clig

CLIG(1)                       Programmer's Manual                      CLIG(1)



NAME
       clig - Command Line Interface Generator

SYNOPSIS
       clig clifile [-o outprefix] [-m manpage] [-d]


OPTIONS
       -o     Clig generates a .c and a .h file. Their name-prefix, i.e.
              without the .c or .h, can be specified by -o. By default the
              name is clifile without suffix.


       -m     is used to define the name of the manual page to generate or
              edit. The default is equal to the string specified with the
              Name-command in clifile suffixed with .1


       -d     in addition to the command-line parser, the generated .c-file
              contains the function

                void showOptionValues(void)

              which, when called after calling parseCmdline(), will print all
              parameters defined by default or found on the command line.
              ShowOptionValues() is mainly used for debugging purposes.



EXAMPLE
       An example demonstrating features of clig is the file
       `/usr/local/share/doc/clig/cmdline.cli'. Together with `main.c' and
       `makefile' in the same directory you can construct an example program
       to play with.


DESCRIPTION
       One of the main reasons to use clig is, that besides the command line
       parser a usage() function and a manual page are generated, which are
       always up-to-date with respect to the options actually understood by
       the program.

       From the description in clifile, clig generates C source code, which is
       put into outprefix.c and outprefix.h.  The source code contains a
       command line parser with the prototype

              Cmdline *parseCmdline(int argc, char **argv)

       which returns its result in a structure of type Cmdline.  The section
       `DESCRIPTION FILE' details, which variables will be found in Cmdline.

       Besides parseCmdline(), the function

              void usage(void)

       is generated and will be called by the command-line parser, if the
       command line contains obvious errors. An example main() function which
       calls the parser is shown in the section `EXAMPLE MAIN PROGRAM'.

       Additionally, clig generates or edits a manual page. It fills the
       contents of the sections NAME, SYNOPSIS and OPTIONS with information
       from clifile.  See the section `MANUAL PAGE GENERATION' for more
       details.

       The structure Cmdline and the functions parseCmdline(), usage() and
       showOptionValues() (see below), will be declared in outprefix.h.  In
       addition, outprefix.c defines the external variable char* Program,
       which is set equal to argv[0] by parseCmdline().

       Currently, options of type flag, string, floating point and integer are
       supported. Except for flag options, all option-descriptions allow to
       specify how many arguments are expected for the option and whether the
       option is mandatory or not. For non-mandatory options, default values
       can be specified and will be returned by parseCmdline() if necessary.
       In addtion, for floating point and integer options, a range can be
       declared, and the parser will exit the program with an error message,
       if the option's argument lies outside the given range.

       In some applications where files are created by programs with
       complicated command lines, it is often desireable to store the full
       command line in the generated file for documentation purposes.
       Therefore clig can generate code to concatenate the whole command line
       into one string before it is parsed and store it in a variable in the
       generated structure.  (See command Commandline in section `DESCRIPTION
       FILE' for details.)

       Clig is implemented in Tcl and clifile actually contains tcl-code, but
       under normal circumstances the user does not need to know anything
       about tcl, because the syntax of the description-file is described
       below. (I admit that this is probably a lie, because under `normal
       circumstances' clifile may contain syntax errors resulting in really
       tcl-ish error messages.)


