Doxygen Documentation
Main Index	Package Index
Package:	CLI
Version:	V0-0-5	Marked:	(not marked)
Constituent:	cli	Tag:	sun-gcc

Interface Compound List File List Compound Members File Members

CLI_pubdefs.h File Reference

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

Defines

#define CLI_O_NEGATE   0x0001

Can be negated (qualifier only).

#define CLI_O_VALUE   0x0002

Must be valued (qualifier only).

#define CLI_O_NOVALUE   0x0004

Must not be valued (qualifier only).

#define CLI_O_REQUIRED   0x0008

Must be present.

#define CLI_T_LIST   0x0100

Value may be a list of values.

#define CLI_T_INTEGER   0x0200

Value must be integer.

#define CLI_T_FLOAT   0x0400

Value must be floating point.

#define CLI_T_KEYWORD   0x0800

Value is drawn from keyword list.

#define CLI_T_RESTOFLINE   0x1000

Value is rest of line (parameter only).

#define CLI_T_NEWSNTX   0x2000

Value starts a new syntax (parameter only).

#define CLI_SUCCESS   0x00000001

Success.

#define CLI_PRESENT   0x00000003

Qualifier present.

#define CLI_NEGATED   0x00000005

Qualifier present in negated form.

#define CLI_COMMA   0x00000007

Another parameter/qualifier value follows.

#define CLI_BADSNTX   0x00000002

Bad syntax (discovered in user callback).

#define CLI_ABSENT   0x00000004

Qualifier absent.

#define CLI_NOTCTL   0x00000006

(Opaque) control structure pointer isn't

#define CLI_NOTSNTX   0x00000008

(Opaque) syntax structure pointer isn't

#define CLI_ENDOFCMD   0xffffffff

Request exit from command processing.

Typedefs

typedef _CLI_KeyDef CLI_KeyDef

Typedef for struct _CLI_KeyDef.

typedef _CLI_KeyList CLI_KeyList

Typedef for struct _CLI_KeyList.

typedef _CLI_ParmDef CLI_ParmDef

Typedef for struct _CLI_ParmDef.

typedef _CLI_QualDef CLI_QualDef

Typedef for struct _CLI_QualDef.

typedef _CLI_VerbDef CLI_VerbDef

Typedef for struct _CLI_VerbDef.

typedef _CLI_Syntax CLI_Syntax

Typedef for struct _CLI_Syntax.

typedef _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.

Functions

CLI_Syntax * CLI_createSyntax (const char *)

Create a new CLI syntax.

CLI_KeyList * CLI_createKeyList (const char *)

Create a new CLI keyword list.

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

Add a key to a CLI keyword list.

CLI_VerbDef * CLI_addVerb (const CLI_Syntax *, const char *, const char *, CLI_CB_Func *)

Add a verb to a CLI syntax.

CLI_ParmDef * CLI_addParm (CLI_VerbDef *, unsigned short, unsigned short, void *)

Add a parameter to a CLI verb.

CLI_QualDef * CLI_addQual (CLI_VerbDef *, const char *, unsigned short, unsigned short, CLI_KeyList *)

Add a qualifier to a CLI verb.

unsigned int CLI_command (const char *, const char *, const CLI_Syntax *, void *)

Process commands.

unsigned int CLI_present (CLI_Control *, const char *)

Test for the presence of a qualifier.

unsigned int CLI_getValue (const CLI_Control *, const char *, const char **)

Return the value of some object.

Detailed Description

Standard public include file for the CLI package.

CVS $Id: CLI_pubdefs.h,v 1.4 2003/12/12 06:13:49 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.

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.

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

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

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).

unsigned int CLI_command ( const char * ilin,

const char * prompt,

const CLI_Syntax * syntax,

void * user

)

Process commands.

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).

CLI_KeyList * CLI_createKeyList ( const char * name )

Create a new 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.

CLI_Syntax * CLI_createSyntax ( const char * name )

Create a new 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.

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>

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

Generated on Thu Dec 11 22:17:54 2003 by

1.3.3


Defines
#define	CLI_O_NEGATE 0x0001
	Can be negated (qualifier only).
#define	CLI_O_VALUE 0x0002
	Must be valued (qualifier only).
#define	CLI_O_NOVALUE 0x0004
	Must not be valued (qualifier only).
#define	CLI_O_REQUIRED 0x0008
	Must be present.
#define	CLI_T_LIST 0x0100
	Value may be a list of values.
#define	CLI_T_INTEGER 0x0200
	Value must be integer.
#define	CLI_T_FLOAT 0x0400
	Value must be floating point.
#define	CLI_T_KEYWORD 0x0800
	Value is drawn from keyword list.
#define	CLI_T_RESTOFLINE 0x1000
	Value is rest of line (parameter only).
#define	CLI_T_NEWSNTX 0x2000
	Value starts a new syntax (parameter only).
#define	CLI_SUCCESS 0x00000001
	Success.
#define	CLI_PRESENT 0x00000003
	Qualifier present.
#define	CLI_NEGATED 0x00000005
	Qualifier present in negated form.
#define	CLI_COMMA 0x00000007
	Another parameter/qualifier value follows.
#define	CLI_BADSNTX 0x00000002
	Bad syntax (discovered in user callback).
#define	CLI_ABSENT 0x00000004
	Qualifier absent.
#define	CLI_NOTCTL 0x00000006
	(Opaque) control structure pointer isn't
#define	CLI_NOTSNTX 0x00000008
	(Opaque) syntax structure pointer isn't
#define	CLI_ENDOFCMD 0xffffffff
	Request exit from command processing.
Typedefs
typedef _CLI_KeyDef	CLI_KeyDef
	Typedef for struct _CLI_KeyDef.
typedef _CLI_KeyList	CLI_KeyList
	Typedef for struct _CLI_KeyList.
typedef _CLI_ParmDef	CLI_ParmDef
	Typedef for struct _CLI_ParmDef.
typedef _CLI_QualDef	CLI_QualDef
	Typedef for struct _CLI_QualDef.
typedef _CLI_VerbDef	CLI_VerbDef
	Typedef for struct _CLI_VerbDef.
typedef _CLI_Syntax	CLI_Syntax
	Typedef for struct _CLI_Syntax.
typedef _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.
Functions
CLI_Syntax *	CLI_createSyntax (const char *)
	Create a new CLI syntax.
CLI_KeyList *	CLI_createKeyList (const char *)
	Create a new CLI keyword list.
CLI_KeyDef *	CLI_addKey (const CLI_KeyList , const char )
	Add a key to a CLI keyword list.
CLI_VerbDef *	CLI_addVerb (const CLI_Syntax , const char , const char , CLI_CB_Func )
	Add a verb to a CLI syntax.
CLI_ParmDef *	CLI_addParm (CLI_VerbDef , unsigned short, unsigned short, void )
	Add a parameter to a CLI verb.
CLI_QualDef *	CLI_addQual (CLI_VerbDef , const char , unsigned short, unsigned short, CLI_KeyList *)
	Add a qualifier to a CLI verb.
unsigned int	CLI_command (const char , const char , const CLI_Syntax , void )
	Process commands.
unsigned int	CLI_present (CLI_Control , const char )
	Test for the presence of a qualifier.
unsigned int	CLI_getValue (const CLI_Control , const char , const char **)
	Return the value of some object.