PARSEARGS — Divide a string into arguments.

Syntax:
PARSEARGS /A:array /F:flags /Q /V:var !string

/A:arrayname of an array to receive the arguments; the default is ARG
/F:flagsparse flags; bitmapped, see below; the default is 1
/Qquiet; don’t display arguments to stdout
/V:varname of an environment variable containing the string to parse
!stringthe 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:
1divide the string at unquoted spaces
2divide the string at unquoted commas
4slashes kludge: treat /A/B like /A /B
8quotes kludge: treat /A"foo" like /A:"foo"
16equals kludge: break at the first unquoted equals sign
32one-arg kludge: allow unquoted spaces in arg not beginning with /
64don’t swallow double quotes
128force all arguments to uppercase
256don’t trim spaces from the end of args
512disable 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.