CLI_pubdefs.h File Reference

Standard public include file for the CLI package. More...

#include <time.h>
#include <CLI/CLI_msgs.h>

Defines
#define	CLI_L_TIMESTAMP   20
#define	CLI_O_NEGATE   0x0001
#define	CLI_O_VALUE   0x0002
#define	CLI_O_NOVALUE   0x0004
#define	CLI_O_REQUIRED   0x0008
#define	CLI_T_LIST   0x0100
#define	CLI_T_INTEGER   0x0200
#define	CLI_T_FLOAT   0x0400
#define	CLI_T_KEYWORD   0x0800
#define	CLI_T_RESTOFLINE   0x1000
#define	CLI_T_NEWSNTX   0x2000
#define	CLI_T_TIMESTAMP   0x4000
Typedefs
typedef enum _CLI_Timezone	CLI_Timezone
	Typedef for enum _CLI_Timezone.
typedef struct _CLI_KeyDef	CLI_KeyDef
	Typedef for struct _CLI_KeyDef.
typedef struct _CLI_KeyList	CLI_KeyList
	Typedef for struct _CLI_KeyList.
typedef struct _CLI_ParmDef	CLI_ParmDef
	Typedef for struct _CLI_ParmDef.
typedef struct _CLI_QualDef	CLI_QualDef
	Typedef for struct _CLI_QualDef.
typedef struct _CLI_VerbDef	CLI_VerbDef
	Typedef for struct _CLI_VerbDef.
typedef struct _CLI_Syntax	CLI_Syntax
	Typedef for struct _CLI_Syntax.
typedef struct _CLI_Control	CLI_Control
	Typedef for struct _CLI_Control.
typedef unsigned int	CLI_CB_Func (CLI_Control *, void *)
	Typedef for a CLI verb callback routine.
Enumerations
enum	_CLI_Timezone {   CLI_K_TIMEZONE_LOCAL = 0,   CLI_K_TIMEZONE_UTC = 1 }
	Enumeration of enumeration tables FMX recognizes (!). More...
Functions
CLI_KeyDef *	CLI_addKey (const CLI_KeyList *list, const char *name)
	Add a key to a CLI keyword list.
CLI_ParmDef *	CLI_addParm (CLI_VerbDef *verb, unsigned short opts, unsigned short type, void *sork)
	Add a parameter to a CLI verb.
CLI_QualDef *	CLI_addQual (CLI_VerbDef *verb, const char *text, unsigned short opts, unsigned short type, CLI_KeyList *list)
	Add a qualifier to a CLI verb.
CLI_VerbDef *	CLI_addVerb (const CLI_Syntax *sntx, const char *name, const char *call, CLI_CB_Func *func)
	Add a verb to a CLI syntax.
CLI_Syntax *	CLI_createSyntax (const char *name)
	Allocate and initialize a CLI syntax.
unsigned int	CLI_command (const char *ilin, const char *prompt, const CLI_Syntax *syntax, void *user)
	Parse and dispatch command lines.
CLI_KeyList *	CLI_createKeyList (const char *name)
	Allocate and initialize a CLI keyword list.
unsigned int	CLI_getValue (const CLI_Control *ctl, const char *text, const char **valu)
	Return the value of some object.
time_t	CLI_timeString2Unix (const char *text, CLI_Timezone zone)
	Parse a string timestamp into a unix calendar time.
void	CLI_timeUnix2String (time_t time, char *text, CLI_Timezone zone)
	Parse a unix calendar time into a string timestamp.
unsigned int	CLI_present (CLI_Control *ctl, const char *text)
	Test for the presence of a qualifier.
void	CLI_stitchCommandFree (char *line)
	Free the buffer allocated by CLI_stitchCommandLine().
char *	CLI_stitchCommandLine (int argc, char *argv[])
	Reconstruct the unix (?) command line, preserving tokenization.

---

Detailed Description

Standard public include file for the CLI package.

CVS $Id: CLI_pubdefs.h,v 1.6 2011/03/25 00:51:24 apw Exp $

Author:

A.P.Waite - apw@slac.stanford.edu

The standard CLI user interface is available through this file. It provides the function prototypes for the callable routines as well as a set of macros needed to access them sensibly.

