clig(1) Programmer's Manual clig(1)NAMEclig - generate a command line parser and/or basic manual page
SYNOPSISclig [-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.)
DESCRIPTION FILE
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/local/share/doc/clig/example/cmdline.cli.
OUTPUT TYPE C
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;
}
OUTPUT TYPE tcl
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.
OUTPUT TYPE man
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.
SEE ALSOclig_Version(n), clig_Usage(n), clig_Float(n), clig_Int(n), clig_Com‐
mandline(n), clig_Long(n), clig_Flag(n), clig_String(n), clig_Dou‐
ble(n), clig_Name(n), clig_Rest(n), clig_Description(n), clig_parseCmd‐
line(n)Clig-manuals 1.9.11.1 clig(1)
