User guide

58 CHAPTER 3. THE LIBRARY
where the decoded integer is stored. If a /N was not specified, the setti n g will be a
BCPL string with its characters packed into argv. Note that an argument should not
have both /N and /S specified.
Command arguments are read from the currently selected input stream using a
decoding mechanism that permits both positional and keyed arguments to be freely
mixed. A ty pi c al use of rdargs occurs in the source of the input command as follows:
UNLESS rdargs("FROM/A,TO=AS/K,DATA/N/P,N/S", argv, 50) DO
{ writef("Bad arguments for: FROM/A,TO=AS/K,DATA/N/P,N/S*n")
...
}
In this example, there are four possible arguments and their values will be pl ac ed in
the first four elements of argv. The first argument has keyword FROM and must receive
a value because of the quali fie r /A. Th e sec ond has alternative keywords TO and AS with
qualifier /K that insists the argument is intr oduced by one of its keywords. The third
argument has the qualifiers /N and /P indicating that it expects a number and that it
will be prompted for if not already given, and the l as t argument has the qualifier /S
indicating that it is a switch that can be set by the presence of its keyword.
Table 3.4 shows the values in placed in argv and the result when the call:
rdargs("FROM/A,TO=AS/K,DATA/N/P,N/S", argv, 50)
is given various argument strings. This example ill us tr at es that keyword synonyms can
be defined using = within the key string. Positional arguments are those not introduced
by keywords. When one is encountered, it becomes the value of the lowest numbered
unset non-switch argument.
Arguments argv!0 argv!1 argv!2 argv!4 Result
abc TO xyz "abc" "xyz" 0 0 ~=0
to xyz from abc "abc" "xyz" 0 0 ~=0
as xyz abc n "abc" "xyz" 0 -1 ~=0
abc xyz - - - - =0
"from" to "to" "from" "to" 0 0 ~=0
abc data 123 to "to" "abc" "to" ->123 0 ~=0
data 123 to junk - - - - =0
Figure 3.4: rdargs("FROM/A,TO=AS/K,DATA/N/P,N/S", argv, 50)
To consolidate your understanding of rdargs, try compiling and running the pro-
gram: bcplprogs/tests/tstrdargs.b.
res := rdargs2(keys1, keys2, argv, upb) CIN:y, POS:y, NAT:y
This function behaves just like rdargs, specified above, except it uses key data that
is the concatenation of strings keys1 and keys2 thus allowing the key data to have up
to than 510 characters.