reference/info/functions/getopt.xml
4d02fe98ddc684a0d82a3921ef189a71b98f4f04
4d02fe98ddc684a0d82a3921ef189a71b98f4f04
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.getopt">
3
+
<refentry xml:id="function.getopt" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>getopt</refname>
6
6
<refpurpose>Gets options from the command line argument list</refpurpose>
...
...
@@ -9,9 +9,10 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>array</type><methodname>getopt</methodname>
13
-
<methodparam><type>string</type><parameter>options</parameter></methodparam>
14
-
<methodparam choice="opt"><type>array</type><parameter>longopts</parameter></methodparam>
12
+
<type class="union"><type>array</type><type>false</type></type><methodname>getopt</methodname>
13
+
<methodparam><type>string</type><parameter>short_options</parameter></methodparam>
14
+
<methodparam choice="opt"><type>array</type><parameter>long_options</parameter><initializer>[]</initializer></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter role="reference">rest_index</parameter><initializer>&null;</initializer></methodparam>
15
16
</methodsynopsis>
16
17
<para>
17
18
Parses options passed to the script.
...
...
@@ -23,7 +24,7 @@
23
24
<para>
24
25
<variablelist>
25
26
<varlistentry>
26
-
<term><parameter>options</parameter></term>
27
+
<term><parameter>short_options</parameter></term>
27
28
<listitem>
28
29
<simpara>
29
30
Each character in this string will be used as option characters and
...
...
@@ -40,7 +41,7 @@
40
41
</listitem>
41
42
</varlistentry>
42
43
<varlistentry>
43
-
<term><parameter>longopts</parameter></term>
44
+
<term><parameter>long_options</parameter></term>
44
45
<listitem>
45
46
<simpara>
46
47
An array of options. Each element in this array will be used as option
...
...
@@ -53,10 +54,19 @@
53
54
</simpara>
54
55
</listitem>
55
56
</varlistentry>
57
+
<varlistentry>
58
+
<term><parameter>rest_index</parameter></term>
59
+
<listitem>
60
+
<simpara>
61
+
If the <parameter>rest_index</parameter> parameter is present, then the
62
+
index where argument parsing stopped will be written to this variable.
63
+
</simpara>
64
+
</listitem>
65
+
</varlistentry>
56
66
</variablelist>
57
67
</para>
58
68
<para>
59
-
The <parameter>options</parameter> parameter may contain the following
69
+
The <parameter>short_options</parameter> parameter may contain the following
60
70
elements:
61
71
<simplelist>
62
72
<member>Individual characters (do not accept values)</member>
...
...
@@ -71,12 +81,20 @@
71
81
</simpara>
72
82
</note>
73
83
</para>
84
+
<para>
85
+
The <parameter>long_options</parameter> array values may contain:
86
+
<simplelist>
87
+
<member>String (parameter does not accept any value)</member>
88
+
<member>String followed by a colon (parameter requires value)</member>
89
+
<member>String followed by two colons (optional value)</member>
90
+
</simplelist>
91
+
</para>
74
92
<note>
75
93
<para>
76
-
The format for the <parameter>options</parameter> and
77
-
<parameter>longopts</parameter> is almost the same, the only difference is
78
-
that <parameter>longopts</parameter> takes an array of options (where each
79
-
element is the option) whereas <parameter>options</parameter> takes a
94
+
The format for the <parameter>short_options</parameter> and
95
+
<parameter>long_options</parameter> is almost the same, the only difference is
96
+
that <parameter>long_options</parameter> takes an array of options (where each
97
+
element is the option) whereas <parameter>short_options</parameter> takes a
80
98
string (where each character is the option).
81
99
</para>
82
100
</note>
...
...
@@ -85,7 +103,7 @@
85
103
<refsect1 role="returnvalues">
86
104
&reftitle.returnvalues;
87
105
<para>
88
-
This function will return an array of option / argument pairs,&return.falseforfailure;.
106
+
This function will return an array of option / argument pairs, &return.falseforfailure;.
89
107
</para>
90
108
<note>
91
109
<para>
...
...
@@ -108,27 +126,9 @@
108
126
</thead>
109
127
<tbody>
110
128
<row>
111
-
<entry>5.3.0</entry>
112
-
<entry>
113
-
Added support for "=" as argument/value separator.
114
-
</entry>
115
-
</row>
116
-
<row>
117
-
<entry>5.3.0</entry>
118
-
<entry>
119
-
Added support for optional values (specified with "::").
120
-
</entry>
121
-
</row>
122
-
<row>
123
-
<entry>5.3.0</entry>
124
-
<entry>
125
-
Parameter <parameter>longopts</parameter> is available on all systems.
126
-
</entry>
127
-
</row>
128
-
<row>
129
-
<entry>5.3.0</entry>
129
+
<entry>7.1.0</entry>
130
130
<entry>
131
-
This function is no longer system dependent, and now works on Windows, too.
131
+
Added the <parameter>rest_index</parameter> parameter.
132
132
</entry>
133
133
</row>
134
134
</tbody>
...
...
@@ -255,6 +255,35 @@ array(2) {
255
255
</screen>
256
256
</example>
257
257
</para>
258
+
<para>
259
+
<example xml:id="getopt.examples-4">
260
+
<title><function>getopt</function> example: Using <parameter>rest_index</parameter></title>
261
+
<programlisting role="php">
262
+
<![CDATA[
263
+
<?php
264
+
// Script example.php
265
+
$rest_index = null;
266
+
$opts = getopt('a:b:', [], $rest_index);
267
+
$pos_args = array_slice($argv, $rest_index);
268
+
var_dump($pos_args);
269
+
]]>
270
+
</programlisting>
271
+
<programlisting role="shell">
272
+
<![CDATA[
273
+
shell> php example.php -a 1 -b 2 -- test
274
+
]]>
275
+
</programlisting>
276
+
&example.outputs;
277
+
<screen>
278
+
<![CDATA[
279
+
array(1) {
280
+
[0]=>
281
+
string(4) "test"
282
+
}
283
+
]]>
284
+
</screen>
285
+
</example>
286
+
</para>
258
287
</refsect1>
259
288
260
289
<refsect1 role="seealso">
...
...
@@ -267,7 +296,6 @@ array(2) {
267
296
</refsect1>
268
297
269
298
</refentry>
270
-
271
299
<!-- Keep this comment at the end of the file
272
300
Local variables:
273
301
mode: sgml
274
302