NAME ==== Getopt::Std - Process single-character options with option clustering SYNOPSIS ======== use Getopt::Std; # Classical usage, slightly extended: # - for options that take an argument, return only the last one # - for options that don't, return a string containing the option # name as many times as the option was specified my Str:D %opts = getopts('ho:V', @*ARGS); CATCH { when X::Getopt::Std { .message.note; usage } }; version() if %opts; usage(True) if %opts; exit(0) if %opts{}:k; my $outfile = %opts // 'a.out'; # "All options" usage: # - for options that take an argument, return an array of all # the arguments supplied if specified more than once # - for options that don't, return the option name as many times # as it was specified my %opts = getopts-all('o:v', @*ARGS); $verbose_level = %opts.elems; for %opts -> $fname { process_outfile $fname; } # Permute usage (with both getopts() and getopts-all()): # - don't stop at the first non-option argument, look for more # arguments starting with a dash # - stop at an -- argument my Str:D %opts; %opts = getopts('ho:V', @*ARGS, :permute); DESCRIPTION =========== This module exports the `getopts()` and `getopts-all()`> functions for parsing command-line arguments similarly to the POSIX getopt(3) standard C library routine. The options are single letters (no long options) preceded by a single dash character. Options that do not accept arguments may be clustered (e.g. `-hV` for `-h` and `-V`); the last one may be an option that accepts an argument (e.g. `-vo outfile.txt`). Options that accept arguments may have their argument "glued" to the option or in the next element of the arguments array, i.e. `-ooutfile` is equivalent to `-o outfile`. There is no equals character between an option and its argument; if one is supplied, it will be considered the first character of the argument. If an unrecognized option character is supplied in the arguments array, `getopts()` will throw an exception. Otherwise it will return a hash with the options found in the arguments array. The key in the returned hash is the option name (e.g. `h` or `o`); the value is the option argument for options that accept one or the option name (as many times as it has been specified) for options that do not. FUNCTIONS ========= * sub getopts sub getopts(Str:D $optstr, @args, Bool :$nonopts, Bool :$permute, Bool :$unknown) returns Hash[Str:D] Look for the command-line options specified in `$optstr` in the `@args` array. Return the options found in a hash, leave only the non-option arguments in the `@args` array. Note that if an option is specified more than once on the command line, `getopts()` will only record the last argument in the returned hash; see also the `getopts-all()` function below. The `:permute` flag specifies whether option parsing should stop at the first non-option argument, or go on and process any other arguments starting with a dash. A double dash (--) stops the processing in this case, too. The `:unknown` flag controls the handling of unknown options - ones not specified in the `$optstr`, but present in the `@args`. If it is false (the default), `getopts()` will throw an exception; otherwise, the unknown option character will be present in the returned hash as an argument to a `:` option and `getopts()` will still succeed. This is similar to the behavior of some `getopt(3)` implementations if `$optstr` starts with a `:` character. The `:nonopts` flag makes `getopts()` treat each non-option argument as an argument to an option with a character code 1. This is similar to the behavior of some `getopt(3)` implementations if `$optstr` starts with a `-` character. The `:permute` flag is redundant if `:nonopts` is specified since the processing will not stop until the arguments array has been exhausted. Throws an `X::Getopt::Std` exception if an invalid option string has been specified or an unknown option has been found in the arguments array. Current API available since version 1.0.0. * sub getopts-all sub getopts-all(Str:D $optstr, @args, Bool :$nonopts, Bool :$permute, Bool :$unknown) returns Hash[Array[Str:D]] Same as the `getopts()` function, but all the returned values are arrays containing all the specified arguments if any options have been specified more than once. For example, the command line -vI foo -I bar -v, matched against an option string of I:v, would produce `{ :I :v }` with `getopts()` and `{ :I(['foo', 'bar']) :v(['v', 'v']) }` with `getopts-all()`. Current API available since version 1.0.0. AUTHOR ====== Peter Pentchev <[roam@ringlet.net](mailto:roam@ringlet.net)> COPYRIGHT ========= Copyright (C) 2016, 2017, 2020 Peter Pentchev LICENSE ======= The Getopt::Std module is distributed under the terms of the Artistic License 2.0. For more details, see the full text of the license in the file LICENSE in the source distribution.