tomwalters@0: /*
tomwalters@0:     Copyright (c) Applied Psychology Unit, Medical Research Council. 1988, 1989
tomwalters@0:     ===========================================================================
tomwalters@0: 
tomwalters@0:     Permission to use, copy, modify, and distribute this software without fee 
tomwalters@0:     is hereby granted for research purposes, provided that this copyright 
tomwalters@0:     notice appears in all copies and in all supporting documentation, and that 
tomwalters@0:     the software is not redistributed for any fee (except for a nominal shipping 
tomwalters@0:     charge). Anyone wanting to incorporate all or part of this software in a
tomwalters@0:     commercial product must obtain a license from the Medical Research Council.
tomwalters@0: 
tomwalters@0:     The MRC makes no representations about the suitability of this 
tomwalters@0:     software for any purpose.  It is provided "as is" without express or implied 
tomwalters@0:     warranty.
tomwalters@0:  
tomwalters@0:     THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
tomwalters@0:     ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE
tomwalters@0:     A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 
tomwalters@0:     DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN 
tomwalters@0:     AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
tomwalters@0:     OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
tomwalters@0: */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:                                             *
tomwalters@0:    The Leanest Resource Manager in the West
tomwalters@0:    -----------------------------------------
tomwalters@0:                                            
tomwalters@0: 
tomwalters@0:                                    (*) is no more! The gallant <getopts.[ch]> has
tomwalters@0:                                        given way to a new daring duo! Henceforth,
tomwalters@0:                                        read "options" for "getopts". The new features
tomwalters@0:                                        include classified options and user-supplied
tomwalters@0:                                        "Help" information. See <options.c> for edit
tomwalters@0:                                        history.
tomwalters@0: 
tomwalters@0:    Copyright (c), 1989  The Medical Research Council of the United Kingdom.
tomwalters@0: 
tomwalters@0:    Author  :    Paul Manson
tomwalters@0:    Written :    March 1st 1989  [See options.c for modifications history]
tomwalters@0: 
tomwalters@0:    Options may be supplied as defaults (actually in the code), as command line
tomwalters@0:    arguments, and in an option file. The default arguments may be overridden by
tomwalters@0:    the option-file contents, which may be overridden in turn by command line
tomwalters@0:    arguments. The syntax of a option file is as follows:
tomwalters@0: 
tomwalters@0:    <option file> ::= { <option line> <linefeed> }
tomwalters@0: 
tomwalters@0:    <option line> ::= <option specification> | <comment line> | <blank line>
tomwalters@0: 
tomwalters@0:    <option specification> ::= <name> "=" <option value> [ <comment line> ]
tomwalters@0: 
tomwalters@0:    <option value> ::= <contiguous character string> | 
tomwalters@0:                         """ <any printable chars except """> """
tomwalters@0: 
tomwalters@0:    <comment line> ::= "#" <absolutely anything>
tomwalters@0: 
tomwalters@0:    where spaces are not considered significant except that the <value> ought to
tomwalters@0:    be a quoted string if it contains spaces. On Unix, the OPTIONSPATH path in the
tomwalters@0:    users' environment is used to search for a option file, but if this path is
tomwalters@0:    absent, the current working directory will still be searched. On an IBM PC, the
tomwalters@0:    the directory in which the application program was found is searched for the
tomwalters@0:    option file. [In the future, this will be modified so that the current directory
tomwalters@0:    is searched first].
tomwalters@0: 
tomwalters@0:    Command line arguments may take any of the following forms;
tomwalters@0: 
tomwalters@0:    1.     -name
tomwalters@0:    
tomwalters@0:    2.     -name=value
tomwalters@0: 
tomwalters@0:    3.     name=value
tomwalters@0: 
tomwalters@0:    where it should be noted that spaces ARE significant, and that the first of these
tomwalters@0:    formats effects a set/toggle operation on the named option, by setting its 
tomwalters@0:    value to some system-defined default value (at present, this is "1").
tomwalters@0: 
tomwalters@0:    If a user specifies -help on the command line then getopts uses the "help" option
tomwalters@0:    (if there is one) to print a message detailing the options available to the
tomwalters@0:    user. Specifying -update on the command line causes a new version of the currently
tomwalters@0:    read option file to be written, incorporating any alterations which have been
tomwalters@0:    effected by previous command line options.
tomwalters@0: 
tomwalters@0:    Abbreviations are permitted for options, but it must be noted that only
tomwalters@0:    unambiguous option specifications will have any effect (ambiguous specifications
tomwalters@0:    are rejected with a warning message). If a option specification uses a name which
tomwalters@0:    is an abbreviation for two options, but matches one of these options EXACTLY,
tomwalters@0:    this is not considered to be ambiguous (the exact match being taken as the intended
tomwalters@0:    one). Abbreviations are NOT permitted in option headers (see readopts and writeopts
tomwalters@0:    below).
tomwalters@0: 
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: #include <stdio.h>
tomwalters@0: 
tomwalters@0: #define InputOption (1)
tomwalters@0: #define OutputOption (2)
tomwalters@0: #define InOutOption (0)
tomwalters@0: #define SilentOption (3)
tomwalters@0: 
tomwalters@0: typedef struct {
tomwalters@0:   char *name          ;    /* The name of the option,                      */
tomwalters@0:   char *defaultValue  ;    /* its default value,                             */
tomwalters@0:   char **value        ;    /* The place where its current value is stored    */
tomwalters@0:   char *comment       ;    /* Something to print when the user types "-help" */
tomwalters@0:   short classification;    /* What form of option it is.                     */
tomwalters@0: } Option, *OptionPtr;
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    This structure may be used to build a database of option handles, as indicated
tomwalters@0:    in the following sample program;
tomwalters@0: 
tomwalters@0:    static char *samplerate, *inputfile;
tomwalters@0: 
tomwalters@0:    static Option res[] = {
tomwalters@0:         { "Sample Rate", "10000.0",    &samplerate, "The Rate of Sampling", InOutOption },
tomwalters@0:         { "Input File ", "input.data", &inputfile , "A File to Read From ", InOutOption }};
tomwalters@0: 
tomwalters@0:    which declares two options, <samplerate> and <inputfile>, and gives them 
tomwalters@0:    default values. These defaults may later be overwritten by the function
tomwalters@0:    getopts(), either from the option file or from the command line.
tomwalters@0: 
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: #define NumOptions(res) (sizeof(res) / ((sizeof(char *) + (sizeof(char **)))))
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Provides a macro for determining how many options are present in a res[]
tomwalters@0:    declaration such as that shown above. eg. NumOptions(res) == 2. This macro
tomwalters@0:    should be used on calls to getopts, etc.
tomwalters@0: 
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: extern void getnopts(); /* (options, numOptions, &argc, &argv) */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    This function should be called before an application program examines its arguments
tomwalters@0:    (this is because it butchers them!). First of all, it reads the appropriate option
tomwalters@0:    file and interprets the options specified therein (the name of the option file
tomwalters@0:    is given by the name of the application, ie. argv[0]). After redefining the options
tomwalters@0:    specified by the option file, it examines the arguments (given by argc and argv) 
tomwalters@0:    and scans them for additional options. Finally, it resets argc and argv for the
tomwalters@0:    remainder of the program (if any) to deal with. NOTE THAT argc AND argv _MUST_ BE
tomwalters@0:    PASSED AS POINTERS TO THIS ROUTINE!.
tomwalters@0: 
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: extern void getopts();          /* (options, &argc, &argv) */
tomwalters@0: extern void cmd_line_opts() ;   /* (options, &argc, &argv) */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Some fussy people don't like to count their own option lists, so this routine
tomwalters@0:    does the necessary dirty-work before passing the result(s) to getnopts(). You MUST
tomwalters@0:    remember to null-terminate your options array; ie.
tomwalters@0: 
tomwalters@0:    static char *samplerate, *inputfile;
tomwalters@0: 
tomwalters@0:    static Option res[] = {
tomwalters@0:         { "Sample Rate", "10000.0",    &samplerate, "The Rate of Sampling", InOutOption },
tomwalters@0:         { "Input File ", "input.data", &inputfile , "A File to Read From ", InOutOption },
tomwalters@0: 	NULL};
tomwalters@0: 
tomwalters@0:    and upon your own head (or lesser, more sensitive, appendages) be it if you forget
tomwalters@0:    to do this!
tomwalters@0: 
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: extern void readnopts(); /* (options, numOptions, filePointer) */
tomwalters@0: extern void readopts() ; /* (options, filePointer)               */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Try to read a options header from the specified <file>, with reference to the
tomwalters@0:    array of <options>. The header layout is specified below (see writenopts), and
tomwalters@0:    the operation, if successful, will leave the filePointer set to the first byte
tomwalters@0:    after the (padded) option header. Unsuccessful readnopts will cause en error
tomwalters@0:    message and will terminate the program. If there does not appear to be a header
tomwalters@0:    on the file at all, readnopts does nothing. The routine readopts counts the
tomwalters@0:    options in <options> for you, and you MUST null-terminate your options
tomwalters@0:    array if you use this routine. 
tomwalters@0: 
tomwalters@0:    WARNING: readopts and readnopts do NOT require that a option name found in a 
tomwalters@0:    header be an actual option of the calling program, and will IGNORE any such 
tomwalters@0:    option assignments.
tomwalters@0: 
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: extern void writenopts(); /* (options, numOptions, filePointer) */
tomwalters@0: extern void writeopts() ; /* (options, filePointer)               */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Write the current option settings as specified by <options> into the 
tomwalters@0:    specified file. The options are written as an ASCII header, in the same form
tomwalters@0:    as is required by getopts (and consequently, readopts). This header will begin
tomwalters@0:    with some suitable comment (line beginning with a # character) to indicate that
tomwalters@0:    it is in fact a option header. Following this comment will be information 
tomwalters@0:    concerning the size of the option file header. This information is used to tell
tomwalters@0:    subsequent calls to readnopts the length of the option header; this header will 
tomwalters@0:    actually be padded to a block boundary to avoid disturbing the following data
tomwalters@0:    unnecessarily. As might be expected, writeopts is a counting version of writenopts;
tomwalters@0:    remember to NULL-terminate your option array if you use this routine.
tomwalters@0:    
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: extern FILE *fileopts();   /* (options, &argc, &argv ) */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    A packaging function which performs getopts(options, &argc, &argv), then fopens
tomwalters@0:    the next argument and does readopts on it. It returns a file handle to this file
tomwalters@0:    with the header removed (ie. it points at the first byte of data).
tomwalters@0:    
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: extern FILE *optoutput(); /* (String) */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Simply open a file for output (depending on the value of String)... a NULL string
tomwalters@0:    returns NULL, the default String (at present this is "1") sends to stdout, and
tomwalters@0:    anything else is taken as being a path name for a file to create for writing.
tomwalters@0:    
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: extern void helpnopts(); /* (options, numOptions, program_name) */
tomwalters@0: extern void helpopts(); /* (options, program_name) */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Allows application programs to invoke the online help (ie. usage) information at
tomwalters@0:    any point. The helpopts call counts the number of options for you, BUT ONLY IF
tomwalters@0:    you remember to NULL-TERMINATE IT!
tomwalters@0:       
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: typedef void helpRoutine( /* (options, numOptions, program_name) */ );
tomwalters@0: 
tomwalters@0: extern helpRoutine *helpOptsHandler(); /* (helpRoutine) */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    Allows an application program to install its very own helpHandler routine to
tomwalters@0:    override the default help-message handler. The behaviour of such a routine is
tomwalters@0:    implicitly trusted by <options>, so you should only install your own handler 
tomwalters@0:    when you are quite familiar with the Options structure format. This routine
tomwalters@0:    returns the address of the previously installed handler (which is initially the
tomwalters@0:    default handler) so that this may be reinstated at a later point.
tomwalters@0: 
tomwalters@0:    ---------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: 
tomwalters@0: #define isON(_STR) (!isOFF(_STR))
tomwalters@0: 
tomwalters@0: extern int isOFF();
tomwalters@0:      /* char *optionStr; */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    A convenience call which returns TRUE (1) if the optionStr is what options thinks
tomwalters@0:    of as "ON", "YES", "TRUE", or "1".... This merely allows us to hide the actual
tomwalters@0:    implementation of "ON" from the application programs.
tomwalters@0:       
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: extern int isNULL();
tomwalters@0:      /* char *optionStr; */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    A convenience call which returns TRUE (1) if the optionStr is what options thinks
tomwalters@0:    of as "NULL", "NONE", nothing, zip, etc... This merely allows us to hide the actual
tomwalters@0:    implementation of "NULL" from the application programs.
tomwalters@0:       
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: #define ON_OPTION "on"
tomwalters@0: #define OFF_OPTION "off"
tomwalters@0: #define NULL_OPTION "none"
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:   NOTE: The above definitions allow the expression of constant option settings
tomwalters@0:   via static option[] arrays... they do so at the risk of allowing some klutz
tomwalters@0:   to alter them... the only solution to this problem (other than forcing
tomwalters@0:   application programmers to read .h files) is to return copies of these
tomwalters@0:   strings via procedure calls, and this precludes static initialisation.
tomwalters@0:       
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: extern int OptionStringsEqual();
tomwalters@0:      /* char *str1, *str2; */
tomwalters@0: 
tomwalters@0: /* ---------------------------------------------------------------------------------
tomwalters@0: 
tomwalters@0:    A routine to reduce the load on the application programmer by providing a simple
tomwalters@0:    boolean check for string equality WITHOUT CASE SIGNIFICANCE. This allows applications
tomwalters@0:    to leave case and typing problems within "options" reliably.
tomwalters@0:       
tomwalters@0:    --------------------------------------------------------------------------------- */
tomwalters@0: 
tomwalters@0: extern char *versionstr;