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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html>
<head>
<title>Castle Game Engine: CastleParameters: Class TParameters</title>
<meta name="generator" content="PasDoc 0.13.0">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<link rel="StyleSheet" type="text/css" href="pasdoc.css">
</head>
<body>
<table class="container"><tr><td class="navigation">
<h2>Castle Game Engine</h2><p><a href="introduction.html" class="navigation">Introduction</a></p><p><a href="AllUnits.html" class="navigation">Units</a></p><p><a href="ClassHierarchy.html" class="navigation">Class Hierarchy</a></p><p><a href="AllClasses.html" class="navigation">Classes, Interfaces, Objects and Records</a></p><p><a href="AllTypes.html" class="navigation">Types</a></p><p><a href="AllVariables.html" class="navigation">Variables</a></p><p><a href="AllConstants.html" class="navigation">Constants</a></p><p><a href="AllFunctions.html" class="navigation">Functions and Procedures</a></p><p><a href="AllIdentifiers.html" class="navigation">Identifiers</a></p></td><td class="content">
<a name="TParameters"></a><h1 class="cio">Class TParameters</h1>
<table class="sections wide_list">
<tr>
<td><a class="section" href="#PasDoc-Description">Description</a></td><td><a class="section" href="#PasDoc-Hierarchy">Hierarchy</a></td><td>Fields</td><td><a class="section" href="#PasDoc-Methods">Methods</a></td><td>Properties</td></tr></table>
<a name="PasDoc-Description"></a><h2 class="unit">Unit</h2>
<p class="unitlink">
<a href="CastleParameters.html">CastleParameters</a></p>
<h2 class="declaration">Declaration</h2>
<p class="declaration">
<code>type TParameters = class(<a class="normal" href="CastleStringUtils.TCastleStringList.html">TCastleStringList</a>)</code></p>
<h2 class="description">Description</h2>
<p>
Storing and processing command-line parameters and options. For simple processing, you can just read values of this list, checking count with comfortable methods like <a class="normal" href="CastleParameters.TParameters.html#CheckHigh">CheckHigh</a>. For more involved processing, use the Parse function, that does a whole job for you based on a simple specification of allowed options.
<p>Some terminology:
<p></p>
<dl class="paragraph_spacing">
<dt><i>Parameter</i></dt>
<dd><p>Command-line parameters list is given directly by the OS to our program. These are the contents of this list, initialized from the standard Pascal ParamStr/ParamCount. They can be modified to remove the already-handled parameters.</p></dd>
<dt><i>Option</i></dt>
<dd><p>Options are things encoded by the user in the parameters. Examples:
<p></p>
<ul class="paragraph_spacing">
<li><p>Command-line
<p></p>
<pre class="preformatted"> view3dscene --navigation Walk</pre>
<p>
<p>passes two parameters (<code>--navigation</code> and <code>Walk</code>) for view3dscene, and these two parameters form one option: <code>--navigation=Walk</code>.</p></li>
<li><p>Command-line
<p></p>
<pre class="preformatted"> view3dscene -hv</pre>
<p>
<p>passes one parameter (<code>-hv</code>) for view3dscene, and inside this parameter two options are encoded: <code>-h</code> and <code>-v</code>.</p></li>
</ul>
<p>
<p>The very idea of this unit is to decode "options" from the "parameters". </p></dd>
<dt><i>Argument</i></dt>
<dd><p>Argument is a part of the option, that clarifies what this option does. For example in <code>--navigation=Walk</code>, "<code>Walk</code>" is the argument and "<code>--navigation</code>" is the option long name.
<p>Some options don't take any arguments, some take optional argument, some take required argument, some have a couple of arguments. <a class="normal" href="CastleParameters.html#TOptionArgument">TOptionArgument</a> type allows you to specify all this.</p></dd>
</dl>
<p>
<p>For simple programs, you can directly parse command-line by looking at our parameters strings. For more involved cases, using <a class="normal" href="CastleParameters.TParameters.html#Parse">Parse</a> method has a lot of advantages:
<p></p>
<ul class="paragraph_spacing">
<li><p>Less error-prone, and your program's code stays simple.</p></li>
<li><p>We automatically handle special parameter -- that is a standard way to mark the end of the options. (Useful for users that have filenames that start with "-" character.)</p></li>
<li><p>We automatically detect and make exceptions with nice messages on various errors. For example unrecognized options are clearly reported (so they will not mistaken for e.g. missing filenames by your program).</p></li>
<li><p>We automatically allow combining of short options, so user can use <code>-abc</code> instead of <code>-a -b -c</code>.</p></li>
<li><p>We have a simple interface, where you simply specify what options you want, long and short option names, option arguments and such.</p></li>
</ul>
<p>
<p>See [<a href="http://castle-engine.sourceforge.net/common_options.php">http://castle-engine.sourceforge.net/common_options.php</a>] for a user description how short and long options are expected to be given on the command-line.</p>
<a name="PasDoc-Hierarchy"></a><h2 class="hierarchy">Hierarchy</h2>
<ul class="hierarchy"><li class="ancestor">TStringList</li>
<li class="ancestor"><a class="normal" href="CastleStringUtils.TCastleStringList.html">TCastleStringList</a></li>
<li class="thisitem">TParameters</li></ul><h2 class="overview">Overview</h2>
<a name="PasDoc-Methods"></a><h3 class="summary">Methods</h3>
<table class="summary wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>function <b><a href="CastleParameters.TParameters.html#High">High</a></b>: Integer;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleParameters.TParameters.html#CheckHigh">CheckHigh</a></b>(ParamValue: integer);</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleParameters.TParameters.html#CheckHighAtLeast">CheckHighAtLeast</a></b>(ParamValue: integer);</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleParameters.TParameters.html#CheckHighAtMost">CheckHighAtMost</a></b>(ParamValue: integer);</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>function <b><a href="CastleParameters.TParameters.html#IsPresent">IsPresent</a></b>(const A: array of string): boolean;</code></td>
</tr>
<tr class="list2">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleParameters.TParameters.html#Parse">Parse</a></b>(Options: <a href="CastleParameters.html#POption_Array">POption_Array</a>; OptionsCount: Integer; OptionProc: <a href="CastleParameters.html#TOptionProc">TOptionProc</a>; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;</code></td>
</tr>
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><code>procedure <b><a href="CastleParameters.TParameters.html#Parse">Parse</a></b>(const Options: array of <a href="CastleParameters.TOption.html">TOption</a>; OptionProc: <a href="CastleParameters.html#TOptionProc">TOptionProc</a>; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;</code></td>
</tr>
</table>
<h2 class="description">Description</h2>
<h3 class="detail">Methods</h3>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="High"></a><code>function <b>High</b>: Integer;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="CheckHigh"></a><code>procedure <b>CheckHigh</b>(ParamValue: integer);</code></td>
</tr>
<tr><td colspan="2">
<p>
Does the number of parameters (High) satisfy given condition. </p>
<h6 class="description_section">Exceptions raised</h6>
<dl class="exceptions_raised">
<dt><a class="normal" href="CastleParameters.EInvalidParams.html">EInvalidParams</a></dt>
<dd>When High is wrong.</dd>
</dl>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="CheckHighAtLeast"></a><code>procedure <b>CheckHighAtLeast</b>(ParamValue: integer);</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="CheckHighAtMost"></a><code>procedure <b>CheckHighAtMost</b>(ParamValue: integer);</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="IsPresent"></a><code>function <b>IsPresent</b>(const A: array of string): boolean;</code></td>
</tr>
<tr><td colspan="2">
<p>
Is one of given strings present on the parameters list. Looks inside Strings[1..High], case sensitive.</p>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Parse"></a><code>procedure <b>Parse</b>(Options: <a href="CastleParameters.html#POption_Array">POption_Array</a>; OptionsCount: Integer; OptionProc: <a href="CastleParameters.html#TOptionProc">TOptionProc</a>; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;</code></td>
</tr>
<tr><td colspan="2">
<p>
Parse command-line parameters. Given a specification of your command-line options (in Options), we will find and pass these options to your OptionProc callback. The handled options will be removed from the <a class="normal" href="CastleParameters.html#Parameters">Parameters</a> list.
<p>After running this, you should treat the remaining <a class="normal" href="CastleParameters.html#Parameters">Parameters</a> as "normal" parameters, usually a filenames to open by your program or such.
<p>See also <a class="normal" href="CastleParameters.TOption.html">TOption</a> for a specification of an option, and see <a class="normal" href="CastleParameters.html#TOptionArgument">TOptionArgument</a> for a specification of an option argument, and see <a class="normal" href="CastleParameters.html#TOptionProc">TOptionProc</a> for a specification what your OptionProc callback gets.
<p>
<p>Note that a single dash parameter is left alone, without making any exceptions, as this is a standard way of telling "standard input" or "standard output" for some programs.
<p>Note that a double dash parameter -- is handled and removed from the <a class="normal" href="CastleParameters.html#Parameters">Parameters</a> list, and signals an end of options.
<p>You should not modify <a class="normal" href="CastleParameters.html#Parameters">Parameters</a> list when this function is running, in particular do not modify it from your OptionProc callback. Also, do not depend on when the handled options are exactly removed from the <a class="normal" href="CastleParameters.html#Parameters">Parameters</a> list (before or after OptionProc callback).
<p>We never touch here the Strings[0] value, we look only at the Strings[1] to Strings[High].
<p>ParseOnlyKnownLongOptions = <code>True</code> makes this procedure work a little differently, it's designed to allow you to process <i>some</i> long options and leave the rest options not handled (without making any error):
<p></p>
<ol class="paragraph_spacing">
<li value="1"><p>All short options are ignored then.</p></li>
<li value="2"><p>All unknown long options are also ignored, without making any error.</p></li>
<li value="3"><p>The special -- is handled (signals the end of options), but it's not removed from the <a class="normal" href="CastleParameters.html#Parameters">Parameters</a>.</p></li>
</ol>
<p>
<p>The ParseOnlyKnownLongOptions = <code>True</code> is useful if you want to handle some command-line options, but you still want to leave final options parsing to a later code. For example <a class="normal" href="CastleWindow.TCastleWindowCustom.html#ParseParameters">TCastleWindowCustom.ParseParameters</a> parses some window parameters (like –geometry), leaving your program-specific stuff in peace.
<p>Note that ParseOnlyKnownLongOptions = <code>True</code> isn't an absolutely fool-proof solution, for example the command-line <code>view3dscene –navigation –geometry 800x600 Walk</code> is actually invalid. But we will handle it, by first detecting and removing <code>–geometry 800x600</code> from <a class="normal" href="CastleWindow.TCastleWindowCustom.html#ParseParameters">TCastleWindowCustom.ParseParameters</a>, and then detecting and removing <code>–navigation Walk</code> from view3dscene code. Basically, processing by Parse many times is not fool-proof in some weird situations.
<p></p>
<h6 class="description_section">Exceptions raised</h6>
<dl class="exceptions_raised">
<dt><a class="normal" href="CastleParameters.EInvalidShortOption.html">EInvalidShortOption</a></dt>
<dd>On invalid (unknown) short option name.</dd>
<dt><a class="normal" href="CastleParameters.EInvalidLongOption.html">EInvalidLongOption</a></dt>
<dd>On invalid long option name.</dd>
<dt><a class="normal" href="CastleParameters.EExcessiveOptionArgument.html">EExcessiveOptionArgument</a></dt>
<dd>When an option gets too many arguments, this may happen for options with oaNone or oaRequiredXSeparate that are specified with <code>–option=argument</code> form.</dd>
<dt><a class="normal" href="CastleParameters.EMissingOptionArgument.html">EMissingOptionArgument</a></dt>
<dd>When an option gets too few arguments, this may happen when argument for oaRequired option is missing, or when too few arguments are given for oaRequiredXSeparate option.</dd>
<dt><a class="normal" href="CastleParameters.EInvalidParams.html">EInvalidParams</a></dt>
<dd>On invalid parameter without an option, like <code>-=argument</code> or <code>–=argument</code>.</dd>
</dl>
</td></tr>
</table>
<table class="detail wide_list">
<tr class="list">
<td class="visibility"><a href="legend.html"><img src="public.gif" alt="Public" title="Public"></a></td>
<td class="itemcode"><a name="Parse"></a><code>procedure <b>Parse</b>(const Options: array of <a href="CastleParameters.TOption.html">TOption</a>; OptionProc: <a href="CastleParameters.html#TOptionProc">TOptionProc</a>; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;</code></td>
</tr>
<tr><td colspan="2">
</td></tr>
</table>
<!-- Piwik -->
<script type="text/javascript">
var _paq = _paq || [];
_paq.push(["trackPageView"]);
_paq.push(["enableLinkTracking"]);
(function() {
var u=(("https:" == document.location.protocol) ? "https" : "http") + "://michalis.ii.uni.wroc.pl/piwik-castle-engine/";
_paq.push(["setTrackerUrl", u+"piwik.php"]);
_paq.push(["setSiteId", "1"]);
var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0]; g.type="text/javascript";
g.defer=true; g.async=true; g.src=u+"piwik.js"; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Piwik Code -->
<noscript>
<!-- Piwik Image Tracker -->
<img src="http://michalis.ii.uni.wroc.pl/piwik-castle-engine/piwik.php?idsite=1&rec=1" style="border:0" alt="" />
<!-- End Piwik -->
</noscript>
<hr noshade size="1"><span class="appinfo"><em>Generated by <a href="http://pasdoc.sourceforge.net/">PasDoc 0.13.0</a> on 2015-06-15 04:43:10</em>
</span>
</td></tr></table></body></html>
|
