/*
Copyright (c) 1993 Xerox Corporation.  All rights reserved.
*/
/*
$Id$

$Date$
 *
 */
/* Chauser, October 28, 1993 3:33 pm PDT */

#ifndef ←←PCR←BaseArgs←h
#   define ←←PCR←BaseArgs←h 1

#include <config/PCR←StdTypes.h>

#include <stdarg.h>


typedef struct PCR←BaseArgs←TemplateRep * PCR←BaseArgs←TemplatePtr;

typedef struct PCR←BaseArgs←TemplateRep {
    char * at←name;		/* arg name, includes leading - */
    char * at←options;		/* options pattern */
    char * at←doc;		/* documentation string */
} PCR←BaseArgs←Template;

typedef PCR←BaseArgs←Template * PCR←BaseArgs←Templates;
    /* by convention: an array terminated by at←name == NIL */

/*
    Options pattern syntax:
      - a single word without spaces describes option interpretation.
      - if the word begins with the character '#' the option must
        be specified as a number.
      - a default value may be specified in parentheses.
      - square brackets may be used to indicate optional values.
    Example:
      ???
    Options pattern may be NIL,
      in which case the documentation string is the name of a
      different arg for which this one is a synonym.
*/


extern PCR←ERes
PCR←BaseArgs←OverrideTemplateDefaults(
    PCR←BaseArgs←TemplatePtr overrides,
    PCR←BaseArgs←TemplatePtr templates
);
/*
    Smash the default values from overRides
      over the correspondingly named args in templates.
    Does not allocate.
    Does not require threads.
*/


extern PCR←ERes
PCR←BaseArgs←Tokenize(
    const char *argsString,
    char **argsBuf, unsigned sizeOfArgsBuf );
/*
    Tokenize the string, returning number of tokens.
    ArgsBuf must be big enough to hold a copy of argsString
      as well as the token pointers. 
    Result may be error PCR←ERes←FromErr(ENOMEM).
*/



extern PCR←ERes
PCR←BaseArgs←Get(
    int nArgs, const char **args,
    PCR←BaseArgs←Templates templates,
    const char *argName, unsigned index,
    PCR←Bool useDefault,
    const char **sp, long *np );
/*
    Look up the named argument in args, as described in template.

    Store specified field
      into *sp (as a string, if sp != NIL)
      and *np (as a number, if np != NIL). 

    The zero'th field is the arg itself, e.g. a call to

      PCR←BaseArgs←Get(..., (*argName*) "-t", (*index*) 0, ...)

      succeeds iff "-t" appears in args and in the template.

    Success:
      PCR←ERes←okay, with *sp and *np filled in as appropriate.
    Failure:
      EINVAL -- argname is not valid
      ERANGE -- arg[index] not present and useDefault false
      EINVAL -- np non-nil but arg not numeric
*/


extern PCR←ERes
PCR←BaseArgs←CheckFirst(
    int nArgs, const char **args,
    PCR←BaseArgs←Templates templates,
    int * pCnt, PCR←BaseArgs←TemplatePtr *pTemplate );
/*
    Return success iff prefix of args is a legal arg sequence.
    Store length of longest correct prefix in *pCnt,
      and pointer to template used in *pTemplate.
*/


extern PCR←ERes
PCR←BaseArgs←Partition(
    int nArgs, const char **args,
    PCR←BaseArgs←Templates templates,
    int *nKnownArgs, const char **knownArgs,
    int *nUnknownArgs, const char **unknownArgs,
    char *msgBuf, int msgBufLen );
/*
    Partition given args sequence
      "known" == described by templates;
      "unknown" == not described by templates.
    If any known args are not valid,
      return failure and store appropriate message into *msgBuf.
    Any of {nKnownArgs, knownArgs, nUnknownArgs, unknownArgs, msgBuf}
      may be NIL.
    Note: if both of {knownArgs, unknownArgs} are NIL, this just checks
      the arguments for validity.
*/


extern PCR←BaseArgs←TemplatePtr
PCR←BaseArgs←GetTemplatePtr(
    const char *arg,
    PCR←BaseArgs←Templates templates );
/*
    Get template for arg; return NIL if arg not defined in templates.
*/


extern PCR←ERes
PCR←BaseArgs←EnumerateTemplates(
    PCR←BaseArgs←Templates templates,
    PCR←ERes (*proc)(const PCR←BaseArgs←TemplatePtr template, void *data),
    void * data );
/*
    Call (*proc)(template, data) on each template in templates.
    Terminate enumeration if (*proc) returns res such
      that PCR←ERes←IsErr(res) is true.
*/


extern PCR←ERes
PCR←BaseArgs←GetUsageMsg(
    const char *arg,
    PCR←BaseArgs←Templates templates,
    char *msgBuf, int msgBufLen );
/*
    Store null-but-not-newline-terminated usage message for template
      into specified buf.
*/


#endif /* !←←PCR←BaseArgs←h */
/*
$Log$
*/