2.13.1 modclopt
Keywords: onyx

Next: 3. The onyx program Up: 2.13 Module reference Previous: 2.13 Module reference Contents Index

##
2.13.1 modclopt

The modclopt module implements command line option parsing via the clopt class. Both short- and long-style arguments are supported. There are also methods that aid in validating and converting arguments.

An application implements a command line parser by loading the modclopt module, subclassing the clopt class, and defining option-handling methods. At a minimum, this looks something like:

    $modclopt mclass:singleton:load

    $myopts clopt <
    ><
        `--help' {
            `Help yourself' ;error_print
            1 die
        }
    > cdef

    argv myopts:new:parse

There are five option formats. Handler methods ``names'' must be strings. The absence or presence of the ``:'', ``?'', and ``='' characters at the ends of the handler method names determines whether the options take arguments:

``-s'`:
  Handle a short-style argument (`-s`) that has no arguments.
`'-S:'`:
  Handle a short-style argument (`-S`) that must have an argument.
``--long'`:
  Handle a long-style option (`--long`) that has no arguments.
``--Long?'`:
  Handle a long-style option (`--Long`) that has an optional argument.
``--LONG='`:
  Handle a long-style option (`--LONG`) that must have an argument.

The `--` command line argument terminates argument parsing, and any remaining arguments are returned by the parse method.

clopt subclasses vclass.

Table 2.15: clopt summary
Input(s) Method Output(s) | Description
Class-context methods
- new instance | Constructor.
Instance-context methods
argv parse remainder false | Successfully parse argv.
argv parse true | Unsuccessfully parse argv.
errstr error_print - | Print an error.
errstr error_escape - | Handle an error, and unwind to the parse method.
- progname_get progname | Return the program name.
- argv_get argv | Return argv.
- index_get index | Return the current argv index.
- flag_get flag | Return the current option flag.
- arg_get arg | Return the current option argument.
enum arg_enum_get value | Map the current option argument to a value.
- arg_int_get int | Return the current option argument as an integer.
- arg_uint_get uint | Return the current option argument as an unsigned integer.

enum arg_enum_get value:
  Input(s):
    enum:
      A dictionary of string keys with associated values, as well as an optional `$default` key and associated value.
  Output(s):
    value:
      One of the values in enum.
  Error(s):
    stackunderflow.
    typecheck.
  Description:
    Map the current option argument to a value in enum, and return that value. This method is only to be called from within an option handler.
  Example(s):
    `arg_enum_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--verbose?' -
            `--verbose?' {
                `Verbosity: ' print
                <
                    $default true
                    `yes' true
                    `no' false
                > ;arg_enum_get
                1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./arg_enum_get.nx --verbose
        Verbosity: true
        $ ./arg_enum_get.nx --verbose=yes
        Verbosity: true
        $ ./arg_enum_get.nx --verbose=no
        Verbosity: false
        $

- arg_get arg:
  Input(s):
    None.
  Output(s):
    arg:
      A string if an argument was specified, null otherwise.
  Error(s):
    None.
  Description:
    Get the argument string associated with the current flag, or null if no argument was specified. This method is only to be called from within an option handler.
  Example(s):
    `arg_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	;arg_get null ne {
        	    `--foo --> ' print
        	    ;arg_get 1 sprint
        	}{
        	    `--foo\n' print
        	} ifelse
            } bind
        > cdef

        argv myopts:new:parse

        $ ./arg_get.nx --foo --foo= --foo=arg --foo
        --foo
        --foo --> `'
        --foo --> `arg'
        --foo
        $

- arg_int_get int:
  Input(s):
    None.
  Output(s):
    int:
      An integer.
  Error(s):
    None.
  Description:
    Return the current option argument as an integer. Perform input validation, and cause the parse method to return an error if the argument cannot be converted to an integer. This method is only to be called from within an option handler.
  Example(s):
    `arg_int_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	`--foo --> ' print
        	;arg_int_get 1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./arg_int_get.nx --foo=42 --foo=+43 --foo=-44 --foo=hi
        --foo --> 42
        --foo --> 43
        --foo --> -44
        arg_int_get.nx: Error parsing value `hi' for option --foo
        $

- arg_uint_get uint:
  Input(s):
    None.
  Output(s):
    uint:
      An unsigned integer.
  Error(s):
    None.
  Description:
    Return the current option argument as an unsigned integer. Perform input validation, and cause the parse method to return an error if the argument cannot be converted to an unsigned integer. This method is only to be called from within an option handler.
  Example(s):
    `arg_uint_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	`--foo --> ' print
        	;arg_uint_get 1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./arg_uint_get.nx --foo=0 --foo=42 --foo=+43 --foo=-5
        --foo --> 0
        --foo --> 42
        --foo --> 43
        arg_uint_get.nx: Integer must be non-negative for option --foo
        $

- argv_get argv:
  Input(s):
    None.
  Output(s):
    argv:
      An array of strings.
  Error(s):
    None.
  Description:
    Get the argument array that was passed in to the parse method. This method is only to be called from within an option handler.
  Example(s):
    `argv_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	`argv: ' print
        	;argv_get 1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./argv_get.nx --foo -- unprocessed args
        argv: [`./argv_get.nx' `--foo' `--' `unprocessed' `args']
        $

