Provided by: clig_1.9.11.1-3_all bug
 

NAME

        clig - generate a command line parser and/or basic manual page
 

SYNOPSIS

        clig [-t types] [-o outprefix] [-m manFile] [-mx manExt] [-d] infile
 

OPTIONS

        -t     the  types  of output to generate. Currently supported types are
               ‘C’, ‘tcl’ and ‘man’,
               1 or more String values
               Default: ‘C’ ‘man’
 
        -o     name of .c and .h file if type C is  requested  Default:  infile
               with suffix removed,
               1 String value
 
        -m     manual  page  to  edit  or  generate  if  type  man is requested
               Default: ‘Name’ specified in input file,
               1 String value
 
        -mx    extension of manual page,
               1 String value
               Default: ‘.1’
 
        -d     generate the function showOptionValues if type C is requested  .
 
        infile name of file which contains the command line specification.
 

DESCRIPTION

        Clig  reads  infile  and  creates the output as requested by option -t.
        Most often you will just use the  default  to  create  a  command  line
        interpreter  for  your  C  program  as well as the skeleton of a manual
        page. One of the main reasons to use clig is, that besides the  command
        line  interpreter,  a usage() function and a manual page are generated,
        which are always up-to-date with respect to the options actually under‐
        stood by the program.
 
        Currently,  options  of  type Flag, String, Int, Long, Float and Double
        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 val‐
        ues can be specified and will be returned by the generated command line
        interpreter if necessary. In addition, for floating point  and  integer
        options,  a  range  can  be declared, and the interpreter will exit the
        program with an error message, if the option’s  argument  lies  outside
        the given range.
 
        Clig  is  implemented in Tcl and infile 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 in section "DESCRIPTION FILE" and in the manual pages  clig_*  as
        noted  in the section “SEE ALSO”. (I admit that this is probably a lie,
        because under ‘normal circumstances’ infile may contain  syntax  errors
        resulting in really tcl-ish error messages.)
        The  description-file, infile, is a line-oriented ascii-file. Each line
        contains a command which either describes an option or specifies  addi‐
        tional  information  necessary to generate the command line interpreter
        or the manual page.  A command starts with the command-name followed by
        mandatory  parameters  and  possibly followed by options.  If a command
        does not fit on a line, it may be continued on the  next  line  if  the
        previous line is terminated with a backslash (\).
 
        The commands are described in detail in their own manual pages, but let
        us consider a simple example, e.g. a  command  to  describe  an  option
        named  -fs  which wants exactly one parameter of type float and will be
        used in your program as a font size. (Note the backslash  on  the  next
        line!)
 
               Float -fs fontsize \
                   {size of font in points} -d 11.0 -r 8.0 19.5
 
        The command’s name is Float.  It has three fixed parameters: The first,
        -fs, is the string to be detected by the command line interpreter.  The
        second,  fontsize,  is  the name of a variable your program will use to
        receive the value found on the command line.  The third parameter, i.e.
        everything  between  the  braces,  is a string which will be printed by
        usage().  The -d (for default) specifies that fontsize will be  set  to
        the  default  of 11.0, if -fs is not found on the command line. With -r
        (for range) you make sure that the command line interpreter will refuse
        any values for -fs which are not within the given range.
 
    Mandatory Commands
        The  description  file infile must contain the commands Name and Usage.
        The first gives a name to your program and the second declares a  short
        (one-line)  description for it. Both pieces of information will be used
        in the usage()-message as well as in the manual page.
 
    Other Commands
        Please read the manual pages listed under "SEE ALSO" below which  start
        with  clig_ to find a detailed description of all commands available in
        the description  file  infile.   An  example-infile  can  be  found  as
        /usr/share/doc/clig/example/cmdline.cli.
        Clig generates the files outprefix.c and outprefix.h, where outprefix.h
        contains all declarations necessary to use the services defined in  the
        outprefix.c.  If a prefix is not given on the command line, it defaults
        to the name of the input file with any suffix removed.
 
    parseCmdline
        The output files implement a command line interpreter with  the  proto‐
        type
 
               Cmdline *parseCmdline(int argc, char **argv);
 
        which  is  meant  to  be called by your main() to interpret the command
        line given as argc and argv.
 
    usage
        The output files also implement the function
 
               void usage(void);
 
        custom made from the information in infile.  IF parseCmdline()  encoun‐
        ters  an  undeclared  option  on the command line, it immediately calls
        usage().  Therefore you should normally declare neither -h  nor  --help
        as options for your program so that usage-message can be requested with
        any of these options. Normally it is  not  necessary  to  call  usage()
        directly, but it is possible.
 
    Cmdline
        The  type Cmdline, a pointer to which is returned by parseCmdline(), is
        also declared in the generated header file. It is custom-made according
        to  what is found in infile.  If, for example, infile contains the dec‐
        laration
 
          Float -pi pi {your personal approximation of pi}
 
        the structure will have the three slots piP, pi and piC, where piP is a
        boolean  set  to 1 if and only if the option -r is found on the command
        line. In that case piC contains the number of parameters found for  -r.
        The  parameters  found  are  stored  in pi itself. It is either of type
        float* or float depending on whether option -r may  at  all  have  more
        than  one  argument. In the example above, this is not the case, but if
        you declare
 
          Float -ival ival {interval to consider} -c 2 2
 
        in infile, ival must store 2 values and consequently it will be of type
        float* with sufficient memory allocated.
 
    Program
        To  be conveniently available for error message and for use in usage(),
        parseCmdline() will also set the global variable
 
               char *Program;
 
        to the tail of argv[0].
 
    showOptionValues
        If so requested with option -d, the output will contain a function
 
               void showOptionValues(void);
 
        which can be called after parseCmdline() to print the structure Cmdline
        to stdout. This is merely for debugging purposes.
 
    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("Program = ‘%s’\n", Program);
 
            /*****
              Your code goes here. Option parameters and cleaned-up
              argc and argv are referenced with cmd->...
            *****/
 
            return 0;
          }
        In  fact,  output  type tcl is not yet supported. However this does not
        mean you cannot use ::clig to  instrument  your  Tcl-scripts.  It  only
        means  that  you  must  have  ::clig  installed  on the machine were an
        instrumented script should run. Read clig_parseCmdline(n) to learn  how
        to instrument your Tcl-script with ::clig.
        Clig  can  generate  or edit a manual page in *roff format. The name of
        the manual page can be specified with option -m and its suffix  can  be
        specified  with -mx.  By default, the name will be the string specified
        with the Name-command in the description file and the default suffix is
        .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.
        clig_Commandline(7), clig_Description(7), clig_Double(7), clig_Flag(7),
        clig_Float(7),  clig_Int(7),  clig_Long(7), clig_Name(7), clig_Rest(7),
        clig_String(7), clig_Usage(7), clig_Version(7), clig_parseCmdline(7)