📄 comnd.doc
字号:
environment at the reparse point. If this value is
non-NULL, then if a reparse is required, a longjmp()
operation is performed using this setjmp buffer.
o CSB_INP is the address of the input-character routine to
use. If this value is non-NULL, then this routine is called
to get each character of input. No line editing or special
interactive characters are recognized in this mode, since it
is assumed that this will be used for file input. Note
especially: this facility is not yet implemented, however
the definition is provided for future expansion. Thou shalt
always leave this NULL, or write the facility thyself.
o CSB_OUT is the inverse correspondent to the previous element
(CSB_INP). It is the address of a routine to process output
from the command library. Please see the warning in the
CSB_INP description about not being implemented.
o CSB_PMT is the address of the prompt string to use for
command parsing. The command library takes care of
prompting, so make sure this is filled in.
o CSB_BUF is the address of the buffer to put user input into
as s/he is typing it in.
o CSB_BSZ, an int, is the number of bytes which can be stored
in CSB_BUF; i.e., it is the buffer size.
o CSB_ABF is the address of an atom buffer. Some (if not all)
parsing functions involve extracting some number of
characters from the input buffer and interpreting or simply
returning this extracted string. This buffer is necessary
for those operations. It should probably be as large as the
input buffer (CSB_BUF), but it is really up to you.
o CSB_ASZ, an int, is the number of characters which can be
stored in CSB_ABF; i.e., it is the size of that buffer.
** Note ** CSB elements from here to the end do not have to
be initialized by the calling program. They are used to
store state information and are initialized as required by
the library.
o CSB_PRS, an int, contains the parse index. This is the
point in the command buffer up to which parsing has been
achieved.
o CSB_FLN, an int, is the filled length of the command
buffer. This is the number of characters which have been
typed by the user.
o CSB_RCD, an int, is a result code of the parse. This is the
same value which is returned as the result of the COMND()
procedure call.
o CSB_RVL is a union which is used to contain either an int or
an address value. The names of the union elements are:
_INT for int, _ADR for address (note that a typecast should
be used for proper address assignment). This element
contains a value returned from some parse functions which
return values which are single values. For example, if an
integer is parsed, its value is returned here.
o CSB_CFB is the address of a command function block for which
a parse was successful. This is significant in cases where
there are alternative possible interpretations of the next
command line field.
The parse of each element in a command line involves, as well
as the Command State Block just described, a Command Function
Block which identifies the sort of thing to be parsed. This
block is defined in a structure named "CFBs", which has a
corresponding typedef named "CFB". Elements of the CFB, named
"CFB_xxx", are as follows (in the order they appear in the
structure):
o CFB_FNC, a BYTE, is the function code. This defines the
function to be performed. The function codes are listed,
and their actions described, a little later.
o CFB_FLG, a BYTE, contains flags which the caller specifies
to the library. These are very significant, and in most
cases affect the presentation to the user. The flag bits
are:
o _CFHPP: A help string has been supplied and should be
given when the user types the help character ("?").
o _CFDPP: A default string has been supplied, and shall be
used if the user does not type anything at this point
(typing nothing means typing a return or requesting
command completion). Note that this flag (and the
default string) is ONLY significant for the CFB passed in
the call to the COMND() routine, and not for any others
referenced as alternatives by that CFB. Note further
that a default specified by the first CFB is applied to
the input stream, and not to the parsing function. That
means that the default is subject to interpretation by
alternate CFBs, and in fact, does not even have to be
appropriate for the CFB which contains it.
o _CFSDH: The default help message should be supressed if
the user types the help character ("?"). This is
normally used in conjunction with the _CFHPP flag.
However, if this flag is present and the _CFHPP is not
selected, then the help operation is inhibited, and the
help character becomes insignificant (just like any other
character).
o _CFCC: A character characteristic table has been
provided. A CC table identifies which characters may be
part of the element being recognized. Not all functions
support this table (for example, it does not make sense
to re-specify which characters may compose decimal
numbers). This table also specifies which characters are
break characters, causing the parser to "wake up" the
calling program when one of them is typed. If this bit
is not set (as is usually the case), a default table is
associated according to the function code.
o _CFDTD: For parsing date and time, specifies that the
date should be parsed.
o _CFDTT: For parsing date and time, specifies that the
time should be parsed.
o CFB_CFB is the address of another CFB which may be invoked
if the user input does not satisfy this CFB. CFBs may be
chained in this manner at will. Recognize, however, that
the ORDER of the chain plays an important part in how input
is handled, particularly in disambiguation of input. Note
also that only the first CFB of the chain is used for
specifying a default string and CC table for command
wake-up.
CFB chaining is a very important part of parsing with this
library.
o CFB_DAT is defined as a long, since it is used to contain
address or int values. It should be referenced via
typecast. It is not defined as a union because it is
inconvenient or impossible to initialize unions at compile
time with most (all?) C compilers, and initialization of
these blocks at compile time is very desirable. This
element contains data used in parsing of a field in the
command line. For instance, in parsing an integer, the
caller specifies the default radix of the integer here.
o CFB_HLP is the address of a caller-supplied help string.
This is only significant if the flag bit _CFHPP is set in
the CFB_FLG byte.
o CFB_DEF is the address of a caller-supplied default string.
This is only significant if the flag bit _CFDPP is set in
the CFB_FLG byte, and only for the first CFB in the CFB
chain.
o CFB_CC is the address of a character characteristics table.
This is only significant if the flag bit _CFCC is set in the
CFB_FLG byte. This is the address of a 16-word table, each
word containing 16 bits which are interpreted as 8 2-bit
characteristic entries. The most significant bits
correspond to the lower ASCII values, etc. The 2-bit binary
value has the following meaning, per character:
o 00: Character may not be part of the element being
parsed.
o 01: Character may be part of the element only if it is
not the first character of that element.
o 10: Character may be part of the element.
o 11: Character may not be part of the element;
furthermore, when it is typed, it will case parsing to
begin immediately (a wake-up character). Note: wake-up
via this mechanism is not implemented.
Don't hesitate to use CC tables; they only take up 16
bytes apiece.
The function code in the CFB_FC element of the command
function block specifies the operation to be performed on
behalf of that function block. Functions are described now.
CFB function _CMINI: Initialize
Every parse of a command line must begin with an
initialization call. This tells the command library to reset
its indexes, that the user must be prompted, etc. There may be
NO other CFBs chained to this one, because if they are, they
are ignored.
The reparse point is the point right after this call. If
the setjmp method is used, then the setjmp environment should
be defined here. After the reparse point, any variables etc
which may be the victims of parsing side-effects should be
initialized.
CFB function _CMKEY: Keyword parse
_CMKEY parses a keyword from a given list. The CFB_DAT
element of the function block should point to a table of string
pointers, ending with a NULL pointer. The user may type any
unique abbreviation of a keyword, and may use completion to
fill out the rest of a known match. The address of the pointer
to the matching string is returned in the CSB_RVL element of
the command state block. The value is returned this way so
that the index can be easily calculated, and because it is
consistent with the general keyword parsing mechanism
(_CMGSK).
The incremental help associated with keyword parsing is
somewhat special. The default help string is "Keyword, one
of:" followed by a list of keywords which match anything
already typed. If a help string has been supplied (indicated
by _CFHPP) and no suppression of the default help is specified,
then the initial part ("Keyword, ") is replaced with the
supplied help string and the help is otherwise the same. If a
help string has been supplied and the default has been
supressed, then the given help string is presented unaltered.
CFB function _CMNUM: number
This parses a number. The caller supplies a radix in the
CFB_DAT element of the function block. The number parsed is
returned (as an int) in the CSB_RVL element of the state
block.
CFB function _CMNOI: guide word string
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -