Node: Program Arguments Parsing, Next: , Previous: System Informations, Up: System Procedures



Program Arguments Parsing

STKLOS provides a simple way to parse program arguments with the parse-arguments special form. This form is generally used into the main function in a Scheme script. See SRFI-22 see SRFIs on how to use a main function in a Scheme program.

parse-arguments <args> <clause1> <clause2> ... STKLOS Procedure
The parse-arguments special form is used to parse the command line arguments of a Scheme script. The implementation of this form internally uses the GNU C getopt function. As a consequence parse-arguments accepts options which start with the '-' (short option) or '-' characters (long option).

The first argument of parse-arguments is a list of the arguments given to the program (comprising the program name in the CAR of this list). Following arguments are clauses. Clauses are described later.

By default, parse-arguments permutes the contents of (a copy) of the arguments as it scans, so that eventually all the non-options are at the end. However, if the shell environment variable POSIXLY_CORRECT is set, then option processing stops as soon as a non-option argument is encountered.

A clause must follow the syntax:

          <clause>       => string | <list-clause>
          <list clause>  => (<option descr> <expr> ...) | (else <expr> ...)
          <option descr> => (<option name> [<keyword> value]*)
          <option name>  => string
          <keyword>      => :alternate | :arg | :help
          

A string clause is used to build the help associated to the command. A list clause must follow the syntax describes an option. The <expr>s associated to a list clauses are executed when the option is recognized. The else clauses is executed when all parameters have been parsed. The :alternate key permits to have an alternate name for an option (generally a short or long name if the option name is a short or long name). The :help is used to provide help about the the option. The :arg is used when the option admit a parameter: the symbol given after :arg will be bound to the value of the option argument when the corresponding <expr>s will be executed.

In an else clause the symbol other-arguments is bound to the list of the arguments which are not options.

The following example shows a rather complete usage of the parse-arguments form

          
          #!/usr/bin/env stklos-script
          
          (define (main args)
            (parse-arguments args
               "Usage: foo [options] [parameter ...]"
               "General options:"
                 (("verbose" :alternate "v" :help "be more verbose")
                   (format #t "Seen the verbose option\n"))
                 (("long" :help "a long option alone")
                   (format #t "Seen the long option\n"))
                 (("s" :help "a short option alone")
                   (format #t "Seen the short option\n"))
               "File options:"
                 (("input" :alternate "f" :arg file :help "use <file> as input")
                   (format #t "Seen the input option with ~S argument\n" file))
                 (("output" :alternate "o" :arg file :help "use <file> as output")
                   (format #t "Seen the output option with ~S argument\n" file))
               "Misc:"
                 (("help" :alternate "h" :help "provides help for the command")
                   (arg-usage (current-error-port))
                   (exit 1))
                 (else
               (format #t "All options parsed. Remaining arguments are ~S\n"
                       other-arguments))))
          

The following program invocation

          foo -vs --input in -o out arg1 arg2
          

produces the following output

          Seen the verbose option
          Seen the short option
          Seen the input option with "in" argument
          Seen the output option with "out" argument
          All options parsed. Remaining arguments are ("arg1" "arg2")
          

Finally, the program invocation

          foo --help
          
produces the following output
          Usage: foo [options] [parameter ...]
          General options:
            --verbose, -v               be more verbose
            --long                      a long option alone
            -s                          a short option alone
          File options:
            --input=<file>, -f <file>   use <file> as input
            --output=<file>, -o <file>  use <file> as output
          Misc:
            --help, -h                  provides help for the command
          

Note:

  • Short option can be concatenated. That is,
                   prog -abc
                   

    is equivalent to the following program call

                   prog -a -b -c
                   

  • Any argument following a '-' argument is no more considered as an option, even if it starts with a '-' or '-'.
  • Option with a parameter can be written in several ways. For instance to set the output in the bar file for the previous example can be expressed as
    • --output=bar
    • -o bar
    • -obar

arg-usage port STKLOS Procedure
arg-usage as-sexpr STKLOS Procedure
This procedure is only bound inside a parse-arguments form. It pretty prints the help associated to the clauses of the parse-arguments form on the given port. If the argument as-sexpr is passed and is not #f, the help strings are printed on port as S-exprs. This is useful if the help strings need to be manipulated by a program.