DESCRIPTION FILE
       The description-file, clifile, is a line-oriented ascii-file. Each line
       contains a command which either describes an option or specifies
       additional information necessary to generate parseCmdline(), usage() ,
       showOptionValues() and the manual page.  A command starts with the
       command-name followed by mandatory parameters and possibly followed by
       optional parameters.  If a command does not fit on a line, it may be
       continued on the next line if the previous line is terminated by a
       backslash (\).

       Before the commands are described in detail, let's consider a simple
       example, e.g. a command to describe a flag option named -v which is
       meant to instruct the program to operate verbosely: (Note the backslash
       on the next line!)

              Flag -v verbose \
                  {verbose operation generating blurb}

       The command's name is Flag.  It has three parameters: The first, -v, is
       the string to be detected by the command line parser. The second,
       verbose, is the name of a variable in the structure Cmdline which will
       be set by the parser, if -v is on the command line. (Actually the
       variable's name will be verboseP.  More about that later.) The third
       parameter, i.e. everything between the braces, is a string which will
       be printed by usage().

       In general, every parameter of a description-command should be enclosed
       in braces, as soon as it contains white space.

       The detailed description of all commands follows. As usual, parameters
       enclosed in brackets are optional.


   MANDATORY COMMANDS
       The description file must contain at least the following two commands:

       Name program-name
              The Name-command specifies the name of the program. The string
              program-name is used in the generated manual page and also
              specifies the default name of the manual page. However the
              specified name is not used anywhere in the C-code, because use
              of argv[0] is preferred there.  A trivial but sufficient example
              would be

                Name doit


       Usage one-liner
              The Usage command specifies a one line description of the
              program's intent and function. The string one-liner is printed
              --- besides other sutff --- by the generated function usage().
              (Remember to enclose one-liner in braces.) A (not so) typical
              example would be

                Usage {program to delete your home directory}

              In fact, as of version 1997-07-27, the one-liner can be longer
              than one line. Best results are obtained, if one-liner is not
              put in braces but is surrounded by double quotes. The quoted
              string may than contain newlines. Clig automatically adds
              backslashes where necessary in the generated C-code so that the
              C-compiler does not go wild.



   STRING OPTIONS
       String option variable usage [ count=lo,hi ] [  mandatory |
       default=values ]

       The String command declares option to have zero or more string
       arguments. The structure Cmdline will contain the entries variable,
       variableP and variableC.  The value of variableP will be set nonzero,
       if the option was found on the command line.  If the optional parameter
       count= is not present, variable is of type char* and will point to the
       string found after the option. The parser will abort the program, if
       there is no string after the option.

       The parameter usage specifies a string printed by usage() as a
       description of the option.

       The optional parameter count=lo,hi declares, how many strings are
       expected as arguments to option.  An example is

              {count=3,7},

       telling the parser that at least three and at most seven strings must
       be present after the option. As a special case, the upper bound may be
       oo, indicating that there is no upper limit for the number of strings
       expected after option.  If the count allows more than one option
       argument (hi>1), the type of Cmdline.variable will be char**.  If the
       count=-parameter allows at most one option argument, the type of
       Cmdline.variable will be char*.  In both cases, the value of
       Cmdline.variableC will be set to the number of option arguments found.

       The optional parameter mandatory tells the parser, that this option
       must be present. The parser will print an error message and terminate
       the program, if the option is not on the command line. The parameter
       mandatory cannot be use together with default=values.

       The optional parameter default=values specifies one or more default
       values to be returned in Cmdline.variable if option is not on the
       comand line. In main(), no difference can be detected  between actual
       command line arguments and default values inserted by the parser.

       Example use of String:

         String -l labels {labels for x and y-axis} \
             {count = 2,2} \
             {default = {samples} {f in Hz} }

       Please note how each default value is enclosed in braces. Actually
       samples need not be enclosed in braces here, since it contains no
       whitespace.  The parameter {count = 2,2} specifies that -l must be
       followed by exactly two strings.



   FLOAT OPTIONS
       Float option variable usage [ count=lo,hi ] [  mandatory |
       default=values ] [ range=lo,hi ]

       The Float command declares option to have zero or more floating point
       arguments. The description of variable, usage, count= and mandatory
       applies as for the String-command.  The type of Cmdline.variable is
       float, if there is no count=-parameter or if it allows at most one
       option argument. It is float* otherwise.

       The optional parameter range=lo,hi specifies a range for the option
       arguments. The special values -oo for lo and oo for hi are recognized.
       As an example,

              {range = -oo,1.0}

       specifies, that each option argument must be less or equal to 1.0.  If
       the command line parser finds an argument of option which is not in the
       given range, it prints a suitable error messages and exits the program.

       WARNING: The implementation of the default=-parameter is currently
       incomplete insofar, as the specified default values are not checked by
       clig, i.e. the following would go unnoticed:

              {default = 1.0} {range = 500.0, 600.0}

       In this case, if option is not on the command line, main() would find
       in Cmdline.variable the out-of-range value 1.0. (Maybe this is a
       feature?)


       Example use of Float:

         Float -p prob {list of probabilities adding up to one} \
             {range = 0.0, 1.0}  {default = 0.1 0.2 0.7} \
             {count = 1,oo}

       Please note, that the additional constraint requiring the values
       summing to 1.0 cannot be checked by the parser, but must be checked by
       your main() function.



   INT OPTIONS
       Int option variable usage [ count=lo,hi ] [  mandatory | default=values
       ] [ range=lo,hi ]

       The Int command declares option to have zero or more integer arguments.
       The description of variable, usage, count=, mandatory and range=
       applies as for the Float-command.  Even the note about the unchecked
       default values applies.  However, the type of Cmdline.variable is int
       or int* depending on the count=-parameter.

       Example use of Int:

         Int -b blocksize {size of internal buffer} \
             {range = 1024,oo} \
             {default = 1024}




   FLAG OPTIONS
       Flag option variable usage

       The Flag command declares an option without any parameters. The command
       line parser merely checks for the existence of option on the command
       line. If it is found, the parser returns a nonzero value in
       Cmdline.variableP as for all other option types. However, there are no
       variables named Cmdline.variable and Cmdline.variableC in the structure
       returned to main().

       Example use of Flag:

         Flag -v verbose {verbose operation}



   OTHER COMMANDS
       Rest name usage [ count=lo,hi ]

         The Rest command specifies, what the parser should do with command
         line arguments not associated with any option. If clifile does not
         contain a Rest command, the parser will generate an error message for
         those arguments and terminate the program. If Rest is present, non-
         option arguments are left in char** Cmdline.argv while their number
         is recorded in int Cmdline.argc.  The parameters name and usage are
         printed by usage().  The optional count=-parameter works as described
         for the String command. It does not, however, influence the type of
         Cmdline.argv, because this is always set equal to argv+1, where argv
         is the value passed to parseCmdline().

         Example use of Rest:

           Rest infiles {input files} {count = 1,oo}


       Commandline argvstr

         If you want to record the whole command line of a program in one of
         its output files for documentation purposes, this command comes in
         handy. If clig finds it in the description file it generates code to
         concatenate all command line arguments in one string. The code is
         called automatically within the function parseCmdline() just before
         the command line is actually parsed. The result is stored in the
         structure returned by parseCmdline() in entry argvstr.

         Example use of Commandline:

           Commandline tool

         In your main() you can access the whole command line as one string
         like this:
            ...
           Cmdline *cmd = parseCmdline(argc, argv);
           printf("Full command line is `%s'\n", cmd->tool);
            ...

       Version version
         The Version command specifies a string to be used as a version-
         identification of the generated parser. Currently it is merely
         printed as part of the usage-information. An example using my
         favorite type of version numbers would be

           Version 1995-08-22


       Description description
         The Description command should not be used. Instead, the respective
         section in the generated manual page should be filled out. The main
         reason for this advice is, that clig copies description AS IS into
         the manual page, so it can be typed into the manual page file in the
         first place. Please remember that the generated manual page needs
         some hand-tuning anyway, because for example the `SEE ALSO'-section
         cannot be generated. Since this command should not be used, no
         example is given.


EXAMPLE MAIN PROGRAM
       The following example demonstrates the use of the command line parser,
       provided that outprefix = cmdline and that clig was called with option
       -d to generate the function showOptionValues().

         #include <cmdline.h>

         int main(int argc, char **argv)
         {
           Cmdline *cmd = parseCmdline(argc, argv);
           showOptionValues();

           /* Program is set by parseCmdline */
           printf("argv[0] = `%s'\n", Program);

           /*****
             Your code goes here. Option parameters and cleaned-up
             argc and argv are referenced with cmd->...
           *****/

           return 0;
         }