errstr error_escape -:
  Input(s):
    errstr:
      An error string.
  Output(s):
    None (does not return).
  Error(s):
    ioerror.
    stackunderflow.
    typecheck.
  Description:
    Call the error_print method, then clean up from an error, such that the parse method returns an error.
  Example(s):
    `error_escape.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--bang' -
            `--bang' {
        	`This is an arror string' ;error_escape
            } bind
        > cdef

        argv myopts:new:parse {
            `Parse error\n' print
        }{
            `Parse success\n' print
        } ifelse

        $ ./error_escape.nx
        Parse success
        $ ./error_escape.nx --bang
        error_escape.nx: This is an arror string
        Parse error
        $

errstr error_print -:
  Input(s):
    errstr:
      An error string.
  Output(s):
    None.
  Error(s):
    ioerror.
    stackunderflow.
    typecheck.
  Description:
    Print errstr to stderr. This method is only to be called from within an option handler.
  Example(s):
    `error_print.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--bang' -
            `--bang' {
        	`This is an arror string' ;error_print
            } bind
        > cdef

        argv myopts:new:parse

        $ ./error_print.nx
        $ ./error_print.nx --bang
        error_print.nx: This is an arror string
        $

- flag_get flag:
  Input(s):
    None.
  Output(s):
    flag:
      A string that contains the argument, including any leading dashes, but excluding any trailing argument characters.
  Error(s):
    None.
  Description:
    Get the current argument flag. This method is only to be called from within an option handler.
  Example(s):
    `flag_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	`--foo --> ' print
        	;flag_get 1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./flag_get.nx --foo --foo= --foo=blah
        --foo --> `--foo'
        --foo --> `--foo'
        --foo --> `--foo'
        $

- index_get index:
  Input(s):
    None.
  Output(s):
    index:
      Array index of current argument, within the array passed in to the parse method.
  Error(s):
    None.
  Description:
    Get the array index of the current argument, within the array passed in ot the parse method. This method is only to be called from within an option handler.
  Example(s):
    `index_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	`index: ' print
        	;index_get 1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./index_get.nx --foo --foo=42 --foo=
        index: 1
        index: 2
        index: 3
        $

- new instance:
  Input(s):
    None.
  Output(s):
    instance:
      An instance of clopt.
  Error(s):
    None.
  Description:
    Constructor.
  Example(s):

        onyx:0> $modclopt mclass:singleton:load
        onyx:0> clopt:new
        onyx:1> 1 sprint
        -instance=$clopt-
        onyx:0>

argv parse remainder false:
argv parse true:
  Input(s):
    argv:
      An array of strings. The first element in the array is the program path, and the rest of the array is arguments.
  Output(s):
    remainder:
      A subarray of argv that contains any remaining unprocessed arguments.
    false:
      Success.
    true:
      An error occurred during parsing.
  Error(s):
    stackunderflow.
    typecheck.
  Description:
    Parse the arguments contained in argv and call the appropriate argument handler methods. Stop processing when there is an error, the `-` argument is processed, or the entire input array has been processed.
  Example(s):
    `parse.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	;arg_get null ne {
        	    `--foo --> ' print
        	    ;arg_get 1 sprint
        	}{
        	    `--foo\n' print
        	} ifelse
            } bind
        > cdef

        argv myopts:new:parse {
            `Error\n' print
        }{
            `Success.  Remainder: ' print
            1 sprint
        } ifelse

        $ ./parse.nx --foo --foo=bar
        --foo
        --foo --> `bar'
        Success.  Remainder: []
        $ ./parse.nx --foo --foo=bar -- unprocessed arguments
        --foo
        --foo --> `bar'
        Success.  Remainder: [`unprocessed' `arguments']
        $ ./parse.nx --foo bang
        --foo
        Success.  Remainder: [`bang']
        $ ./parse.nx --foo --bang
        parse.nx: Error interpreting option --bang
        --foo
        Error
        $

- progname_get progname:
  Input(s):
    None.
  Output(s):
    progname:
      A string that is the basename of the first string in the argument array passed to the parse method.
  Error(s):
    None.
  Description:
    Get the program name, which is the basename of the first string in the argument array passed to the parse method. This method is only to be called from within an option handler.
  Example(s):
    `progname_get.nx`:

        #!/usr/bin/env onyx

        # Load the clopt module.
        $modclopt mclass:singleton:load

        # Subclass clopt and add option handlers.
        $myopts clopt <
        ><
            #class#
            #- new #instance
            $new {
                ;rnew
                #instance
            } bind

            #instance#
            #- `--foo?' -
            `--foo?' {
        	`progname: ' print
        	;progname_get 1 sprint
            } bind
        > cdef

        argv myopts:new:parse

        $ ./progname_get.nx --foo
        progname: `progname_get.nx'
        $

Next: 3. The onyx program Up: 2.13 Module reference Previous: 2.13 Module reference Contents Index