MKCMD(1)                                                              MKCMD(1)



NAME
       mkcmd - make a command line option parser

SYNOPSIS
       mkcmd  [-M | -R remote] [-AGKP] [-B boot.m] [-I directory] [-m manpage]
       [-n name] [files]
       mkcmd -E expander
       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.

       -B boot.m
              Replace the default mkcmd startup for the parser with the speci-
              fied  module.   This  is  only used to build tools with multiple
              command-line parsers.

       -E expander
              Output a list of the percent markup defined  for  each  expander
              package.  The expander "-" (dash) lists the available expanders,
              each expander table explains both the single letter and word for
              each available expander function.

       -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,
              externals  for  the memory allocation functions malloc(3), real-
              loc(3) and  calloc(3),  and  a  definition  of  strerror(3),  if
              needed.

       -h
              Print only a short help message.

       -I directory
              Mkcmd  searches  for  the files on the command line first in the
              current    directory,    then    in     a     standard     place
              ("/usr/local/lib/mkcmd"), then in any directory listed as param-
              eters to this option.

       -K
              In addition to building the parser, output a table  of  all  the
              keys defined for this product.

       -m manpage
              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.

       -M
              Produce  output that may be useful to build make(1) dependencies
              for the given configuration file.

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

       -P
              Suppress  most  cpp-like #line control information.  This allows
              some debuggers to follow the mixed code-path,  and  removes  the
              bogus  "mkcmd_generated_main"  filename that limits debugging of
              "main".

       -R remote[:explmux]
              Fetch modules from a remote tcpmux service named  explmux.   The
              local  modules (under -I) are searched after the remote service.

       -T
              Mkcmd outputs a table of the types it knows how to convert,  and
              nothing else.

       -V
              Mkcmd  outputs  a  handy version string, and some other compile-
              time configuration information.

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 (x), or a parametric position  on  the  command  line.
       The  conversion takes place as soon as the option (or position) is pro-
       cessed.  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 over-
       ide 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 attribute 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 identifier [unconv]       bind C variable identifier 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 identifier   read default value from $identifier
       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 identifier           n   set identifier 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 identifier           n   name the usage string (%t)
       usage identifier           n   name the usage function (%u)
       vector identifier          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 mandatory 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  mandatory  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
       KS Braunsdorf
       NonPlayer Character Guild
       mkcmd at ksb under npcguild.org.spam-not

HTML
       Writing Command Line Option Parsers (an HTML document).

SEE ALSO
       make(1),  cc(1),  getopt(3l),  explode(1l),  explmux(7l), tcpmux(8l) or
       inetd(8), cpp(1)



                                     LOCAL                            MKCMD(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | LANGUAGE | EXAMPLES | BUGS | AUTHOR | HTML | SEE ALSO