Repository navigation
Option Parameters
Parameters to .utl.addArg, .utl.addOpt, and .utl.addOptDef
The flags for an option are always a list of characters. It can be any character combination that isn’t separated by whitespace. Multiple names for an option can be provided by using comma separation. For example, "size" and "size,count" are both valid. The former will only respond to the option --size while the latter will respond to both --size and --count.
.utl.addOpt and .utl.addOptDef support this parameter.
Type arguments can be of three types: a boolean value, a single character, or a list of characters.
In the case that the argument is a boolean, the option will be treated as a binary flag. If the boolean is 1b, then it is a positive flag. If the boolean is 0b, then it is a negative flag. The practical effects of this become apparent with the third parameter. Only .utl.addOpt supports boolean flag types.
If the argument is a single character, then the option value is cast with that character as if the $ operator were being used. So, for example, to interpret an option as an integer, you would use "I", to interpret it as a date, you would use "D", and to just interpret it as a character list, you would use "*".
If the argument is a list of characters, then only the first character is used in the cast, but the option is interpreted as a list of values. So, for example, we could interpret a list of integers for an option in the following fashion:
q script.q --foo="1 2 3"
q).utl.addOpt["foo";(),"I";`intList]
.utl.addArg, .utl.addOpt and .utl.addOptDef support this parameter.
The default value, where supported, is the value used for an option if the option is not supplied on the command line. For all applicable calls, this value is simply used if the option is not present.
.utl.addArg and .utl.addOptDef support this parameter.
The number for a required argument allows you to specify whether 1, a specific number, or all remaining positional parameters are consumed. You can additionally specify a positional option. This chart explains the different ways the number can be specified:
| Number | Effect | |||
0
|
A positional option. A default will be used if not provided | |||
1
|
A single required argument | |||
2
|
A required argument that will consume two positional parameters | |||
N
|
A required argument that will consume N positional parameters | |||
(),0
|
A greedy positional option that will consume all remaining positional parameters. A default will be used if not provided | |||
(),N
|
A greedy argument that will consume at least N and all remaining positional parameters |
.utl.addArg supports this parameter.
The handler is one of three things: A symbol, a function, or a pair of a symbol and a function.
If it is a symbol, then the action is a simple assignment. If the type was a character or character list, the resulting value from applying the cast is stored in the variable:
q script.q --foo="1 2 3"
q).utl.addOpt["foo";(),"I";`intList]
q)intList
1 2 3
If the option is not present, nothing is stored.
If the type was a boolean, then the boolean value provided is stored in the variable
q script.q --foo --bar
q).utl.addOpt["foo";1b;`foo]
q).utl.addOpt["bar";0b;`bar]
q)foo
1b
q)bar
0b
And if the flags are not present, then the opposite value is stored:
q script.q
q).utl.addOpt["foo";1b;`foo]
q).utl.addOpt["bar";0b;`bar]
q)foo
0b
q)bar
1b
If the handler is a function and the type was a list or character list, then the function is called with the result of the cast. Again, if the option was not present, the function is not invoked.
If the handler is a function and the type was a boolean, then the function is only called when the flag is present, regardless of the value of the boolean in the type. If it is called, it will be given the value of type.
q script.q --bar
q).utl.addOpt["bar";0b;{show "Called with: ",string x}]
Called with: 0
q).utl.addOpt["foo";1b;{show "Called with: ", string x}]
If the handler is a pair, the function will be called with the result of the cast, and then the return value of that function will be assigned to the variable. If the type was a character or character list, this will only happen when the parameter is present.
q script.q --bar 20
q).utl.addOpt["bar";"I";(`bar;{x*20})]
q).utl.addOpt["foo";"I";(`foo;{x*10})]
q)bar
400
q)foo
'foo
If the handler is a pair and the type was a boolean, the function will always be called, regardless of whether or not the flag was present. The function will be given the XOR value of whether or not the flag was present and the type.
q script.q --bar
q).utl.addOpt["bar";0b;(`bar;{show "Called with: ",string x;x})]
Called with: 0
q).utl.addOpt["foo";1b;(`foo;{show "Called with: ", string x;x})]
Called with: 0
q)bar
0b
q)foo
0b
.utl.addArg, .utl.addOpt and .utl.addOptDef support this parameter.