The other public interface file CLI_dmpdefs.h should only be included in cases where access to the debugging/dumping routines is also required (in which case the shareable clidmp.so must be added to the calling program's link step ... see "TV" for an example of how to do this).

---

Typedef Documentation

unsigned int CLI_CB_Func

Typedef for a CLI verb callback routine.

This defines the signature of a CLI callback function. The first argument is an opaque pointer to a CLI control structure. It should be passed through unaltered as the first argument to the CLI_getValue() and CLI_present() routines. The second argument is simply the user argument which was given in the call to CLI_command(). It's provided for the user to pass context through to the callback routines.

---

Enumeration Type Documentation

enum _CLI_Timezone

Enumeration of enumeration tables FMX recognizes (!).

Enumerator:

CLI_K_TIMEZONE_LOCAL	Convert in date in local timezone
CLI_K_TIMEZONE_UTC	Convert as date in UTC

---

Function Documentation

CLI_KeyDef * CLI_addKey	(	const CLI_KeyList *	list,
		const char *	name
	)

Add a key to a CLI keyword list.

Parameters:

	list	(Opaque) pointer to keyword list
	name	Name of this keyword

Return values:

	NULL	Failure
	x	Success

Add a keyword to a CLI keyword list. Returns a handle to the keyword.

References _CLI_KeyList::key, _CLI_KeyDef::next, _CLI_KeyDef::text, and _CLI_KeyDef::tlen.

CLI_ParmDef * CLI_addParm	(	CLI_VerbDef *	verb,
		unsigned short	opts,
		unsigned short	type,
		void *	sork
	)

Add a parameter to a CLI verb.

Parameters:

	verb	(Opaque) pointer to verb
	opts	Option flags for this parameter
	type	Type constraints for this parameter
	sork	Overloaded (opaque) pointer. When the parameter type includes the CLI_T_KEYWORD option, sork should point to a keyword list. When the parameter type is CLI_T_NEWSNTX, sork should point to a syntax. Otherwise this parameter is ignored. (The name derives from Syntax OR Keyword).

Return values:

	NULL	Failure
	x	Success

Add a parameter to a CLI verb. Returns a handle for the parameter.

The opts and type arguments should be supplied as an OR of the provided C macros. There are occasions where options and types interact such that one excludes another (e.g. for a qualifier it makes no sense to define it as both requiring a value (CLI_O_VALUE) and not requiring a value (CLI_O_NOVALUE)). Such exclusions are noted in the tables which follow. The CLI routines will detect clashing options/types. When multiple types are OR'd together (e.g. CLI_T_INTEGER | CLI_T_KEYWORD), the parsed value can be either an integer or be drawn from a keyword list.

Parameter options:

C Macro	Meaning	Excluded Options	Excluded Types
CLI_O_REQUIRED	Parameter must be provided	none	none

Parameter types:

C Macro	Meaning	Excluded Options	Excluded Types
CLI_T_LIST	Value may be a comma separated list of values	none	CLI_T_RESTOFLINE CLI_T_NEWSNTX
CLI_T_INTEGER	Value must be an integer	none	CLI_T_RESTOFLINE CLI_T_NEWSNTX
CLI_T_FLOAT	Value must be an floating point number	none	CLI_T_RESTOFLINE CLI_T_NEWSNTX
CLI_T_KEYWORD	Value must be drawn from a list of keywords	none	CLI_T_RESTOFLINE CLI_T_NEWSNTX
CLI_T_RESTOFLINE	Value if the rest of the line	All options except CLI_O_REQUIRED	All other types
CLI_T_NEWSNTX	Pass the rest of the line to a new syntax	All options except CLI_O_REQUIRED	All other types

References _CLI_ParmDef::next, _CLI_ParmDef::opts, _CLI_VerbDef::parm, _CLI_VerbDef::preq, _CLI_ParmDef::sork, _CLI_ParmDef::type, and _CLI_VerbDef::type.

Referenced by CLI_createSyntax().

CLI_QualDef * CLI_addQual	(	CLI_VerbDef *	verb,
		const char *	text,
		unsigned short	opts,
		unsigned short	type,
		CLI_KeyList *	list
	)

Add a qualifier to a CLI verb.

Parameters:

	verb	(Opaque) pointer to verb
	text	Qualifier text (name)
	opts	Option flags for this qualifier
	type	Type constraints for this qualifier
	list	(Opaque) pointer to keyword list (only needed for type "keyword")

Return values:

	NULL	Failure
	x	Success

Add a qualifier to a CLI verb. Returns a handle to the qualifier.

The opts and type arguments should be supplied as an OR of the provided C macros. There are occasions where options and types interact such that one excludes another (e.g. for a qualifier it makes no sense to define it as both requiring a value (CLI_O_VALUE) and not requiring a value (CLI_O_NOVALUE)). Such exclusions are noted in the tables which follow. The CLI routines will detect clashing options/types. When multiple types are OR'd together (e.g. CLI_T_INTEGER | CLI_T_KEYWORD), the parsed value can be either an integer or be drawn from a keyword list.

Qualifier options:

C Macro	Meaning	Excluded Options	Excluded Types
CLI_O_NEGATE	Qualifier can be negated	none	none
CLI_O_VALUE	Qualifier must have a value	CLI_O_NOVALUE	none
CLI_O_NOVALUE	Qualifier must not have a value	CLI_O_VALUE	none
CLI_O_REQUIRED	Qualifier must be provided	none	none

Qualifier types:

C Macro	Meaning	Excluded Options	Excluded Types
CLI_T_LIST	Value may be a comma separated list of values	none	none
CLI_T_INTEGER	Value must be an integer	none	none
CLI_T_FLOAT	Value must be an floating point number	none	none
CLI_T_KEYWORD	Value must be drawn from a list of keywords	none	none

References _CLI_QualDef::list, _CLI_QualDef::next, _CLI_QualDef::opts, _CLI_VerbDef::qual, _CLI_QualDef::spare, _CLI_QualDef::text, _CLI_QualDef::tlen, and _CLI_QualDef::type.

CLI_VerbDef * CLI_addVerb	(	const CLI_Syntax *	sntx,
		const char *	name,
		const char *	call,
		CLI_CB_Func *	func
	)

Add a verb to a CLI syntax.

Parameters:

	sntx	(Opaque) pointer to syntax
	name	Name of the verb
	call	Name of callback function associated with this verb
	func	Address of callback function associated with this verb

Return values:

	NULL	Failure
	x	Success

Add a verb to a CLI syntax. Returns a handle which the caller uses in subsequent calls to CLI_addParm() and CLI_addQual() to build up the syntax associated with this verb.

Naming the callback function (argument name) is implemented for future expansion (it has no current use).

References _CLI_VerbDef::call, _CLI_VerbDef::func, _CLI_VerbDef::id, _CLI_VerbDef::next, _CLI_VerbDef::parm, _CLI_VerbDef::preq, _CLI_VerbDef::qual, _CLI_VerbDef::text, _CLI_VerbDef::tlen, _CLI_VerbDef::type, and _CLI_Syntax::verb.

Referenced by CLI_createSyntax().

unsigned int CLI_command	(	const char *	ilin,
		const char *	prompt,
		const CLI_Syntax *	syntax,
		void *	user
	)

Parse and dispatch command lines.

Parameters:

	ilin	Input line to parse (can be NULL or blank)
	prompt	Command prompt to use (when in subcommand mode)
	syntax	(Opaque) pointer to syntax to use to decode lines
	user	(Opaque) pointer to user parameter(s)

Returns:

Status code

CLI_command parses and dispatches command lines. It handles the direct command case (when ilin contains a real string) and the 'enter subcommand' case (when ilin is NULL or blank).

References CLI_clearFiles(), CLI_clearTokens(), CLI_createCtl(), CLI_getFile(), CLI_getTerm(), CLI_parse(), _CLI_Control::file, _CLI_File::frst, _CLI_Syntax::id, _CLI_File::last, _CLI_File::name, and _CLI_Control::tokens.

Referenced by CLI_parse().

CLI_KeyList * CLI_createKeyList

(

const char *

name

)

Allocate and initialize a CLI keyword list.

Parameters:

name

Name of keyword list

Return values:

	NULL	Failure
	x	Success

Allocate and initialize a CLI keyword list. Returns a handle which the caller uses in subsequent calls to CLI_addKey() to populate the list.

References CLI_keyListList, _CLI_KeyList::id, _CLI_KeyList::key, _CLI_KeyList::name, _CLI_KeyList::next, and _CLI_KeyList::opts.

CLI_Syntax * CLI_createSyntax

(

const char *

name

)

Allocate and initialize a CLI syntax.

Parameters:

name

Name of syntax

Return values:

	NULL	Failure
	x	Success

Allocate and initialize a CLI syntax. Returns a handle which the caller uses in subsequent calls to CLI_addVerb() to build the list of verbs the syntax accepts.

References _CLI_VerbDef::call, CLI_addParm(), CLI_addVerb(), CLI_dumpSyntax(), CLI_indirect(), CLI_syntaxList, _CLI_Syntax::id, _CLI_Syntax::name, _CLI_Syntax::next, _CLI_VerbDef::text, and _CLI_Syntax::verb.

unsigned int CLI_getValue	(	const CLI_Control *	ctl,
		const char *	text,
		const char **	valu
	)

Return the value of some object.

Parameters:

	ctl	(Opaque) pointer to CLI control structure
	text	Text (name) of object to fetch
	valu	Returned value

Return values:

	CLI_ABSENT	No value found
	CLI_COMMA	Another value available
	CLI_NOTCTL	(Opaque) pointer does not point to CLI control structure
	CLI_SUCCESS	Value returned (and end of list if a list exists)

CLI_getValue is the one and only fetch command for parameters, qualifiers and some special cases. The table is as follows:

String	Returns
$line	Original command line
$verb	Verb from command line
$<n>	Value of parameter <n> (starting at zero)
<qualifier>	Value of qualifier <qualifier>

References _CLI_Qual::curr, _CLI_Parm::curr, _CLI_Control::id, _CLI_Tokens::line, _CLI_Qual::list, _CLI_Parm::list, _CLI_Qual::next, _CLI_Valu::next, _CLI_Parm::next, _CLI_Tokens::parm, _CLI_Tokens::qual, _CLI_Qual::text, _CLI_Valu::text, _CLI_Control::tokens, and _CLI_Tokens::verb.

Referenced by CLI_indirect().

unsigned int CLI_present	(	CLI_Control *	ctl,
		const char *	text
	)

Test for the presence of a qualifier.

Parameters:

	ctl	(Opaque) pointer to CLI control structure
	text	Text of the qualifier for which to search

Return values:

	CLI_ABSENT	Qualifier is absent
	CLI_NEGATED	Qualifier is present in its negated form
	CLI_NOTCTL	(Opaque) pointer does not point to CLI control structure
	CLI_PRESENT	Qualifier is present

References _CLI_Qual::flag, _CLI_Control::id, _CLI_Qual::next, _CLI_Tokens::qual, _CLI_Qual::text, and _CLI_Control::tokens.

Referenced by CLI_parse().

void CLI_stitchCommandFree

(

char *

line

)

Free the buffer allocated by CLI_stitchCommandLine().

Parameters:

line

(in) Command line pointer returned by CLI_stitchCommandLine()

CLI_stitchCommandFree() frees the memory allocated by a call to CLI_stitchCommandLine().

char * CLI_stitchCommandLine	(	int	argc,
		char *	argv[]
	)

Reconstruct the unix (?) command line, preserving tokenization.

Parameters:

	argc	(in) Number of command line tokens (pass through from "main")
	argv	(in) Token pointers (pass through from "main")

Returns:

x Pointer to reconstructed command line

Warning:

CLI_stitchCommandLine() allocates memory in which to construct the reconstructed command line. The caller is responsible for freeing this memory using the CLI_stitchCommandFree() call.

The canonical command line tokens delivered to a "main" routine can be stitched together by CLI_stitchCommandLine() in such a fashion that any tokenization constructed on the command line (via assorted quoting) is correctly preserved. This is a courtesy function and has no real function within CLI processing.

time_t CLI_timeString2Unix	(	const char *	text,
		CLI_Timezone	zone
	)

Parse a string timestamp into a unix calendar time.

Parameters:

	text	String timestamp (presumably a token from CLI parsing)
	zone	Zone in which to perform the conversion

Returns:

0 Invalid timestamp string

x Unix calendar time

References CLI_K_TIMEZONE_UTC, and validateTime().

void CLI_timeUnix2String	(	time_t	time,
		char *	text,
		CLI_Timezone	zone
	)

Parse a unix calendar time into a string timestamp.

Parameters:

	time	Unix calendar time
	text	String timestamp
	zone	Zone in which to perform the conversion

Returns:

0 Invalid timestamp string

x Unix calendar time

References CLI_K_TIMEZONE_UTC.