4.2. kink/ARGV_PARSER

Parses command line arguments.

Usage example:

:ARGV_PARSER.require_from('kink/')
:PROCESS.require_from('kink/')
:Opt = new_val(
  'Loglevel' 'ERROR'
)
:Non_opts = ARGV_PARSER.parse(['--log' 'INFO' 'foo' 'bar']){(:P)
  P.no_arg(['-h' '--help']){
    stdout.print_line('USAGE: voxxx [Options...] [--] [Args...]')
    PROCESS.exit(0)
  }
  P.req_arg(['-L' '--loglevel']){(:Arg)
    Opt:Loglevel <- Arg
  }
  P.on_error{(:Msg)
    stderr.print_line('voxxx: {}'.format(Msg))
    PROCESS.exit(1)
  }
}

stdout.print_line(Opt.Loglevel) # => INFO
stdout.print_line(Non_opts) # => ["foo" "bar"]

Parsing of the options stops when all the words are read, or the special delimiter word "--" is read, or a non-option word is read (only in the strict_order mode).

Words which are not option switches and option arguments are passed to the success handler as a vec, the default implementation of which returns the vec itself.

There are two different shapes of option switches, short and long, and two different arity of option switches, req_arg, opt_arg, and no_arg. Therefore, there are 2x3 = 6 types of option switches.

Shapes:

A short option switch consist of a leading character "-" and a following “switch character”. The switch character cannot be “-”. Example short option switches: "-v" and "-?".

A long option switch consist of a leading "--" and one or more characters. Example long option switches: "--version" and "--no-timestamp". A long option switch can be abbreviated to its prefix if not ambiguous. For example, “--version” can be abbreviated to “--ver” if “--verbose” is not defined.

Arity:

A req_arg switch takes one argument.

In the short shape, the argument for a req_arg switch can be passed as following characters in the word, or the next distinct word. For example, if “-m” is defined as a req_arg switch, both “-mITER” and “-m ITER” mean an option switch “-m” and its argument “ITER”.

In the long shape, the argument for a req_arg switch can be passed after “=” in the word, or the next distinct word. For example, if “--module” is defined as a req_arg switch, both “--module=ITER” and “--module ITER” means an option switch “--module” and its argument “ITER”.

An opt_arg switch takes zero or one argument.

In the short shape, the argument for a opt_arg switch can be passed as following characters in the word,. For example, if “-L” is defined as an opt_arg switch, “-LDEBUG” means an option switch “-L” and its argument “DEBUG”.

In the long shape, the argument for an opt_arg switch can be passed after “=” in the word. For example, if “--loglevel” is defined as a req_arg switch, “--loglevel=DEBUG” means an option switch “--loglevel” and its argument “DEBUG”.

A no_arg switch does not take an argument.

In the short shape, when there is one or more characters after the switch character in the word, the next character is taken as another option switch character. For example, if no_arg option switches "-x" and "-z", and a req_arg switch “f” are defined, and a word "-xzfarchive.tar.gz" is passed as a word, it is equivalent to distinct words "-x", "-z", “-f” and “archive.tar.gz”.

Compatibility:

ARGV_PARSER supports almost equivalent functionality to glibc getopt_long function, with the following differences.

1. getopt_long assumes argv[0] is the name of the program, but ARGV_PARSER handles the elements after the program name.

2. ARGV_PARSER lacks support for the option to equate "-W foo" to "--foo".

4.2.1. ARGV_PARSER.parse(Words ...[$config = {}])

Parses the Words, with configuration specified by $config.

If the parsing completes without an error, the invocation of ARGV_PARSER.parse tail-calls the success handler with the non-opt words. The default action of the success handler is to simply return the non-opt words.

If the parsing results in an error, the invocation of ARGV_PARSER.parse tail-calls the error handler with the error message. The default error handler is `raise`.

$config must take a argv_parser_config as an argument, and configure it.

4.2.2. type argv_parser_config

Config val for ARGV_PARSER.parse.

4.2.2.1. C.on_success($_handle_success)

Sets $_handle_success as a success handler, which is a fun tal-called when the parsing succeeds.

$_handle_success takes a vec of non-opt words. If .on_success is not called, VAL.identity is used as default.

4.2.2.2. C.on_error($_handle_error)

Sets $_handle_error as a error handler, which is a fun tail-called when the parsing causes an error.

$_handle_error takes a message as an arg. If .on_error is not called, `raise` is used as default.

4.2.2.3. C.strict_order

Uses strict_order/POSIX mode.

In this mode, option switches cannot be placed after non-opt args.

4.2.2.4. C.lenient_order

Uses lenient_order/GNU mode.

In this mode, option switches can be placed after non-opt args, unless the special argument “--” is used.

This is the default mode, thus you don't have to call this method explicitly.

4.2.2.5. C.no_arg(Switches $action)

Adds an option which takes no argument, with the Switches.

$action is called with no arg when one of the option Switches is specified.

4.2.2.6. C.opt_arg(Switches $action)

Adds an option which takes optional argument, with the Switches.

$action is called with an empty vec [] when one of the option Switches is specified with no argument.

$action is called with a singleton vec containing an argument, when one of the option Switches is specified with the argument.

4.2.2.7. C.req_arg(Switches $action)

Adds an option which requires an argument, with the Switches.

$action is called with an argument when one of the option Switches is specified with the argument.