GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MKCMD (1)

NAME

mkcmd - make a command line option parser

CONTENTS

Synopsis
Description
Options
Language
Examples
Bugs
Author

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:

        typeletter{
                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 typeMkcmd typeParameter mnemonic
intboolean 
inttoggle 
char [dim]string [dim]string
char *pointerstring
intletterletter
intintegerint
unsignedunsignedunsigned
longlongint
doubledoublefloat
f(int, char*)functionarg
f(int)action 
intnumberint
char *accumulatearg
FILE *filefile
intfdfd

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
Attributedescriptionescape
named ident [unconv]bind C variable ident to option value%n
localC variable is local to routine 
globalC variable is global 
staticC variable is storage class static 
hiddenhide option from users 
aborts C-statementstop program after this option 
excludes listthese option are mutually exclusive 
from fileinclude file for declaration of named 
help stringprovide for run-time help%h
initializer valuedefault value%i
initializer getenv identread default value from $ident 
initializer dynamic exprset default value to expr 
parameter paramprovide mnemonic parameter name%p
onceoption may only be given once 
stopsoption quits dash processor 
endsoption ends the command line 
track [ variable ]set variable if option presented%U
update C-statementconvert value specially 
user C-statementrun after update 
verify [ C-statement ]validate data 
before C-statementinitialize before option processing 
after C-statementcleanup after option processing 

The global switches act like attributes for the whole parser.

Global switches for mkcmd
SwitchRepeat Description (Percent Escape)
basenamenchop progname
basename name optsywhen progname is name force opts
basename otherwise optsnwhen no match for progname force opts
comment textyinsert header comments
excludes optionsymutually exclusion options
from fileya #include file we must have
getenv envnread env for options
initializer C-statementsyset up some external facility
mixymix options and arguments (deprecated)
named identnset ident to hold progname (%b)
prototype stringnformat default function names
routine mainnname for main
template stringnformat default variable names
terse identnname the usage string (%t)
usage identnname the usage function (%u)
vector identnname 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
ControlWhen activated
beforebefore dash processing
escapewhen prefix is given
numberwhen -digits is given
noparameterwhen a parameter-requiring option is last on the line
badoptionwhen an unknown option is given
otherwisethe default case in the switch (unused normally)
afterafter dash processing
leftprocess left justified parameters
rightprocess right justified parameters
zerowhen zero arguments are left
listprocess the list of arguments
everyprocess every argument in turn
exitend 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.
Search for    or go to Top of page |  Section 1 |  Main Index


--> MKCMD (1L) LOCAL

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.