-
Notifications
You must be signed in to change notification settings - Fork 18
/
useroption.html
295 lines (228 loc) · 9.29 KB
/
useroption.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
<!-- Creator : groff version 1.22.3 -->
<!-- CreationDate: Mon Mar 18 08:51:07 2024 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>useroption</title>
</head>
<body>
<h1 align="center">useroption</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#USER OPTIONS">USER OPTIONS</a><br>
<a href="#OPTION VALUES">OPTION VALUES</a><br>
<a href="#USER HELPTEXT">USER HELPTEXT</a><br>
<a href="#HELP OUTPUT">HELP OUTPUT</a><br>
<a href="#EXAMPLES">EXAMPLES</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#COPYRIGHT">COPYRIGHT</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">$useroption,
$userswitch, $longoption, $userhelp − User provided
options, helptext or option values for rwloadsim</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<pre style="margin-left:11%; margin-top: 1em">$useroption:identifier[:"help text"]
$userswitch:identifier[:"help text"]
$longoption:option[=value]
$userhelp:"help text"</pre>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">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
<i>only</i> done to scan for extra options the programmer
may need or to provide ordinary options or option
values.</p>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<p style="margin-left:11%; margin-top: 1em">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:</p>
<p style="margin-left:11%; margin-top: 1em">rwloadsim
fileone.rwl filetwo.rwl</p>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<h2>USER OPTIONS
<a name="USER OPTIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">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
<b>$useroption:identifier</b> or
<b>$userswitch:identifier</b> and the result is that the
named identifier will be added as extra long options.</p>
<p style="margin-left:11%; margin-top: 1em">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 <b>--no-</b> or <b>--</b> version of the
option.</p>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<p style="margin-left:11%; margin-top: 1em">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 <b>$userhelp</b> 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 <b>-h</b> or <b>--help</b> option and the
file with the .rwl suffix. The user can ask for only
printing help for such options using <b>-H</b> or
<b>--userhelp</b></p>
<h2>OPTION VALUES
<a name="OPTION VALUES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>$longoption:option=value</b> 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
<b>=</b> and the wanted value. Ordinary options that
don’t take a value can similarly be provided via
<b>$longoption:option</b></p>
<h2>USER HELPTEXT
<a name="USER HELPTEXT"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>$userhelp:"help text"</b> 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.</p>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<h2>HELP OUTPUT
<a name="HELP OUTPUT"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<h2>EXAMPLES
<a name="EXAMPLES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Consider a file
named echo.rwl with this contents:</p>
<pre style="margin-left:17%; margin-top: 1em"># 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;</pre>
<p style="margin-left:11%; margin-top: 1em">you have
implemented a simple version of the echo command using
rwloadsim. A few calls and their output may be:</p>
<pre style="margin-left:11%; margin-top: 1em">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</pre>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<pre style="margin-left:17%; margin-top: 1em"># 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;</pre>
<p style="margin-left:11%; margin-top: 1em">This last
example shows an example of how $userswitch can be used for
a kind of three valued logic:</p>
<pre style="margin-left:17%; margin-top: 1em"># 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;</pre>
<h2>BUGS
<a name="BUGS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">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.</p>
<h2>COPYRIGHT
<a name="COPYRIGHT"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Copyright
© 2023 Oracle Corporation</p>
<p style="margin-left:11%; margin-top: 1em">Licensed under
the Universal Permissive License v 1.0 as shown at
https://oss.oracle.com/licenses/upl</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><a href="rwloadsim.html">rwloadsim(1rwl)</a>,
<a href="directive.html">directive(1rwl)</a></p>
<hr>
</body>
</html>