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

--------------------------------------------------------------

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

--------------------------------------------------------------

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

--------------------------------------------------------------