SLSH Library Reference (version 2.3.0): Command Line Parsing Functions

Next Previous Contents

## 3. Command Line Parsing Functions

These functions are defined in the `cmdopt.sl` file.

## 3.1 cmdopt_new

Synopsis

  Create a cmdopt object for parsing command-line options

Usage

  `obj = cmdopt_new (Ref_Type error_routine)`

Description

  This function creates an returns an object that may be used by the `cmdopt_process` function to parse command line arguments. The `cmdopt_new` function takes a reference to an error handling function that will get called upon error. In most cases, this function should print out the error message, display a usage message, and then call `exit`. If the error handler is `NULL`, or it returns instead of calling exit, then an exception will be thrown.

  The error handler must be defined to take a single string argument (the error message) and must return nothing.

Example

  > `

  >        require ("cmdopt");
  >        private define help_callback ()
  >        {
  >          () = fputs ("Usage: pgm [options] infile\n", stderr);
  >          () = fputs ("Options:\n", stderr);
  >          () = fputs (" -h|--help           Show this help\n", stderr);
  >          () = fputs (" -v|--verbose        Increase verbosity level\n", stderr);
  >          () = fputs (" -o|--output         Output filename [stdout]\n", stderr);
  >          exit (1);
  >        }
  >        private define error_handler (text)
  >        {
  >           () = fprintf (stderr, "%s\n", text);
  >           help_callback ();
  >        }
  >        define slsh_main ()
  >        {
  >           variable verbose = 0;
  >           outfile = "-";   % stdout
  >           variable c = cmdopt_new (&error_handler);
  >           cmdopt_add (c, "v|verbose", &verbose; inc);
  >           cmdopt_add (c, "h|help", &help_callback);
  >           cmdopt_add (c, "s:o|output", &outfile; type="str");
  >           variable iend = cmdopt_process (c, __argv, 1);

  >           if (verbose) message ("some informative message");
  >           variable fp = stdout;
  >           if (outfile != "-") fp = fopen (outfile, "w");
  >             .
  >             .
  >         }

  > `

See Also

  `cmdopt_add, cmdopt_process`

## 3.2 cmdopt_process

Synopsis

  Process the command-line options

Usage

  `Int_Type cmdopt_process (optobj, argv, istart)`

  > `

  >        Struct_Type optobj;
  >        Array_Type argv;
  >        Int_Type istart

  > `

Description

  This function parses the command line arguments in the string array `argv` according to the rules specified by the `optobj` object, previously allocated by `cmdopt_new`. The array of strings is processed starting at the index specified by `istart`. The function returns the index of the array element where parsing stopped. Upon error, the function will call the error handler established by the prior call to `cmdopt_new`.

Example

  > `

  >         define slsh_main ()
  >         {
  >               .
  >               .
  >            optobj = cmdopt_new (...);
  >            cmdopt_add (optobj, ...);
  >               .
  >               .
  >            variable iend = cmdopt_process (optobj, __argv, 1);
  >               .
  >               .
  >         }

  > `

Notes

  This function may also be called in an object-oriented style using the `process` method:

  > `

  >            optobj = cmdopt_new (...);
  >            optobj.add (...)
  >            iend = optobj.process (__argv, 1);

  > `

See Also

  `cmdopt_add, cmdopt_new`

## 3.3 cmdopt_add

Synopsis

  Add support for a command-line option

Usage

  `cmdopt_add (optobj, optname, addr [,...] [;qualifiers])`

  > `

  >        Struct_Type optobj;
  >        String_Type optname;
  >        Ref_Type addr;

  > `

