DragonFly On-Line Manual Pages
MKCMD(1L) 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.
LOCAL MKCMD(1L)