/*
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$
*/