next up previous contents index
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 up previous contents index
Next: 3. The onyx program Up: 2.13 Module reference Previous: 2.13 Module reference   Contents   Index
Jason Evans 2005-03-16