[comp.sources.misc] v17i053: parseargs - functions to parse command line arguments, Part08/12

brad@hcx1.ssd.csd.harris.com (Brad Appleton) (03/18/91)

Submitted-by: Brad Appleton <brad@hcx1.ssd.csd.harris.com>
Posting-number: Volume 17, Issue 53
Archive-name: parseargs/part08

This is part 8 of parseargs

#!/bin/sh
# this is Part.08 (part 8 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file parseargs/parseargs1.txt continued
#
if test ! -r _shar_seq_.tmp; then
	echo 'Please unpack part 1 first!'
	exit 1
fi
(read Scheck
 if test "$Scheck" != 8; then
	echo Please unpack part "$Scheck" next!
	exit 1
 else
	exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
	echo 'x - still skipping parseargs/parseargs1.txt'
else
echo 'x - continuing file parseargs/parseargs1.txt'
sed 's/^X//' << 'SHAR_EOF' >> 'parseargs/parseargs1.txt' &&
X     or	characters following a newline may be lost, in any
X     variables that are	set by parseargs.
X
X     Parseargs(1) is subject to	the same caveats as parseargs(3).
X     Refer to the CAVEATS section of the parseargs(3) manual
X     page(s) for more information.
X
AUTHOR
X     Brad Appleton  (brad@ssd.csd.harris.com)
X     Harris Computer Systems, Fort Lauderdale, FL USA
X
X
X
X
X
X
X
X
X
X
X
X
X
Page 15
X
X
X
SHAR_EOF
echo 'File parseargs/parseargs1.txt is complete' &&
chmod 0664 parseargs/parseargs1.txt ||
echo 'restore of parseargs/parseargs1.txt failed'
Wc_c="`wc -c < 'parseargs/parseargs1.txt'`"
test 33378 -eq "$Wc_c" ||
	echo 'parseargs/parseargs1.txt: original size 33378, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= parseargs/parseargs3.txt ==============
if test -f 'parseargs/parseargs3.txt' -a X"$1" != X"-c"; then
	echo 'x - skipping parseargs/parseargs3.txt (File already exists)'
	rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting parseargs/parseargs3.txt (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'parseargs/parseargs3.txt' &&
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
NAME
X     parseargs,	usage -	parse command line argument vectors
X
SYNOPSIS
X     #include <parseargs.h>
X
X     int  parseargs(  char *argv[],  ARGDESC *argd  )
X     int  fparseargs(  FILE *fp,  ARGDESC *argd	 )
X     int  lparseargs(  ArgList *argls,	ARGDESC	*argd  )
X     int  sparseargs(  char *str,  ARGDESC *argd  )
X     int  vparseargs(  ARGDESC *argd,  ...  )
X     void  usage(  const ARGDESC *argd	)
X
DESCRIPTION
X     Given a vector of string-valued arguments such as that
X     passed to main and	a vector describing the	possible argu-
X     ments, parseargs matches actual arguments to possible argu-
X     ments, converts values to the desired type, and diagnoses
X     problems such as missing arguments, extra arguments, and
X     argument values that are syntactically incorrect.
X
X     Given a readable input stream and an argdesc array, fpar-
X     seargs will parse arguments in a file in much the same
X     manner as parseargs.  A maximum-line length of 255	charac-
X     ters is imposed.  NO ``escaping'' of any kind is performed.
X     Comments of a limited form	are permitted: if the first non-
X     whitespace	character on a line is a '#' (or '!' for VMS)
X     then that entire line is considered a comment and is
X     ignored.  If a value is provided for an argument that is NOT
X     a list or a vector, then the value	MUST be	on the same line
X     as	the argument (in other words, ``-v val'' is fine but
X     ``-v\nval'' is a not).
X
X     Given an ArgList and an argdesc array, lparseargs will parse
X     arguments in a file in much the same manner as parseargs.
X
X     Given a single string and an argdesc array, sparseargs will
X     parse arguments from a string in much the same manner as
X     parseargs.	 Sparseargs will split the given string	up into	a
X     vector of whitespace separated tokens and then attempt to
X     parse the resultant vector	as if it were given as argv[] on
X     the command-line.	NO special treatment is	given to charac-
X     ters such as single-quotes, double-quotes,	or anything else.
X     Sparseargs	will always assume that	any whitespace characters
X     are intended as argument separators.
X
X
X     Vparseargs	takes an argdesc array,	the number of arguments
X     to	parse, and a (possibly NULL terminated)	list of
X     argument-strings and parses them in much the same manner as
X     parseargs.	 Unlike	sparseargs, vparseargs assumes that all
X     parameters	are already split up into tokens, hence	any
X
X
X
Page 1
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     whitespace	characters contained in	any of the string-
X     parameters	are used as is (and will be considered a part of
X     an	argument name or value).
X
X
X     Given an argdesc array, usage will	print the usage	for the
X     given command in the format specified by the user's
X     USAGECNTL environment variable.
X
THE ARGUMENT STRUCTURE
X     The basic type used by the	parseargs library is the argument
X     descriptor	(or "argdesc" for short). An ARGDESC structure is
X     used to describe a	command-line argument. Each command line
X     argument contains various fields which need to be set and/or
X     queried by	the programmer.	 The individual	fields of an
X     ARGDESC structure are desribed below:
X
X     char  ad_name;
X	  This is a single character which corresponds to the
X	  option-letter	(case-sensitive) from the command-line
X	  that matches the argument described by this structure.
X	  Positional-arguments are denoted by putting a	a space
X	  character in this field.
X
X     argMask_t	ad_flags;
X	  This field contains the various bitflags that	describe
X	  the semantics	of this	argument. See the ARGUMENT FLAGS
X	  section for more information on the possible combina-
X	  tions	of bitmasks for	this field.
X
X     argTypePtr_t  ad_type;
X	  This field is	a pointer to a type conversion function
X	  (such	as the ones provided in	argtype(3). The	type
X	  conversion function is responsible for verifying the
X	  validity of the argument, allocating any necessary
X	  storage for its internal representation, and converting
X	  the command-line argument into its required internal
X	  form.	The type conversion function used may be one of
X	  the pre-defined argtype(3) functions.	The function is
X	  given	three parameters: The first is a pointer to the
X	  ARGDESC struct in question, the second is the	string-
X	  value	(if any) supplied on the command-line, and the
X	  third	is a boolean value that	is TRUE	only if	the
X	  second parameter points to temporary storage (and hence
X	  may need to be copied).  In the case of parseargs(1)
X	  this field must correspond to	the name of one	of the
X	  argument type	functions described in argtype(3).
X
X     ARBPTR  ad_valp;
X	  This field is	a generic pointer to the storage used to
X	  represent the	internal value of the command-line argu-
X	  ment.	It may be a pointer to a number, a boolean value,
X
X
X
Page 2
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  a string, a list, or anything	else for which there
X	  exists a corresponding arg-type function to use in the
X	  ad_type field. In the	case of	of parseargs(1)	this
X	  field	must be	the name of the	corresponding shell vari-
X	  able which eventually	hold the value of the argument
X	  given	on the command-line.
X
X     const char	 *ad_prompt;
X	  This field contains the long-name of the argument and
X	  an optional description (the description must	be
X	  separated from the long-name by at least one whitespace
X	  characters and may optionally	be enclosed in a set of
X	  balanced delimiters (such as parentheses, curly-braces,
X	  square-brackets, or angle-brackets. If the long-name
X	  contains any uppercase characters, then the substring
X	  of long-name consisting of all uppercase characters is
X	  used as the argument name and	the entire long-name is
X	  used as the name of the argument-value (if a value my
X	  be supplied).	The long-name may be matched by	supplying
X	  a unique prefix of either the	argument name or the
X	  argument-value name.
X
DEFINING ARGDESC ARRAYS
X     When defining an argdesc array, the first item in the list
X     should be the item	STARTOFARGS. Normal arguments (defined by
X     the programmer) may then be specified as documented in this
X     manual.  The list of arguments is terminated using
X     ENDOFARGS.
X
X     For example, consider the description:
X       int  RepCount =	   2;
X       BOOL Verbose = FALSE;
X       char *InFile;
X       char *OutFile =	   CHARNULL;
X       BOOL XRated =  FALSE;
X       struct namelist *Files =	NULL;
X
X       ARGDESC Args[] =
X       {
X	 STARTOFARGS,
X	 'c', ARGOPT,	 argInt,  __ &RepCount,	"REPcount {# of	repetitions}",
X	 'v', ARGOPT,	 argBool, __ &Verbose,	"Verbose {set verbose mode}",
X	 ' ', ARGREQ,	 argStr,  __ &InFile,	"INPUTfile {input file}",
X	 ' ', ARGOPT,	 argStr,  __ &OutFile,	"OUTPUTfile {output file}",
X	 'X', ARGHIDDEN, argBool, __ &XRated,	"XratedMODE {naughty stuff!}",
X	 ' ', ARGOPT|ARGLIST, argStr, __ &Files, "File {files to be read}",
X	 ENDOFARGS
X       };
X
X     This describes a program accepting	up to three flag argu-
X     ments and one or two positional arguments,	plus a list of
X     additional	file arguments.	 Only the first	positional
X
X
X
Page 3
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     argument is required.  The	possible flags (in UNIX) are:
X
X     -c	count  An integer repetition count.  This defaults to
X	       two.
X
X     -v	       A Boolean ``verbose'' flag.  It defaults	to FALSE.
X
X     -X	       A Boolean ``X Rated'' flag.  This is not	printed
X	       in the usage message.
X
X     The two positional	arguments are both strings, as is the
X     final list.  In AmigaDOS, the options would be REP	count, V,
X     and XMODE.	 In VAX/VMS, the qualifiers would be /REP=count,
X     /V, and /XMODE.
X
ARGUMENT FLAGS
X     These are the possible bitmasks that may be turned	ON or OFF
X     in	the ad_flags field of an ARGDESC structure.
X
X     ARGOPT
X	  This flag is actually	a dummy	flag (i.e. it is the
X	  default). This flag specifies	that the command-line
X	  argument is optional (need not appear	on the command-
X	  line). It is only needed if no other flags are used to
X	  define the given argument.  If other flags are given
X	  and ARGREQ is	NOT one	of them, then ARGOPT is	always
X	  assumed.
X
X     ARGREQ
X	  The associated command argument is required on the
X	  command-line.
X
X     ARGPOS
X	  The associated command argument is positonal.	The
X	  difference between using this	flag to	indicate a posi-
X	  tional argument and between using a blank in the
X	  ad_name field	to indicate a positional arguments is the
X	  following: If	this flag is set but the ad_name of the
X	  argument is non-blank, then this argument may	be
X	  matched either positionally or by keyword. If	the
X	  ad_name field	is blank, then this argument may only be
X	  matched positionally.
X
X     ARGNOVAL
X	  The associated command argument takes	no value (as in
X	  "-x value"); Its mere	presence (or lack thereof) on the
X	  command-line is sufficient to	determine the necessary
X	  action(s) to take (as	in "-x").  Boolean argument types
X	  and Pseudo-argument types automatically default to ARG-
X	  NOVAL.
X
X     ARGVALOPT
X
X
X
Page 4
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  This flag is used to indicate	that the command-line
X	  argument takes a value (as in	"-s string" or
X	  "/str=string") but that the value to this command-line
X	  argument is NOT required (hence simply "-s" or "/str"
X	  is also permissable).
X
X     ARGVALREQ
X	  Another "dummy" flag.	Unless ARGNOVAL	or ARGVALOPT is
X	  specified, ARGVALREQ is always assumed. This flag indi-
X	  cates	that the value to a command-line argument is
X	  required (hence "-s string" is okay but just "-s" is
X	  not).
X
X     ARGHIDDEN
X	  Don't	display	this argument in usage messages	but still
X	  attempt to match it against strings given on the
X	  command-line.
X
X     ARGLIST
X	  A variable number of values are used for this	argument
X	  (and hence may use more than one or two argv elements
X	  from the command-line	as in "-l val1 val2 ..."). The
X	  list of values must be stored	in an ArgList structure
X	  (NOT a vector	structure), an the corresponding
X	  argument-type	function should	be one of the listXxxx
X	  functions.
X
X     ARGVEC
X	  A variable number of values are used for this	argument
X	  (and hence may use more than one or two argv elements
X	  from the command-line	as in in "-v val1 val2 ..."). The
X	  list of values must be stored	in a vector structure
X	  (NOT an ArgList structure).
X
X     The following bitmasks may	also be	present, but, unlike the
X     above masks which must be specified by the	programmer at
X     initialization time, the following	masks must only	be read
X     (never set) by the	programmer. They may be	queried	by using
X     the pc_ARGFLAGS function code and the mode	pc_READ	with par-
X     secntl(3).
X
X     ARGGIVEN
X	  The argument WAS given on the	command-line.
X
X     ARGVALGIVEN
X	  The value for	this argument was given	on the command-
X	  line.
X
X     ARGVALSEP
X	  The value to this argument was supplied in a separate
X	  argv element from the	argument itself	(as in "-x value"
X	  as opposed to	"-xvalue").
X
X
X
Page 5
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     ARGKEYWORD
X	  This argument	was matched as a keyword (long-form) on
X	  the command-line and not as a	single character.
X
X     ARGDESCRIBED
X	  This argument	was given a description	by the programmer
X	  at initialization.
X
X     ARGCOPYF
X	  This flag is only used for lists and vectors (mul-
X	  tivalued arguments) and is used on a per-item	basis. If
X	  it is	set, it	means that the corresponding value in the
X	  vector/list required space to	be allocated (such as the
X	  duplication of a temporary string).
X
ARGDESC	MACROS
X     The following macros are used to extract and query	the
X     attributes	of a pointer to	a preprocessed arg-descriptor:
X
X     arg_cname(ad)
X	  Return the single-character name of an argument.
X
X     arg_flags(ad)
X	  Return the argument flags of an argument.  The flags
X	  themselves may be manipulated	using the BTEST, BSET,
X	  and BCLEAR macros defined in <useful.h>.
X
X     arg_type(ad)
X	  Return the pointer to	the value-translation-routine of
X	  an argument.
X
X     arg_valp(ad)
X	  Return the pointer to	the value of this argument.
X
X     arg_sname(ad)
X	  Return the string name of an argument.
X
X     arg_sdesc(ad)
X	  Return the description of an argument. If a description
X	  was supplied,	the ARGDESCRIBED flag will be set and the
X	  description will immediately follow the terminating NUL
X	  byte of the string name.
X
X     ARG_isDESCRIBED(ad)
X	  Evaluates to TRUE only if an argument	description was
X	  provided.
X
X     arg_description(ad)
X	  Return the description string	(or an empty string if no
X	  description was given) for this argument.
X
X     ARG_isPOSITIONAL(ad)
X
X
X
Page 6
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  Evaluates to TRUE if this argument may be positionally
X	  matched.
X
X     ARG_isPOSONLY(ad)
X	  Evaluates to TRUE if this argument may only be posi-
X	  tionally matched.
X
X     ARG_isLIST(ad)
X	  Evaluates to TRUE if this argument is	an arglist.
X
X     ARG_isVEC(ad)
X	  Evaluates to TRUE if this argument is	a vector.
X
X     ARG_isMULTIVAL(ad)
X	  Evaluates to TRUE if this argument is	an arglist or a
X	  vector.
X
X     ARG_isVALTAKEN(ad)
X	  Evaluates to TRUE if this argument does NOT take a
X	  value.
X
X     ARG_isGIVEN(ad)
X	  Evaluates to TRUE if this argument was given on the
X	  command-line.
X
X     ARG_isVALGIVEN(ad)
X	  Evaluates to TRUE if the argument value was given on
X	  the command-line.
X
X     ARG_isREQUIRED(ad)
X	  Evaluates to TRUE if this argument is	required.
X
X     ARG_isVALOPTIONAL(ad)
X	  Evaluates to TRUE if the argument value is optional.
X
X     ARG_isVALSEPARATE(ad)
X	  Evaluates to TRUE if the argument value is optional.
X
X     ARG_isHIDDEN(ad)
X	  Evaluates to TRUE if this argument is	omitted	from
X	  usage	messages.
X
CMD MACROS
X     Parseargs.h defines a set of macros to allow a more "self
X     documenting" approach to declaring	argument-descriptor
X     arrays. The "old-style" is	still accepted (but if used it is
X     recommended that the STARTOFARGS macro is used in conjunc-
X     tion with ENDOFARGS).  An example use of these macros
X     (which, with one exception, all begin with	``CMD'') follows:
X	  #include <parseargs.h>
X
X	  static BOOL bflag = FALSE;
X
X
X
Page 7
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  static char *arg1 = CHARNULL;
X	  static char *arg2 = CHARNULL;
X
X	  static
X	     CMD_OBJECT
X		MyCmd
X
X	     CMD_NAME
X		"mycmd -- one line statement of	purpose"
X
X	     CMD_DESCRIPTION
X		"Mycmd will try	really really hard to run without errors \
X	  and do whatever the heck it is supposed to do. If (God forbid) \
X	  something should actually go wrong it	will say so."
X
X	     CMD_ARGUMENTS
X		'H', ARGOPT, argUsage, __ NULL,
X		"Help -- display usage and quit",
X
X		'b', ARGOPT, argSBool, __ &bflag,
X		"bflag -- turn on `b'-mode (whatever that is)",
X
X		' ', ARGREQ, argStr, __	&arg1,
X		"arg1 -- first argument	to this	spiffy program",
X
X		' ', ARGOPT, argStr, __	&arg2,
X		"arg2 -- optional second argument to this spiffy program",
X
X		END_ARGUMENTS
X	     CMD_END
X
X	  main(	int argc, char *argv[] )
X	  {
X	     (void) parseargs( argv, MyCmd );
X	     (void) dostuff();
X	     exit( 0 );
X	  }
X
DEFAULT	ARGUMENT DESCRIPTOR
X     Each argdesc-array	has an initial default argument	list
X     (which may	be reset using the pc_DEFARGS function code with
X     parsecntl). This initial default argument-list contains `?'
X     and `H' which may be used as single character keywords to
X     display command-usage for all command-line	styles.	 Simi-
X     larly, ``?'', ``H'', and ``Help'' may be used as long-
X     keywords to display command-usage for all command-line
X     styles.  In Addition, for VMS style commands, the qualifiers
X     /INPUT=file, /OUTPUT=file,	and /ERROR=file, may be	used to
X     redirect stdin, stdout, and stderr	(respectively) to a file.
X     For AmigaDOS style	commands, the keyword ``ENDKWDS'' may be
X     used to disable parsing for any more keywords on the
X     command-line.
X
X
X
Page 8
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
SUPPLYING DEFAULT ARGUMENTS
X     Programs that use parseargs may be	given default arguments
X     under UNIX	and PCs	through	the use	of environment variables
X     (symbols are used for VMS systems). If a  C-program or
X     shell-script uses parseargs to implement a	command	named
X     ``cmd'' then the environment variable ``CMD_ARGS''	will be
X     parsed for	any "default" arguments	before the command-line
X     is	parsed.	 The command-line will over-ride any options that
X     are specified in this environment variable	(except	that
X     ARGLISTs and ARGVECs set in ``CMD_ARGS'' will be appended
X     from the command-line
X
X     It	is important to	note that the contents of the
X     ``CMD_ARGS'' environment variable are NOT expanded	by the
X     shell and hence any special characters (such as quotes or
X     back-slashes) will	NOT be escaped or removed by parseargs.
X     Furthermore, it will not be possible to try and use a tab,
X     space, or newline character in the	environment variable as
X     anything other than an argument separator.
X
X     Lastly, parts of an option	specification in ``CMD_ARGS'' may
X     NOT be continued on the command-line. As an example, if -f
X     requires an argument and CMD_ARGS="-f", then the command-
X     line "cmd	bah" will NOT assign "bah" as the argument to -f
X     but will instead complain about a missing argument	for -f.
X     Similarly,	if -l takes a list of arguments	and CMD_ARGS="-l
X     item1 item2", then	the command-line "cmd  bah", will NOT
X     assign "bah" to the end of	the list containing "item1" and
X     "item2" but will instead treat "bah" as the first positional
X     parameter on the command-line.
X
PARSING	BEHAVIOR
X     The programmer may	control	parsing	behavior through the use
X     of	parsecntl(3).  The user	may set	his (or	her) own desired
X     parsing behavior through the use of the ``PARSECNTL''
X     environment variable.  By indicating any number of	flags
X     (possibly negated)	the user will directly modify the
X     behavior of the parseargs library.	Flags may be combined by
X     placing a `+' or `|' character in between flags. A	switch is
X     negated by	immediately preceding it with a	`!' or `-' char-
X     acter.  The possible ``flags'' are	given by the following
X     table. Flags are case-insensitive.
X
X     Prompt
X	  Prompt the user for any missing arguments that are
X	  required on the command-line.	No special escaping or
X	  quoting is performed on the user input. Required argu-
X	  ments	that expect a list of values will be repeatedly
X	  prompted for (one item per line) until a blank line
X	  (followed by a carriage return) is entered.
X
X     Ignore
X
X
X
Page 9
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  Ignore any unrecognized or improperly	specified
X	  command-line arguments and continue execution	of the
X	  program. Normally, if	an argument is unmatched (or is
X	  improperly specified), a usage message is printed pro-
X	  gram execution is terminated.
X
X     OptsOnly
X	  Under	UNIX, setting this flag	will disable the parsing
X	  of long-option syntax. This will cause all arguments
X	  starting with	'+' to always be treated as a positional
X	  parameter (instead of	a long-option).
X
X     KwdsOnly
X	  Under	UNIX, setting this flag	disables the parsing of
X	  single-character options.  This will cause all argu-
X	  ments	starting with '-' to always be treated as a posi-
X	  tional parameter (instead of an option).
X
X     LoptsOnly
X	  Same as KwdsOnly.
X
X     Flags1st
X	  Setting this flag causes the parseargs library to force
X	  any and all non-positional arguments to be specified
X	  before any positional	ones.  As an example, under UNIX,
X	  if this flag is SET then parseargs will consider the
X	  command line "cmd -x arg" to consist of one option and
X	  one positional argument; however the command line "cmd
X	  arg -x" would	be considered to consist of two	posi-
X	  tional arguments (the	-x option will be unmatched).
X
X	  If this flag is UNSET, then both of the previous exam-
X	  ples are considered to consist of one	option and one
X	  positional argument.
X
X     CaseIgnore
X	  Setting this flag cause character-case to be ignored
X	  when attempting to match single-character argument
X	  names	(i.e. causes "-i" and "-I" will	be considered
X	  equivalent).
X
X     If	the environment	variable ``PARSECNTL'' is empty	or unde-
X     fined, then parsing behavior set by the programmer	is used.
X     If	the programmer has not explicitly used parsecntl(3) to
X     modify the	parsing	behavior will be ``!Prompt + !Ignore''
X     for Unix MS-DOS, OS/2, and	AmigaDOS systems, and ``Prompt''
X     for VMS systems.
X
USAGE MESSAGES
X     Through the use of	an environment variable	(or a VMS sym-
X     bol), the user may	control	the syntax and the verbosity of
X     the command-usage messages	that are printed by parseargs.
X
X
X
Page 10
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     The desired level of verbosity may	be set by defining the
X     environment variable ``USAGECNTL" to be a combination of
X     strings (case insensitive). The value of each string con-
X     trols one of three	different ``modes'' of behavior	in the
X     displaying	of usage messages:  The	first ``mode'' is ``ver-
X     bose'' mode, which	controls whether or not	a detailed
X     description of each argument should accompany the usual
X     command-line sysnopsis. If	verbose	mode is	``off'', then
X     only a command-line synopsis is printed (this is also ref-
X     ferred to as ``terse'' mode). The other two ``modes'' con-
X     trol the displaying of option syntax and long-option syntax.
X     A mode may	be explicitly disabled by preceding its
X     corresponding string with the `!'	character. The ``modes''
X     which correspond to the possible values of	the ``USAGECNTL''
X     environment variable are given by the following table.
X
X     Quiet
X	  No usage message of any kind is displayed.
X
X     Silent
X	  Same as Quiet.
X
X     Paged
X	  The usage message is piped to	a pager. The pager used
X	  is named by the ``USAGE_PAGER'' environment variable.
X	  If this variable is unset or empty (or is not	the name
X	  of an	executable program) then the pager named by the
X	  ``PAGER'' environment	variable us used.  If this vari-
X	  able is unset	or empty (or is	not the	name of	an exe-
X	  cutable program) then	/usr/ucb/more is used.
X
X     Description
X	  The command description is printed.
X
X     Terse
X	  Terse	mode, just print command-line synopsis.
X
X     Verbose
X	  Verbose mode,	print descriptions for each argument
X
X     Options
X	  Option syntax	is displayed.
X
X     LongOpts
X	  Long-option syntax is	displayed.
X
X     KeyWords
X	  Same as LongOpts.
X
X
X     If	the environment	variable ``USAGECNTL'' is empty	or unde-
X     fined, then the default usage level (which	is presently
X
X
X
Page 11
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     ``Verbose + Options'') will be used.
X
MULTI-VALUED ARGUMENTS
X     Parseargs supports	two different types of multi-valued argu-
X     ments: linked-lists and vectors. The linked-lists are called
X     argument lists (or	arg-lists) and are specified by	supplying
X     the ARGLIST flag along with an associated listXxxx
X     argument-translation routine. The value associated	with an
X     arg-list should be	a list structure of type ArgList. The
X     include file <parseargs.h>	defines	four macros for	manipu-
X     lating ArgList structures:	 ARGLISTNULL, L_NEXT, L_STRING,
X     and L_FLAGS.
X
X     ARGLISTNULL is simply the NULL argument-list pointer.
X     L_NEXT and	L_STRING each take a pointer to	a non-NULL
X     ArgList structure.	L_NEXT returns the address of the next
X     item in the list and L_STRING returns the string-value of
X     the current list-item.  L_FLAGS return the	arg-flags for a
X     given item	in the list. With non-multivalued, only	the flags
X     in	the argument descriptor	are needed; lists and vectors
X     however need a set	of flags for each item they contain. Once
X     an	arg-list has been created, it may be deallocated using
X     the function listFree. ListFree takes two parameters, the
X     first of which is the address of the first	item in	the arg-
X     list, and the second of which is a	boolean	value that is
X     TRUE only if each value pointed to	by each	item should also
X     be	deallocated.
X
X     An	alternative to argument-lists is argument vectors (or
X     arg-vectors).  Arg-vectors	use the	ARGVEC flag instead of
X     the ARGLIST flag and do not require a special listXxxx func-
X     tion for each vector-type.	 Each of the argXxxx functions is
X     responsible for handling vectors of its type (although some
X     argXxx functions such as the boolean types	do not support
X     vectors). An arg-vector is	a structure which contains a
X     count, an array of	elements (i.e. an argc/argv pair), and an
X     array of flags, one for each element of argv. There are two
X     macros in defined in <parseargs.h>	which are used for arg-
X     vectors. ARGVEC_T may be used to declare a	vector structure
X     or	a vector type; ARGVEC_EMPTY may	be used	to initialize the
X     structure.	 It is strongly	recommended that ARGVEC_T be used
X     to	declare	vector types in	a typedef statement (particularly
X     if	one is using function prototypes) but for those	who
X     insist, it	may be used to directly	declare	a  structure.
X     String-vectors will always	have an	extra NULL-pointer at the
X     end such that:
X
X	  ( StrVec.array[ StrVec.count ] == (char *)NULL )
X
X     is	always true, and character-vectors will	always have an
X     extra NUL-character at the	end such that:
X
X
X
X
Page 12
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  ( CharVec.array[ CharVec.count ] == '\0' )
X
X     is	always true. Integer and floating point	vectors	contain
X     no	extra "null" elements.
X
X     Once created, arg-vectors may be deallocated by calling the
X     macro vecFree or the macro	vecDeepFree and	passing	it the
X     arg-vector	structure. The differemce between these	two mac-
X     ros is that the latter will also free each	item in	the vec-
X     tor that required space to	be allocated (at the expense of
X     traversing	the vector).  At this writing, the only	prede-
X     fined argument-types that would benefit from vecDeepFree is
X     argStr vectors.
X
X     An	example	use of arg-lists, and of arg-vectors follows:
X
X	  #include <parseargs.h>
X
X	  typedef ARGVEC_T(char	*) strvec_t;
X
X	  static ArgList  *StringList =	ARGLISTNULL;
X	  static strvec_t  StringVec = ARGVEC_EMPTY(char *);
X	  static ARGVEC_T(int)	NumberVec = ARGVEC_EMPTY(int);
X
X	  static
X	    CMD_OBJECT	Args
X	    CMD_NAME	"foo --	do whatever foo	does"
X	    CMD_DESCRIPTION  "put a brief paragraph here"
X	    CMD_ARGUMENTS
X	       'l', ARGLIST, listStr, __ &StrList, "LiSt {list of strings}",
X	       's', ARGVEC,  argStr,  __ &StrVec,  "STRing {vector of strings}",
X	       'i', ARGVEC,  argInt,  __ &NumVec,  "NUMber {vector of numbers}",
X	       END_ARGUMENTS
X	    CMD_END
X
X	  main(	int argc, char *argv[] )
X	  {
X	     int i, *ls;
X
X	     if	( parseargs(argv, Args)	)  syserr( "parseargs failed" );
X
X	     for ( ls =	StrList, i=1 ; ls ; ls = L_NEXT(ls), i++ )
X		printf(	"List item %d=%s, flags=%x\n",
X			i, L_STRING(ls), L_FLAGS(ls) );
X
X	     for ( i = 0 ; i < StrVec.count ; i++ )
X		printf(	"String[%d]=%s,	flags=%x\n",
X			i, StrVec.array[i], StrVec.flags[i] );
X
X	     for ( i = 0 ; i < NumVec.count ; i++ )
X		printf(	"Number[%d]=%s,	flags=%x\n",
X			i, NumVec.array[i], NumVec.flags[i] );
X
X
X
Page 13
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	     listFree( StrList );
X	     StrList = ARGLISTNULL;
X
X	     vecDeepFree( StrVec, char * );
X	     vecFree( NumVec, int );
X
X	     exit( 0 );
X	  }
X
X
ARGUMENT TYPE FUNCTIONS
X     The argument types	recognized by parseargs	can be extended
X     by	adding new type	functions.  Argument type functions are
X     declared as:
X
X	  BOOL	argXxx(	 ARGDESC *ad,  char *vp,  BOOL copyf  )
X
X     The argd argument points to the descriptor	for the	argument
X     being converted.  Its main	use is to find the location in
X     which to store the	converted value, located in
X     argd->ad_valp.  The string	value to be converted is passed
X     in	argp (which will be NULL if the	ARGNOVAL flag was set for
X     the corresponding entry in	the arg-descriptor table).  The
X     copyf flag	is TRUE	if the argp string value must be copied
X     when saved.  Most non-string types	are copied implicitly
X     (for example, integer arguments are stored	in binary form,
X     so	the original string value need not be saved), so this
X     argument can usually be ignored.  Put simply, this	flag is
X     TRUE when argp points to a	temporary buffer area.
X
X     If	the type function successfully converts	the value, and
X     uses the entire value, it should return TRUE.  If the type
X     function successfully converts the	value, and uses	only N
X     characters	of the value, it should	return -N.  Otherwise, it
X     should print a message using usrerr(3) and	return FALSE.
X     This message should be of the form	"invalid xxxx option
X     'yyyy' for	Zzzz", where xxxx is the type of the option, yyyy
X     is	the string passed in vp, and zzzz is the name (taken from
X     ad->ad_prompt).  The argXxxx function is responsible for
X     detecting if the given argument descriptor	is an ARGVEC
X     argument and for taking the appropriate action.
X
X     For example, a type function that took a filename and stored
X     an	open file pointer might	be coded as:
X
X	  #define REALLOC(ptr,size)  ((! ptr) ?	malloc(size) : realloc(ptr, size))
X	  typedef ARGVEC_T(FILE	*)  FILEvec_t;
X
X	  BOOL	argReadFile(  ARGDESC *ad,  char *vp,  BOOL copyf  )
X	  {
X	       register	FILE *fp;
X	       fp = fopen(vp, "r");
X
X
X
Page 14
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	       if ( ! fp ) {
X		    usrerr("cannot open	'%s' for reading", vp);
X		    return (FALSE);
X	       }
X	       if ( BTEST(arg_flags(ad), ARGVEC) ) {
X		    FILEvec_t  *vec = (FILEvec_t *) arg_valp(ad);
X		    size_t  size  = (1 + vec->count) * (sizeof (FILE *));
X
X		    vec->array = (FILE **) REALLOC(vec->array, size);
X		    if ( ! vec->array )
X			 syserr( "(m|re)alloc failed in	argReadFile" );
X		    vec->flags = (FILE **) REALLOC(vec->flags, size);
X		    if ( ! vec->flags )
X			 syserr( "(m|re)alloc failed in	argReadFile" );
X
X		    vec->flags[	vec->count ] = arg_flags(ad);
X		    vec->array[	(vec->count)++ ] = fp;
X	       }
X	       else
X		    *(FILE *) arg_valp(ad) = fp;
X	       return (TRUE);
X	  }
X
LONG OPTIONS
X     Under UNIX, Parseargs also	allows for long	options	in addi-
X     tion to single character options. Long options are	denoted
X     by	a `+' character	(which may be changed using keywordpre-
X     fix). The keyword that is used is the first word in the
X     prompt field of an	argument descriptor entry.  Long options
X     are case insensitive! An argument to a long option	may be
X     separated from the	long option by an equal	sign (`=') or by
X     one or more whitespace characters.	 Thus, if an entry looks
X     like:
X
X     then ``-c4'', ``+repcount=4'', ``+count=4'', ``+rep-
X     count 4'',	and ``+count 4'' will all have the same	effect.
X
X     The long option names for ``-?'' in the default argument
X     descriptor	are ``+help'' and ``+?'' (respectively). In addi-
X     tion, ``++'' or ``+endopts'' may be used to indicate the end
X     of	options	so that	all remaining arguments	will be	inter-
X     preted as positional parameters (even if one begins with a
X     `+' or a `-').
X
X     Under VAX/VMS and AmigaDOS, single-character options are not
X     used and the ``long'' name	(in the	prompt field of	an argu-
X     ment descriptor) is always	used to	match for possible argu-
X     ments (or keywords, or qualifiers).
X
X     For all supported operating systems, a long option	may be
X     matched in	one of two ways: it may	match all uppercase char-
X     acters in the prompt field, or it may match all characters
X
X
X
Page 15
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     in	the prompt field (as in	``+count=4'' and ``+rep-
X     count=4'').
X
X     Under UNIX	and VAX/VMS, only the number of	characters
X     required to uniquely identify the desired argument	are
X     needed, but at least two characters must be given (unless
X     the prompt	field is itself	less than two characters long).
X     This means	that using the above example, that ``+rep=4'' and
X     ``+cou=4''	would also work	but ``+c=4'' would NOT (in other
X     words, if you only	want to	use one	character, use ``-c4''
X     instead).
X
X     Under VAX/VMS, the	possibilities using the	above example
X     would be:	``/REPCOUNT=4'', ``/COUNT=4'', ``/REP=4'', and
X     ``/COU=4'',
X
X     Under AmigaDOS, no	``shortened'' keywords are accepted and
X     the possibilities using the above example would be:  ``REP-
X     COUNT 4'',	and ``COUNT 4''
X
RETURN VALUE
X     The functions in the parseargs library will return	a value
X     of	zero upon succesful completion.	They may however, return
X     any of the	following status codes (which are defined in
X     <parseargs.h>):
X
X     pe_SYSTEM
X	  A system error occurred. The global variable errno may
X	  indicate the problem (then again, it may not).
X
X     pe_SUCCESS
X	  Success, no errors encountered (zero is returned).
X
X     pe_SYNTAX
X	  A command-line syntax	error was encountered
X
X     pe_DEFARGS
X	  An attempt (using parsecntl) was made	to change the
X	  default arg-search list of a command to point	to an
X	  argdesc-array	which already has the given command on
X	  its default arg-search list (which would cause an
X	  infinite loop	when attempting	to match an unknown
X	  command-line argument).
X
X     pe_NOMATCH
X	  Unable to match the named argument. This occurs when
X	  the argument keyword name passed to parsecntl	(using
X	  the pc_ARGFLAGS functions code) was found in the given
X	  argdesc-array	or in its default-list.
X
X     pe_BADMODE
X	  Bad mode for given command in	parsecntl. This	occurs
X
X
X
Page 16
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X	  when pc_WRITE	or pc_RDWR mode	is passed to parsecntl in
X	  conjunction with the pc_ARGFLAGS functions code.  Par-
X	  secntl will not modify existing arguments.
X
X     pe_BADCNTL
X	  Bad command for parsecntl. This occurs if an unknown
X	  function-code	was passed to parsecntl.
X
SEE ALSO
X     argtype(3), parseargs(1), syserr(3)
X     The ``C Advisor'' column in UNIX Review Vol. 7 No.	11.
X
CAVEATS
X     Because of	the way	argument parsing is implemented	under
X     UNIX, MS-DOS, and OS/2, option arguments which contain a
X     leading dash (`-')	(or whatever the option	prefix character
X     is	defined	to be) may not be specified as a separate argu-
X     ment on the command line, it must be part of the same argu-
X     ment. That	is to say that if a program has	a -f option that
X     requires a	string argument, then the following:
X	  -f-arg
X
X     will properly assign the string ``-arg'' to the option
X     whereas the following:
X	  -f -arg
X
X     will be interpreted by parseargs as two option strings: the
X     first of which (``-f'') is	missing	a required argument and
X     the second	of which (``-arg'') will most likely be	flagged
X     as	an invalid option.
X
X     Similarly,	if the user requires an	ARGLIST	option to take
X     multiple arguments	with leading dashes then the following
X     method must be used: It is	a ``feature'' of parseargs that
X     ARGLIST arguments are always appended to the current list of
X     arguments for the given option. Thus, if ``-f'' is	an option
X     taking a list of arguments, then the following are	all
X     equivalent:
X	  -farg1 arg2
X
X	  -f arg1 arg2
X	  -farg1 -farg2
X
X	  -f arg1 -f arg2
X     Hence multiple ``leading dash'' arguments may specified as
X     follows:
X
X	  -f-dash_arg1 -f-dash_arg2  ...
X
BUGS
X     When a non-multivalued argument appears more than once on
X     the command-line then only	the last value supplied	is used.
X
X
X
Page 17
X
X
X
X
X
X
PARSEARGS(3)					     PARSEARGS(3)
X
X
X
X     A problem occurs however in the following scenario: suppose
X     `-s' is an	option that takes an optional string argument (nd
X     suppose `-x' is some boolean flag). Then if the following
X     command-line is issued:
X
X	  command  -s string  -x  -s
X
X     then, the argument	flags will properly correspond to the
X     second instance of	the `-s' option	(namely	ARGGIVEN will be
X     set but ARGVALGIVEN will be unset)	but the	value associated
X     with the option will be ``string''	(because the first
X     instance overwrote	the default).  Because of this,	it may be
X     safest to reassign	the default value if ARGGIVEN is set but
X     ARGVALGIVEN is unset.
X
AUTHOR
X     Eric Allman, University of	California, Berkeley
X
MODIFICATIONS
X     Modified to accept	a vector of arguments, better error mes-
X     sages, Unix keyword matching, and AmigaDOS	version	by Peter
X     da	Silva.
X
X     Rewritten by Brad Appleton.  Parseargs(1);	functions par-
X     secntl, sparseargs, fparseargs, lparseargs, and vparseargs;
X     argument types argUsage, argDummy,	argUBool, and argTBool;
X     argument flags ARGPOS, ARGVALOPT, ARGVALREQ, ARGVALGIVEN,
X     ARGNOVAL, and ARGVEC; and VAX/VMS version and IBM-PC version
X     by	Brad Appleton
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Page 18
X
X
X
SHAR_EOF
chmod 0664 parseargs/parseargs3.txt ||
echo 'restore of parseargs/parseargs3.txt failed'
Wc_c="`wc -c < 'parseargs/parseargs3.txt'`"
test 37108 -eq "$Wc_c" ||
	echo 'parseargs/parseargs3.txt: original size 37108, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= parseargs/parsecntl3.txt ==============
if test -f 'parseargs/parsecntl3.txt' -a X"$1" != X"-c"; then
	echo 'x - skipping parseargs/parsecntl3.txt (File already exists)'
	rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting parseargs/parsecntl3.txt (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'parseargs/parsecntl3.txt' &&
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
NAME
X     parsecntl - get and set attributes	of an argument descriptor
X     array
X
SYNOPSIS
X     #include <parseargs.h>
X
X     int  parsecntl( ARGDESC argd[],  parsecntl_t func,	 parsemode_t mode,  ...	)
X
X
DESCRIPTION
X     Parsecntl will read and/or	write the desired attributes of
X     the given command-object. The attributes to be operated upon
X     are specified by the second parameter to parsecntl. The
X     desired mode (read, write,	or both) are specified by the
X     third parameter to	parsecntl. If the operation to be per-
X     formed is pc_ARGFLAGS, then the fourth argument to	parsecntl
X     should be the keyword name	of the argument	whose flags are
X     to	be retrieved.  The last	parameter to parsecntl is always
X     the object	to contain the attribute(s) to be read/written.
X     If	the attribute(s) are to	be read	(regardless of whether or
X     not they are also being changed) then the last argument
X     should be a pointer to an object, otherwise the last argu-
X     ment should be the	object itself.
X
X     If	mode is	pc_READ, then the desired attributes are copied
X     into the object pointed to	by the last parameter. If the
X     mode is pc_WRITE, then the	attributes from	the last parame-
X     ter are copied to the command- object. If mode is pc_RDWR,
X     then the attributes pointed to by the last	parameter are
X     copied to the command-object, and then the	previous value of
X     these attributes (before they were	overwritten) is	copied
X     into the object pointed to	by the last parameter.
X
X     If	cntl is	pc_ARGFLAGS, then the only valid mode is pc_READ.
X     All other attributes may be written or read by parsecntl.
X
FUNCTION CODES
X     Each of the following function codes specifies an attribute
X     that is to	be manipulated by parsecntl.  The function code
X     is	the second parameter to	parsecntl. With	the exception of
X     pc_ARGFLAGS, each of the function codes corresponds to a
X     call to parsecntl using four parameters ( pc_ARGFLAGS uses	5
X     parameters). In each case,	the last parameter is either the
X     address of	a buffer to write the attribute	to, or the actual
X     buffer to read the	attribute from (depending upon the mode	-
X     the third parameter to parsecntl).
X
X     pc_PARSEFLAGS
X	  This function	code is	used to	read and/or modify the
X	  existing parsing parsing behavior. The fourth	parameter
X	  to parsecntl should be a combination of pc_XXXX
X
X
X
Page 1
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X	  bitmasks if the parse-flags are only being written,
X	  otherwise it should be a pointer to an argMask_t vari-
X	  able.
X
X     pc_ARGFLAGS
X	  This function	code may only be used to read the
X	  argument-flags of a named argument. It is an error to
X	  specify a mode that attempts to write	the argument-
X	  flags	with this function code. The fourth parameter to
X	  parsecntl should be the keyword name of the argument
X	  whose	flags are to be	read. The fifth	(and final) argu-
X	  ment should be a pointer to the argMask_t variable
X	  which	will receive the resulting argument-flags.
X
X     pc_DEFARGS
X	  This function	code is	used to	query or modify	the
X	  current default argument-descriptor list for the given
X	  command. The fourth parameter	to parsecntl should be
X	  the argument-descriptor array	to assign as the new
X	  default-list (or the address of an argdesc-array if the
X	  default list is being	retrieved).
X
X	  If a given option/qualifier does not appear to match
X	  any items in the argdesc-array, a  default argdesc-
X	  array	is then	searched to match the option. If it is
X	  STILL	unmatched then it is flagged as	such. The
X	  default-argdesc array	is automatically used by all
X	  programmer-defined argdesc-array but may be unset or
X	  reset	using the pc_DEFARGS function of parsecntl. In
X	  such a  manner, a  programmer	could specify a	different
X	  set of default-arguments to search for. Furthermore,
X	  default argdesc-arrays may also be assigned default
X	  argdesc-arrays, thus allowing	the programmer to define
X	  a whole search-list of default argdesc-arrays	for a
X	  given	command.
X
X	  This could prove useful in a situation where a set of
X	  commands have	a few common-options and differ	in their
X	  remaining ones. If the same main() were used for each
X	  command, then	main could define one common argdesc-
X	  array	and then a set of argdesc-arrays for each com-
X	  mand.	Main could then	figure out which argdesc-array to
X	  used based on	the name in argv[0], and set its default
X	  argdesc-array	to be the common argdesc-array,	as in the
X	  following:
X
X	  #include <parseargs.h>
X	       .
X	       .  variable declarations
X	       .
X
X	  static ARGDESC common_args[] = {
X
X
X
Page 2
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X	     STARTOFARGS,
X	     { 'L', ARGOPT, argBool, __	&lflag,	"list (list the	items)"	},
X	     { 'I', ARGOPT, argStr, __ &item, "item (item to use)" },
X	     ENDOFARGS
X	  };
X
X	  static ARGDESC cmd1_args[] = {
X	     STARTOFARGS,
X	     { 's', ARGOPT, argBool, __	&sflag,	"S (set	S)" },
X	     { 't', ARGOPT, argBool, __	&tflag,	"T (set	T)" },
X	     ENDOFARGS
X	  };
X
X	  static ARGDESC cmd2_args[] = {
X	     STARTOFARGS,
X	     { 'x', ARGOPT, argBool, __	&xflag,	"X (set	X)" },
X	     { 'y', ARGOPT, argBool, __	&yflag,	"Y (set	Y)" },
X	     ENDOFARGS
X	  };
X
X	  main(	int argc, char *argv[] )
X	  {
X	     ARGDESC *cmd = cmd1_args;
X	     int  rc;
X
X	     if	( strcmp(*argv,	"cmd2")	== 0 )
X		cmd = cmd2_args;
X
X	     rc	= parsecntl( cmd, pc_DEFARGS, pc_WRITE,	common_args );
X	     if	( rc !=	pe_SUCCESS )
X		syserr(	"unable	to set default args" );
X
X	     rc	= parseargs( argv, cmd );
X		.
X		.
X		.
X	  }
X
X	  Note that in the above call to parsecntl(3), that zero
X	  will be returned upon	success	and non-zero upon
X	  failure. If pe_DEFARGS is returned, then cmd is already
X	  on common_args's list	of defaults (and would result in
X	  an infinite loop while parsing).
X
X     pc_NAME
X
X     pc_PURPOSE
X
X     pc_DESCRIPTION
X	  Each of these	last three function codes are used to
X	  modify or query the name, purpose, or	description asso-
X	  ciated with a	command. The fourth parameter to
X
X
X
Page 3
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X	  parsecntl should be the new string to	use (or	the
X	  address of the string, a char** variable, to recieve
X	  the current value).
X
PARSE MODES
X     Parsecntl may be used to read current command attributes,
X     write (assign) new	command	attributes, or both. The mode
X     argument to parsecntl determines the which	of these three
X     alternatives are desired. If the programmer merely	wishes to
X     assign new	attributes, then invoking parsecntl in pc_WRITE
X     mode and passing the new attributes will do the job. If the
X     programmer	wishes simply to query attributes, then	invoking
X     parsecntl in pc_READ mode and passing a pointer to	the
X     desired object in which to	write the attribute settings will
X     suffice.
X
X     If	the programmer wishes to assign	new attributes and at the
X     same time find out	what the attributes were before	making
X     the assignment, then programmer must invoke parsecntl for
X     pc_RDWR mode and pass a pointer to	the object containing the
X     new attribute settings; When parsecntl returns, then (assum-
X     ing it returns 0) the desired attributes will have	been
X     assigned and the object that contained the	new attribute
X     settings will now contain the attribute settings that were
X     in	effect before parsecntl	was invoked.
X
PARSE FLAGS
X     The following bitmasks may	be combined in order to	modify
X     the behavior of the parseargs library. The	parse flags for	a
X     given may be set through the use of the parsecntl(3) func-
X     tion.
X
X     pa_PROMPT
X	  Prompt the user for any missing arguments that are
X	  required on the command-line.	No special escaping or
X	  quoting is performed on the user input. Required argu-
X	  ments	that expect a list of values will be repeatedly
X	  prompted for (one item per line) until a blank line
X	  (followed by a carriage return) is entered.
X
X     pa_IGNORE
X	  Ignore any unrecognized or improperly	specified
X	  command-line arguments and continue execution	of the
X	  program. Normally, if	an argument is unmatched (or is
X	  improperly specified), a usage message is printed pro-
X	  gram execution is terminated.
X
X     pa_OPTSONLY
X	  Under	UNIX, setting this flag	will disable the parsing
X	  of long-option syntax. This will cause all arguments
X	  starting with	`+' to always be treated as a positional
X	  parameter (instead of	a long-option).
X
X
X
Page 4
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X     pa_KWDSONLY
X	  Under	UNIX, setting this flag	disables the parsing of
X	  single-character options.  This will cause all argu-
X	  ments	starting with `-' to always be treated as a posi-
X	  tional parameter (instead of an option).
X
X     pa_FLAGS1ST
X	  Setting this flag causes the parseargs library to force
X	  any and all non-positional arguments to be specified
X	  before any positional	ones.  As an example, under UNIX,
X	  if this flag is SET then parseargs will consider the
X	  command line "cmd -x arg" to consist of one option and
X	  one positional argument; however the command line "cmd
X	  arg -x" would	be considered to consist of two	posi-
X	  tional arguments (the	-x option will be unmatched).
X
X	  If this flag is UNSET, then both of the previous exam-
X	  ples are considered to consist of one	option and one
X	  positional argument.
X
X     pa_ANYCASE
X	  Setting this flag will cause character-case to be
X	  ignored when attempting to match single-character argu-
X	  ment names (i.e. causes "-i" and "-I"	will be	con-
X	  sidered equivalent).
X
X     pa_ARGV0
X	  Normally, the	parseargs library will assume that the
X	  first	argument on the	command-line is	the name of the
X	  command. Setting this	flag tells parseargs that this is
X	  NOT the case and that	the very first argument	on the
X	  command-line is a bona-fide argument to the command.
X
X     pa_NOCHECK
X	  Setting this flag will prevent parseargs from	checking
X	  for any required arguments that were not given on the
X	  command-line.	This is	useful when more than one call to
X	  the parseargs	library	is needed to parse all the
X	  command-line arguments (which	could occur if the
X	  command-line argument	came from a file or from two
X	  argv-vectors).
X
X	  Keeping this flag on until the final set of arguments
X	  is parsed will cause parseargs to not	check for missing
X	  arguments until the last set of arguments has	been
X	  parsed (by the final call to *parseargs).
X
X     pa_CONTINUE
X	  Setting this flag will cause subsequent calls	to the
X	  parseargs library to NOT reset the current command-
X	  state. Hence,	all arguments will not be initially set
X	  to "NOT GIVEN" and other (normal) initializations are
X
X
X
Page 5
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X	  not be performed.  This is useful in conjunction with
X	  the pa_NOCHECK flag when more	than one call to par-
X	  seargs is required to	parse all the command arguments.
X	  In this scenario, pa_CONTINUE	should be unset	(the
X	  default setting) for the very	first call to parseargs,
X	  but should then be set before	any subsequent calls to
X	  parseargs are	made.
X
X     pa_NOCMDENV
X	  Setting this flag prevents parseargs from checking the
X	  CMD-NAME_ARGS	environment variable (or symbol) for any
X	  user-defined default command arguments.
X
X     pa_COPYF
X	  When this flag is OFF	(the default), a value of FALSE
X	  is provided as the copyf argument to all the arg-type
X	  (argXxxxx) functions when an argument	is matched. Set-
X	  ting this flag will cause a value of TRUE to be pro-
X	  vided	as the copyf argument to all the arg-type
X	  (argXxxxx) functions when an argument	is matched.
X
ARGUMENT FLAGS
X     These are the possible bitmasks that may be turned	ON or OFF
X     in	the ad_flags field of an ARGDESC structure.
X
X     ARGOPT
X	  This flag is actually	a dummy	flag (i.e. it is the
X	  default). This flag specifies	that the command-line
X	  argument is optional (need not appear	on the command-
X	  line). It is only needed if no other flags are used to
X	  define the given argument.  If other flags are given
X	  and ARGREQ is	NOT one	of them, then ARGOPT is	always
X	  assumed.
X
X     ARGREQ
X	  The associated command argument is required on the
X	  command-line.
X
X     ARGPOS
X	  The associated command argument is positonal.	The
X	  difference between using this	flag to	indicate a posi-
X	  tional argument and between using a blank in the
X	  ad_name field	to indicate a positional arguments is the
X	  following: If	this flag is set but the ad_name of the
X	  argument is non-blank, then this argument may	be
X	  matched either positionally or by keyword. If	the
X	  ad_name field	is blank, then this argument may only be
X	  matched positionally.
X
X     ARGNOVAL
X	  The associated command argument takes	no value (as in
X	  "-x value"); Its mere	presence (or lack thereof) on the
X
X
X
Page 6
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X	  command-line is sufficient to	determine the necessary
X	  action(s) to take (as	in "-x").  Boolean argument types
X	  and Pseudo-argument types automatically default to ARG-
X	  NOVAL.
X
X     ARGVALOPT
X	  This flag is used to indicate	that the command-line
X	  argument takes a value (as in	"-s string" or
X	  "/str=string") but that the value to this command-line
X	  argument is NOT required (hence simply "-s" or "/str"
X	  is also permissable).
X
X     ARGVALREQ
X	  Another "dummy" flag.	Unless ARGNOVAL	or ARGVALOPT is
X	  specified, ARGVALREQ is always assumed. This flag indi-
X	  cates	that the value to a command-line argument is
X	  required (hence "-s string" is okay but just "-s" is
X	  not).
X
X     ARGHIDDEN
X	  Don't	display	this argument in usage messages	but still
X	  attempt to match it against strings given on the
X	  command-line.
X
X     ARGLIST
X	  A variable number of values are used for this	argument
X	  (and hence may use more than one or two argv elements
X	  from the command-line	as in "-l val1 val2 ..."). The
X	  list of values must be stored	in an ArgList structure
X	  (NOT a vector	structure), an the corresponding
X	  argument-type	function should	be one of the listXxxx
X	  functions.
X
X     ARGVEC
X	  A variable number of values are used for this	argument
X	  (and hence may use more than one or two argv elements
X	  from the command-line	as in in "-v val1 val2 ..."). The
X	  list of values must be stored	in a vector structure
X	  (NOT an ArgList structure).
X
X     The following bitmasks may	also be	present, but, unlike the
X     above masks which must be specified by the	programmer at
X     initialization time, the following	masks must only	be read
X     (never set) by the	programmer. They may be	queried	by using
X     the pc_ARGFLAGS function code and the mode	pc_READ	with par-
X     secntl(3).
X
X     ARGGIVEN
X	  The argument WAS given on the	command-line.
X
X     ARGVALGIVEN
X	  The value for	this argument was given	on the command-
X
X
X
Page 7
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X	  line.
X
X     ARGVALSEP
X	  The value to this argument was supplied in a separate
X	  argv element from the	argument itself	(as in "-x value"
X	  as opposed to	"-xvalue").
X
X     ARGKEYWORD
X	  This argument	was matched as a keyword (long-form) on
X	  the command-line and not as a	single character.
X
X     ARGDESCRIBED
X	  This argument	was given a description	by the programmer
X	  at initialization.
X
X     ARGCOPYF
X	  This flag is only used for lists and vectors (mul-
X	  tivalued arguments) and is used on a per-item	basis. If
X	  it is	set, it	means that the corresponding value in the
X	  vector/list required space to	be allocated (such as the
X	  duplication of a temporary string).
X
RETURN VALUE
X     The functions in the parseargs library will return	a value
X     of	zero upon succesful completion.	They may however, return
X     any of the	following status codes (which are defined in
X     <parseargs.h>):
X
X     pe_SYSTEM
X	  A system error occurred. The global variable errno may
X	  indicate the problem (then again, it may not).
X
X     pe_SUCCESS
X	  Success, no errors encountered (zero is returned).
X
X     pe_SYNTAX
X	  A command-line syntax	error was encountered
X
X     pe_DEFARGS
X	  An attempt (using parsecntl) was made	to change the
X	  default arg-search list of a command to point	to an
X	  argdesc-array	which already has the given command on
X	  its default arg-search list (which would cause an
X	  infinite loop	when attempting	to match an unknown
X	  command-line argument).
X
X     pe_NOMATCH
X	  Unable to match the named argument. This occurs when
X	  the argument keyword name passed to parsecntl	(using
X	  the pc_ARGFLAGS functions code) was found in the given
X	  argdesc-array	or in its default-list.
X
X
X
X
Page 8
X
X
X
X
X
X
PARSECNTL(3)					     PARSECNTL(3)
X
X
X
X     pe_BADMODE
X	  Bad mode for given command in	parsecntl. This	occurs
X	  when pc_WRITE	or pc_RDWR mode	is passed to parsecntl in
X	  conjunction with the pc_ARGFLAGS functions code.  Par-
X	  secntl will not modify existing arguments.
X
X     pe_BADCNTL
X	  Bad command for parsecntl. This occurs if an unknown
X	  function-code	was passed to parsecntl.
X
SEE ALSO
X     argtype(3),
X     parseargs(3),
X     parseargs(1)
X
AUTHOR
X     Brad Appleton  (brad@ssd.csd.harris.com)
X     Harris Computer Systems, Fort Lauderdale, FL USA
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Page 9
X
X
X
SHAR_EOF
chmod 0664 parseargs/parsecntl3.txt ||
echo 'restore of parseargs/parsecntl3.txt failed'
Wc_c="`wc -c < 'parseargs/parsecntl3.txt'`"
test 17278 -eq "$Wc_c" ||
	echo 'parseargs/parsecntl3.txt: original size 17278, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= parseargs/pgopen.c ==============
if test -f 'parseargs/pgopen.c' -a X"$1" != X"-c"; then
	echo 'x - skipping parseargs/pgopen.c (File already exists)'
	rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting parseargs/pgopen.c (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'parseargs/pgopen.c' &&
/*************************************************************************
** ^FILE: pgopen.c - pipe output to a pager for Unix Systems.
**
** ^DESCRIPTION:
**    The functions in this file implement a minimal paging system
**    using popen() & pclose() to invoke a specified paging program.
**
**    The following public functions are defined:
**
**       FILE *pgopen( FILE *fp, const char *pager_cmd )
**           -- attempt to open the pager, return the corresponding
**              file-pointer to write to (which will be <fp> if
**              popen(3S) fails).
**
**       int pgclose( FILE *pager_fp )
**           -- close the pager stream, return 0 on success
**
**       int pgactive( const FILE *pager_fp )
**           -- return TRUE if the pager is open.
**
** ^HISTORY:
**    12/03/90 	Brad Appleton 	<brad@ssd.csd.harris.com> 	Created
***^^**********************************************************************/
X
#ifdef  USE_PAGER
X
X
#include <stdio.h>
#include <signal.h>
#include <setjmp.h>
#include <useful.h>
X
/* get #defines for access() call */
#include <sys/file.h>
#ifndef X_OK
#  define X_OK  0x01
#endif
X
/*
**  Implement a state machine that tries first to use a pager
**  specified by the user, then as a second choice, /usr/ucb/more,
**  if all else fails use the given file-pointer (which we assume to
**  be writable)
**
**  The following defines the state machine.
**
*/
X
typedef enum  {
X   PG_CLOSED,  /* pager not-yet-open */
X   PG_NONE,    /* No pager used */
X   PG_ENV,     /* the given pager name (or $PAGER) was used */
X   PG_DFLT,    /* default pager (more) used */
X   PG_FILE     /* file-pointer used */
}  pager_t;
X
#define  DEFAULT_PAGER   "/usr/ucb/more"
X
#ifndef TRUE
#  define  TRUE  1
#endif
#ifndef FALSE
#  define  FALSE 0
#endif
X
#define MAX_NAME_LEN  512
#define isTERMINAL(fd)   ( isatty(fd) ) ? TRUE : (errno = 0, FALSE)
X
extern  char *strcpy();
extern  int   strcmp();
extern  int   access();
extern  int   isatty();
extern  int   wait();
extern  int   sleep();
X
extern  int  errno;
X
static void  pg_error();       /* broken-pipe exception handler */
static jmp_buf pg_recover;     /* jump-buffer for exception handler */
static pager_t  pg_pathname();
X
static pager_t  Pager_Type = PG_CLOSED;
static FILE    *Pager_FP = (FILE *)NULL;
X
X
/***************************************************************************
** ^FUNCTION: pgactive - query pager status
**
** ^SYNOPSIS:
*/
#ifndef __ANSI_C__
X   int pgactive( pager_fp )
/*
** ^PARAMETERS:
*/
X   FILE *pager_fp;
/*    -- the file-pointer returned by pgopen()
*/
#endif  /* !__ANSI_C__ */
X
/* ^DESCRIPTION:
**    Pgactive indicates whether or not the given file-pointer is in
**    use by the paging system.
**
** ^REQUIREMENTS:
**    pgopen() must first be called in order to obtain a valid
SHAR_EOF
true || echo 'restore of parseargs/pgopen.c failed'
fi
echo 'End of  part 8'
echo 'File parseargs/pgopen.c is continued in part 9'
echo 9 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...
-- 
Kent Landfield                   INTERNET: kent@sparky.IMD.Sterling.COM
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    (402) 291-8300         FAX:      (402) 291-4362
Please send comp.sources.misc-related mail to kent@uunet.uu.net.