MANUAL PAGE GENERATION
       Clig will always generate or edit a manual page in *roff format. The
       name of the manual page file can be specified with option -m.  By
       default, the file name will be the string specified with the Name-
       command in the description file suffixed with .1.

       If the manual page file exists, clig edits specially marked sections of
       the file by filling in up-to-date information. If the file does not yet
       exist, it copies a template file into it and then edits the template in
       the same way.

       Clig is able to fill out the manual page sections `NAME', `SYNOPSIS',
       `OPTIONS' and, in a very limited way, `DESCRIPTION'. In addition it
       will supply a default title macro (.TH). The lines of the manual page
       file which are replaced by clig must be clearly marked by matching
       pairs of tag lines like

         .\" cligPart <section>

       and

         .\" cligPart <section> end

       where <section> is one of the section names listed above.

       The idea is, that you edit the manual page, while clig fills in the
       parts that can be deduced from the description file. If you don't like,
       what clig fills in, simply remove both tag-lines of a section and clig
       will leave it alone. You certainly want to do this for the DESCRIPTION-
       section.



BUGS
       The description file clifile is read by clig with the tcl-command
       source, since the option descriptions are actually tcl-procedures. This
       has the effect of irritating non-TCLers with uncomprehendable error
       messages, if there are syntax errors in the description.

       The generated C-code might contain functions which are never used.

       See `WARNING:' above for another bug.

       Non-TCLers might feel uncomfortable with the description syntax. In
       particular, forgetting to enclose parameters in braces will cause
       strange errors.

       The function showOptionValues() does not ascertain that parseCmdline()
       was called before.

       Possibly some more...


FUTURE FEATURES
       o enumeration type options,
       o file type options,
       o `Rest'-command not only with string parameters,
       o better error messages,
       o generation of a Tcl/Tk-GUI driving the specified program,


NO-FUTURE FEATURES
       o Tcl/Tk-GUI for clig,
       o neural net type command line parser,
       o fuzzy logic command line parser,
       o inheritance hierarchy for command line options,
       o visual basic support,
       o command lines shorter than 128 characters,
       o generation of WINDOOF program group,
       o OLE, NILS or JENS support,
       o automatic buzzword implementation.


SEE ALSO
       Tcl(n) tclsh(1)



Kir                                  1.0.2                             CLIG(1)