MKCMD(1L)

NAME
mkcmd - make a command line option parser

SYNOPSIS
mkcmd [-AG] [-I directory] [-m manpage] [-n name] [files]
mkcmd -h
mkcmd -T
mkcmd -V

DESCRIPTION
Mkcmd builds a command line option parser from descriptions in the named files, the generated C code parses the options described.

The files argument should be either a filename which ends in “.m”, or a single dash “-”. The single dash is taken to represent stdin (so that macro expansion may be done before the file is read by mkcmd).

OPTIONS

-A  Under this option mkcmd generates ANSI-style function headers. This option has not been fully tested.

-G  Under this option mkcmd doesn't guess which of <string.h> or <strings.h> to include, or is the system has <stdlib.h> or not, or if the system supports strerror(3). Rather mkcmd assumes one of the source files includes the appropriate string header, externs for the memory allocation functions malloc(3), realloc(3) and calloc(3), and a definition of strerror(3), if needed.

-h  Print a short help message.

-Idirectory
    Mkcmd searches for the files on the command line first in the current directory, then in a standard place (“/usr/local/share/mkcmd”), then in any directory listed as parameters to this option.

-mmanpage
    Mkcmd outputs a manpage template in the file manpage. This file is not overwritten if it exists. A single dash may be used to send the man page template to stdout.

-nname
    Mkcmd's output is two C source files, normally “prog.c” and “prog.h”. This option changes “prog” to name.

-T  Mkcmd outputs a table of the types it knows how to convert.

-V  Mkcmd outputs a handy version string.

LANGUAGE

This quick reference is meant as reminder. For a complete description of the file format of a mkcmd file see Writing UNIX Command Line Option Parsers.

Options in mkcmd are represented as a conversion from the input syntax (-x parameter) to a C variable. The destination variable is bound to an option letter, or a parametric position on the command line. The conversion takes place as soon as the option (or position) is processed. The unconverted string my be preserved if an identifier, unconv, is also provided. Options are declared as:
	type 'letter' {
		attributes
	}
Variables (buffers for left or right) are declared as:
	type variable "name" [ "unconv" ] {
		attributes
	}

Each conversion mkcmd can construct has a unique keyword. Always overide the generic parameter mnemonic with a more specific parameter attribute.
Conversion types for options and variables
C type | Mkcmd type | Parameter mnemonic
int | boolean
int | toggle
char [dim] | string [dim] | string
char * | pointer | string
int | letter | letter
int | integer | int
unsigned | unsigned | unsigned
long | long | int
double | double | float
f(int, char*) | function | arg
f(int) | action |
int | number | int
char * | accumulate | arg
FILE * | file | file
int | fd | fd

An attribute modifies the option, action, or variable which contains it. The parameter to an attrribute is always a string in quotes, either double (") or single ('). Input quoting rules are similar to C's.

Since the defaults values are ugly, each attribute list should contain at least the named and help attribute.
Option attributes for mkcmd
Attribute | description | escape
named ident [unconv] | bind C variable ident to option value | %n
local | C variable is local to routine
global | C variable is global
static | C variable is storage class static
hidden | hide option from users
aborts C-statement | stop program after this option
excludes list | these option are mutually exclusive
from file | include file for declaration of named
help string | provide for run-time help | %h
initializer value | default value | %i
initializer getenv ident | read default value from $ident
initializer dynamic expr | set default value to expr
parameter param | provide mnemonic parameter name | %p
once | option may only be given once
stops | option quits dash processor
ends | option ends the command line
track [ variable ] | set variable if option presented | %U
update C-statement | convert value specially
user C-statement | run after update
verify [ C-statement ] | validate data
before C-statement | initialize before option processing
after C-statement | cleanup after option processing

The global switches act like attributes for the whole parser.
Global switches for mkcmd
Switch | Repeat Description (Percent Escape)
basename | n | chop progname
basename name opts | y | when progname is name force opts
basename otherwise opts | n | when no match for progname force opts
comment text | y | insert header comments
excludes options | y | mutually exclusion options
from file | y | a #include file we must have
getenv env | n | read env for options
initializer C-statements | y | set up some external facility
mix | y | mix options and arguments (deprecated)
named ident | n | set ident to hold progname (%b)
prototype string | n | format default function names
routine main | n | name for main
template string | n | format default variable names
terse ident | n | name the usage string (%t)
usage ident | n | name the usage function (%u)
vector ident | n | name the help vector (%v)

Special control points are declared as:
	action {
		attributes
	}

Each control point is activated either to convert some data from a fixed position on the command line, or to note that a phase of command line processing is ended. Control points which represent errors (badoption, noparameter) usually trigger an abort attribute thus they can only happen once.
Special control points for mkcmd
Control | When activated
before | before dash processing
escape | when prefix is given
number | when -digits is given
noparameter | when a parameter-requiring option is last on the line
badoption | when an unknown option is given
otherwise | the default case in the switch (unused normally)
after | after dash processing
left | process left justified parameters
right | process right justified parameters
zero | when zero arguments are left
list | process the list of arguments
every | process every argument in turn
exit | end processing

The activation of the aborts attribute's code is conditional for left and right. These are executed only if manditory positional parameters are missing. The default action in each case is a words message to stderr.

The spelling of the escape prefix may be specified as
	escape [ prefix ] {
		...
	}
and the type of the escaped data may be specified as:

    escape [ prefix ] type ...

By default the every control point processes arguments via a function. An alternate type for the arguments may be specified as:

    every type ...

This is true for list as well.

The justified parameter lists for left or right may contain a single level of brackets indicating optional parameters. For example in the declaration:

    left "name1" [ "name2" ] ...

name1 is manditory and name2 is optional. The brackets may be repeated, but not nested.

EXAMPLES
The file std_help.m provides a very standard UNIX help system. This file should be used for all products unless there is an overwhelming reason not to use it. The normal invocation of mkcmd is therefore:

    mkcmd std_help.m tool.m

where tool.m is the name of the file containing the description of options to be parsed. In a makefile one might wish to perform a minimal update of the parser. This can be done with:

main.h: main.c
main.c: tool.m
    mkcmd std_help.m tool.m
    -(cmp -s prog.c main.c || (cp prog.c main.c && echo main.c updated))
    -(cmp -s prog.h main.h || (cp prog.h main.h && echo main.h updated))
    rm -f prog.[ch]

BUGS
None known.

AUTHOR
Kevin Braunsdorf
Federal Express
ksbrauns@fedex.com

SEE ALSO
make(1), cc(1), getopt(3l)
Writing Command Line Option Parsers.