$useroption, $userswitch, $longoption, $userhelp − User provided options, helptext or option values for rwloadsim
$useroption:identifier[:"help text"] $userswitch:identifier[:"help text"] $longoption:option[=value] $userhelp:"help text"
The first file (named with a .rwl suffix) provided to rwloadsim is scanned twice. The first scan that takes place very early and before any options provided to rwloadsim are handled, is only done to scan for extra options the programmer may need or to provide ordinary options or option values.
Note that this first scan does no other processing of either directives (such as $if $then or $include) or any rwl code. You can therefore not control if these directives are in use or not using conditional compilation.
The file is scanned once more with normal processing after handling options. Only the first file has this special early scan, so if you for example do:
rwloadsim fileone.rwl filetwo.rwl
only fileone.rwl will have this early scan. Also note, that the argument provided to rwloadsim that will be used as a file for early scan must have a .rwl suffix.
To ease scripting, you can have rwloadsim understand user defined long options (i.e. with an initial --) by using $useroption or $userswitch directives. Both directives take the form $useroption:identifier or $userswitch:identifier and the result is that the named identifier will be added as extra long options.
In the former case, the option will require an argument, in the latter case, the long options --identifier and --no-identifier will both exist and neither will take an argument. When the file later is scanned and parsed as part of ordinary processing, any declaration of a string, integer or double with the same name as provided via the $useroption directives, will have an initial value assigned if the user has provided the appropriate long option and value. For $userswitch directives, no value should be provided by the user, but a value of 0 or 1 will be used if the user provided respectively the --no- or -- version of the option.
In both cases, if the identifier in your rwl program includes underscore character(s), you can optionally replace them by a hyphen in the directive. This allows you to provide user options or switches using the typical option naming scheme with a hyphen character.
You can additionally add a help text for your option or switch by adding :"helptext" to either directive. The helptext cannot span lines, but the same simple escape processing as described below for $userhelp is available. If you don’t add a help text, a default one will be created. The help text is printed when rwloadsim is called with the -h or --help option and the file with the .rwl suffix. The user can ask for only printing help for such options using -H or --userhelp
The $longoption:option=value directive - when found in the first .rwl file - can be used to provide values for any ordinary option using its long option name followed by = and the wanted value. Ordinary options that don’t take a value can similarly be provided via $longoption:option
The $userhelp:"help text" directive will add supplementary help text to be printed using the various help options. The option is primary useful when generating a binary and it can be repeated as needed to output multiple lines of text.
There is simple escape processing done for the helptext and \" or \\ implies a single " or \ will be part of the text. The text cannot span multiple lines.
The user can ask for output of the help text associated with with user options, switches and user help by providing the --userhelp option, or in the case of a generated binary the --help option. Such help will be output in the same order it appears in the source file. This fact can be used to provide nicely appearing user help.
Consider a file named echo.rwl with this contents:
# This is an implementation of the "echo" command
# using rwloadsim with an optional --commaseparate
$longoption:file-count=1 # Tell there is just this input rwl file
$longoption:quiet # Do not show the banner
# Declare an integer and give it an initial value
integer commaseparate := 0;
# and associate that variable with a userswitch
$userswitch:commaseparate:"--commaseparate : Separate using comma"
while $# loop
if $# = 1 then
printline $1;
else
print $1 commaseparate ? "," : " ";
end if;
shift;
end loop;
you have implemented a simple version of the echo command using rwloadsim. A few calls and their output may be:
rwloadsim echo.rwl hello world hello world rwloadsim --commaseparate echo.rwl hello world again hello,world,again rwloadsim --userhelp echo.rwl RWP*Load Simulator user options from echo.rwl: --commaseparate : Separate using comma
The next example shows how a string variable can be set using a useroption. It also shows how an underscore in the variable name can be replaced by a hyphen in the useroption.
# Declare a string variable string my_text; # And associate it with a useroption $useroption:my-text:"--my-text: set a non default text" if my_text = "" then printline "No --my-text argument"; else printline "--my-text is set to " my_text; end if;
This last example shows an example of how $userswitch can be used for a kind of three valued logic:
# Declare an integer with no default
integer mybool;
# and associate it with an extra pair of long options:
$userswitch:mybool
if mybool is null then
printline "--(no-)mybool was not provided by the user";
else
if mybool then
printline "User provided --mybool";
else
printline "User provided --no-mybool";
end;
end;
The scan of the first file looking for these directives is simple compared to the ordinary scan. To avoid recognizing these directives inside a string or a SQL statement, these will also be scanned, but handling of any errors during the scan will not be done until the ordinary scan and parse of the first file.
Copyright © 2023 Oracle Corporation
Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
rwloadsim(1rwl), directive(1rwl)