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 the call exit. If the error handler is NULL, or it returns instead of calling exit, then an exception will be thrown.

The error hander 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=DLFT);
    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