Description

  This function adds support for a command-line option to `optobj` and specifies how that option should be handled. Handling an option involves setting the value of a variable associated with the option, or by calling a function upon its behalf.

  For clarity, assume a command-line option can be specified using the single character `f` or by the longer name `foo`. Then the rules for calling `cmdopt_add` for the various flavors options supported by this interface and how the option may be specified on the command line are as follows:

  Options that set a variable `v` to a value `val`:

  > `

  >         cmdopt_add (optobj, "f|foo", &v; default=val);
  >         cmdline: pgm -f ...
  >         cmdline: pgm --foo ...

  > `

  Options that increment an integer variable `v`:

  > `

  >         cmdopt_add (optobj, "f|foo", &v; inc);
  >         cmdline: pgm -f -f ...       % In these examples, v
  >         cmdline: pgm --foo --foo ... % gets incremented twice

  > `

  Options that bitwise-or an integer variable `v` with `FLAG`:

  > `

  >         cmdopt_add (optobj, "f|foo", &v; bor=FLAG);
  >         cmdline: pgm -f ...       % v = v | FLAG
  >         cmdline: pgm --foo ...    % v = v | FLAG

  > `

  Options that bitwise-and an integer variable `v` with `MASK`:

  > `

  >         cmdopt_add (optobj, "f|foo", &v; band=MASK);
  >         cmdline: pgm -f ...       % v = v & MASK;
  >         cmdline: pgm --foo ...    % v = v & MASK;

  > `

  The above two options may be combined:

  > `

  >         cmdopt_add (optobj, "f|foo", &v; bor=FLAG1, band=~FLAG2);
  >         cmdline: pgm -f ...       % v &= ~FLAG2; v |= FLAG1;

  > `

  Options that require a value and set `v` to the value VAL.

  > `

  >         cmdopt_add (optobj, "f|foo", &v; type="int");
  >         cmdline: pgm -f VAL ...
  >         cmdline: pgm -fVAL ...
  >         cmdline: pgm --foo VAL ...
  >         cmdline: pgm --foo=VAL ...

  > `

  Options whose value is optional:

  > `

  >         cmdopt_add (optobj, "f|foo", &v; type="string", optional=DFLT);
  >         cmdline: pgm -f ...            % set v to DFLT
  >         cmdline: pgm -fVAL ...         % set v to VAL
  >         cmdline: pgm --foo ...         % set v to DFLT
  >         cmdline: pgm --foo=VAL ...     % set v to VAL

  > `

  For the latter two cases, if the `append` qualifier is used, then instead of assigning the value to the specified variable, the value will be appended to a list assigned to the variable, e.g.,

  > `

  >         cmdopt_add (optobj, "f|foo", &v; type="float", append);

  > `

  Then the command line `pgm --foo=VAL1 -fVAL2 -f VAL3 ...` will result in the assignment to `v` or the 3 element list `{VAL1, VAL2, VAL3}`.

  An option can also be associated with a callback function that get called when the option is handled.

  Options that cause a function to be called with arguments `a0,...`:

  > `

  >         cmdopt_add (optobj, "f|foo", &func, a0...);
  >         cmdline: pgm --foo
  >         cmdline: pgm -f

  > `

  Here `func` should be written with the signature:

  > `

  >         define func (a0, ...) {...}

  > `

  Options that take a value and cause a function to be called with additional arguments `a0,...`:

  > `

  >         cmdopt_add (optobj, "f|foo", &func, a0,...; type="int");
  >         cmdline: pgm --foo=VAL
  >         cmdline: pgm -f VAL
  >         cmdline: pgm -fVAL

  > `

  In this case, `func` should be written as

  > `

  >         define func (value, a0, ...) {...}

  > `

  As the above examples illustrate, the data-type of the value assigned to a variable must be specified using the `type` qualifier. Currently the `type` must be set to one of the following values:

  > `

  >          "str"          (String_Type)
  >          "int"          (Int_Type)
  >          "float"        (Double_Type)

  > `

Notes

  This function may also be called in an object-oriented style using the `add` method:

  > `

  >            optobj = cmdopt_new (...);
  >            optobj.add ("f|foo", &func, a0,...; type="int");

  > `

See Also

  `cmdopt_new, cmdopt_process`

Next Previous Contents