Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
clig(1)			      Programmer's Manual		       clig(1)

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

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

       -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 De-
	      fault: `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.

       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 in-
       terpreter 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 understood
       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  be-
       low  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

	      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 us-
       age().  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

       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.

       The  output  files implement a command line interpreter with the	proto-

	      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.

       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 us-
       age().	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() di-
       rectly, but it is possible.

       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-

	 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.

       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].

       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);

	   /* 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  in-
       strumented 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

       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>


	 .\" 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-

       clig_Rest(n),  clig_Flag(n),  clig_Double(n),  clig_Float(n), clig_Ver-
       sion(n),	 clig_Usage(n),	 clig_Name(n),	 clig_Int(n),	clig_parseCmd-
       line(n),	 clig_Long(n),	clig_String(n),	 clig_Commandline(n), clig_De-

Clig-manuals			       clig(1)


Want to link to this manual page? Use this URL:

home | help