PARSEARGS
— Divide a string
into arguments.
Syntax:
PARSEARGS
/A:
array /F:
flags /Q /V:
var !
string
/A: array | name of an array to receive the arguments; the default is ARG |
/F: flags | parse flags; bitmapped, see below; the default is 1 |
/Q | quiet; don’t display arguments to stdout |
/V: var | name of an environment variable containing the string to parse |
! string | the string to parse |
This command exposes the plugin’s internal ParseArgs() function, which
divides a string into command-line arguments. Its operation can be changed in
various ways with the /F:
flags option.
The string to be parsed may be passed in two different ways. You can pass
the string on the command line, immediately following an exclamation point.
The string must be the last item on the command line; everything following the
exclamation point is considered the string to parse. Alternatively, you can
store the string in an environment variable, and pass the name of the variable
with the /V:
var option.
The resulting arguments will be stored in an array. You can specify the
name of the array with the /A:
array
option. The array name must begin with a letter. It may contain only letters,
digits, underscores, and dollar signs; it should not be more than 31 characters
long. If you don’t specify an array name, the default is ARG
.
The number of arguments found will be stored in an environment variable; the
name of this variable is the name of the array with an _N
appended, for example ARG_N
.
Parse flags: | |
1 | divide the string at unquoted spaces |
2 | divide the string at unquoted commas |
4 | slashes kludge: treat /A/B like /A /B |
8 | quotes kludge: treat /A"foo" like /A:"foo" |
16 | equals kludge: break at the first unquoted equals sign |
32 | one-arg kludge: allow unquoted spaces in arg not beginning with / |
64 | don’t swallow double quotes |
128 | force all arguments to uppercase |
256 | don’t trim spaces from the end of args |
512 | disable special handling of double quotes |
You should specify at least one of 1, 2, or 16; specifying more than one is allowed. If you don’t specify any, then 1 is assumed. Note that if you include a value of 2 (break at commas), then empty arguments are possible.
A value 4 causes causes a slash to terminate an argument beginning with a
slash followed by a letter. It treats an argument like /A/B
as
two separate arguments.
A value of 8 checks for arguments beginning with a slash followed by a
single letter and then a double quote. If this kind of construction is found,
the missing colon is supplied, changing /A"foo"
into /A:foo
.
If you only expect one argument which does not begin with a slash, and if that argument will always be the last one in the string, you can add 32 to flags. This allows the (only) argument to contain spaces without the necessity of double quotes.
A value of 16 is useful for commands that, like SET
or ASSOC
,
expect a name=
value
pair. This mode has a number of peculiar quirks. It splits arguments at the
first unquoted equals sign in an argument which does not begin with a slash.
Spaces around the equals sign are dropped. Spaces in the argument after
the equals sign, the value part, are retained even
if they are not quoted; the name=
value
pair is expected to be the last item on the command line. The equals sign is retained
as the first character in the value argument; this
allows you to distinguish a name=
construction
(to clear or reset the value for name, perhaps) from
a name alone (to report the value for
name without changing it.)
Normal behavior is to remove double quotes from the string. Typically the double quotes are not part of the filename, value, etc. per se, but a syntactic mechanism for escaping spaces; once the string has been parsed there is no further need for them. If you want to retain double quotes, add 64 to the value of flags.
• Note: This command is not available in TCC/LE, in 4NT, or in older versions of TCC which don’t support array variables.