GP: Routines for parsing command lines
The routines described here are a convenient package for parsing
command lines and doing a few related functions. They may be found in
GP.Bcpl (source) and GP.Br (binary). No external routines are called
except those supplied by the operating system.
An "unpacked string" is a vector v such that v!1, v!2, ..., v!(v!0)
contain the characters of the string, one per word, right justified.
A "parameter" in a command line is a maximal sequence of characters not
containing $*S or $*N. All the characters before the first $/ are the
"body"; the remaining characters, with any $/ characters ignored, are
the "switches". Thus
BCPL/F FOO.Bcpl
contains two parameters. The first has body "BCPL" and switches "F".
The second has body "FOO.Bcpl" and no switches.
SetupReadParam (stringVec, switchVec, stream, comSwitchVec)
. stringVec is a vector whose length in words should be greater
than the number of characters in the longest body in the
command line. A 0 defaults it to a 256-word vector
inacessible to the user; this may be useful if all the
parameters of the command are files or numbers (see the
discussion of ReadParam below).
. switchVec is a vector whose length in words should be greater
than the largest number of switches on any unit in the
command line. A 0 defaults it to a 128-word vector
inaccessible to the user.
. stream is an OS character stream from which the command line
will be read. It will not be Reset or Closed. A 0 defaults it
to the disk file "Com.Cm". The stream is left in the
external static ReadParamStream.
. comSwitchVec is a vector whose length in words should be
greater than the number of switches on the first unit in the
command line. A 0 defaults it to switchVec.
Missing parameters are defaulted.
------------
Copyright Xerox Corporation 1979
GP: parse command lines January 2, 1978 2
This routine initializes the parameter-reading machinery. It then does
a ReadParam() which will pick off the first parameter (i.e., the name
of the program) and leave the name and switches as unpacked strings in
stringVec and comSwitchVec. If either of these was defaulted to an
inaccessible vector, the corresponding information is lost.
ReadParam (type, prompt, resultVec, switchVec, returnOnNull)
. type is an integer or Bcpl string representing the expected
type of the parameter. If type < 256, it is interpreted as a
character which must select a defined type from the list
described below. If type > 256 it is treated as a Bcpl
string. If the string is one character long, it is
interpreted as though that character had been used. If it is
longer, the first two characters must select a defined type
from the list below.
. prompt is a Bcpl string which is used to prompt the user for
another try at the parameter if a syntax error is discovered.
A 0 defaults it to "Try again: ".
. resultVec is a vector used to return the result for types
which need more than one word to represent their result. A 0
defaults it to the stringVec passed to SetupReadParam (in
which case there must have been one or else ReadParam will
call Swat).
. switchVec is a vector used to return the switches as an
unpacked string. A 0 defaults it to the switchVec passed to
SetupReadParam.
. returnOnNull is a boolean which decides what to do if the
parameter body is null. It defaults to false.
Missing parameters are defaulted. If type is missing, it is defaulted
to 0.
One parameter is read from the stream passed to SetupReadParam. The
switches are separated off and left in switchVec. Any $/ characters
among the switches are stripped off. If there are no switches,
switchVec!0 will be 0.
Then the body is handled in a way which depends on the type:
0: (the integer 0, not the character $0 or the string "0"!) It
is returned in resultVec as an unpacked string. Result is
resultVec.
P: It is returned in resultVec as a packed (Bcpl) string. Result
is resultVec.
GP: parse command lines January 2, 1978 3
I or IC: It is treated as the name of an input character file, to
be opened with OpenFile(body, ksTypeReadOnly, charItem). If
the open fails, prompt for another name. Result is the stream
returned by OpenFile. In addition, the file name is returned
in resultvec as a Bcpl string.
IW: Like I, but a word stream is created.
O or OC: Like I, but OpenFile(body, ksTypeWriteOnly, charItem) is
called.
OW: Like O, but a word stream is created.
F or EF: Like I, but OpenFile(body, ksTypeReadWrite, wordItem) is
called.
B: An octal number is collected and returned. Numbers may start
with #, which forces them octal, and may end with B, b, O, or
o (which forces them octal) or with D or d, which forces them
decimal. Anything else is a syntax error and causes a prompt
for another number. Result is the number.
D: Like B, but for decimal number.
Any undefined type results in a call on Swat.
If the body is empty, ReadParam immediately prompts, without generating
an error message from the null body, unless returnOnNull is true or
prompt eq -1, in which case it returns -1 when it sees a null body.
When prompting for new input, DEL cancels whatever has been typed and
allows another try, and BS and control-A backspace one character.
EvalParam (body, type, prompt, resultVec)
. body is an unpacked string
. the other arguments are like the corresponding ones for
ReadParam. resultVec defaults to body.
body and type may not be omitted.
Works exactly like ReadParam, using body as the parameter body. Does
nothing about switches. This routine is useful for programs whose
interpretation of parameters depends on the switches attached to them.
ReadString (result, breaks, inStream, editFlag, prompt)
. result is a vector in which the string read will be returned,
unpacked. May not be defaulted.
. breaks is a Bcpl string containing the characters which will
cause reading to terminate. Defaults to "*N".
GP: parse command lines January 2, 1978 4
. inStream is the stream to read from. Defaults to keys.
. editFlag says whether DEL, BS and control-A should be
interpreted as editing characters. If it is false, they are
not. Otherwise they are, and furthermore, editFlag is taken
as the stream on which echoing of the input should be done.
It defaults to false unless inStream is keys, in which case
it defaults to dsp.
. prompt is echoed after a DEL. It defaults to "".
Reads characters from inStream until one of the characters in breaks is
encountered, leaving the characters read in result as an unpacked
string. Returns the break character. Allows editing of the input as
described under editFlag above.
AddItem (vek, value)
. vek is a vector whose current size is given by vek!0.
. value is an uninterpreted 16-bit quantity.
Increments vek!0 and stores value at the new vek!(vek!0).