mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Really document this function
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@246578 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson
parent
18c0c7cdb3
commit
2a820bab98
1 changed files with 156 additions and 21 deletions
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.16 $ -->
|
||||
<!-- $Revision: 1.17 $ -->
|
||||
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.getopt">
|
||||
<refnamediv>
|
||||
<refname>getopt</refname>
|
||||
|
|
@ -14,9 +14,7 @@
|
|||
<methodparam choice="opt"><type>array</type><parameter>longopts</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Returns an associative array of option / argument pairs based on the
|
||||
options format specified in <parameter>options</parameter>, or &false;
|
||||
on an error.
|
||||
Parses options passed to the script.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
@ -27,33 +25,70 @@
|
|||
<varlistentry>
|
||||
<term><parameter>options</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The <parameter>options</parameter> parameter may contain the following
|
||||
elements: individual characters, and characters followed by a colon to
|
||||
indicate an option argument is to follow. For example, an option string
|
||||
<literal>x</literal> recognizes an option <literal>-x</literal>, and an
|
||||
option string <literal>x:</literal> recognizes an option and argument
|
||||
<literal>-x argument</literal>. It does not matter if an argument has
|
||||
leading white space.
|
||||
</para>
|
||||
<simpara>
|
||||
Each character in this string will be used as option characters and
|
||||
matched against options passed to the script starting with a single
|
||||
hyphen (<literal>-</literal>).
|
||||
</simpara>
|
||||
<simpara>
|
||||
For example, an option string <literal>"x"</literal> recognizes an
|
||||
option <literal>-x</literal>.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>longopts</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
</para>
|
||||
<simpara>
|
||||
An array of options. Each element in this array will be used as option
|
||||
strings and matched against options passed to the script starting with
|
||||
two hyphens (<literal>--</literal>).
|
||||
</simpara>
|
||||
<simpara>
|
||||
For example, an longopts element <literal>"opt"</literal> recognizes an
|
||||
option <literal>--opt</literal>.
|
||||
</simpara>
|
||||
<note>
|
||||
<simpara>
|
||||
Prior to PHP5.3.0 this parameter was only available on few systems
|
||||
</simpara>
|
||||
</note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
The <parameter>options</parameter> parameter may contain the following
|
||||
elements:
|
||||
<simplelist>
|
||||
<member>Individual characters (do not accept values)</member>
|
||||
<member>Characters followed by a colon (parameter requires value)</member>
|
||||
<member>Characters followed by two colons (optional value)</member>
|
||||
</simplelist>
|
||||
Option values are the first argument after the string. It does not matter
|
||||
if a value has leading white space or not.
|
||||
<note>
|
||||
<simpara>
|
||||
Optional values do not accept <literal>" "</literal> (space) as a seperator.
|
||||
</simpara>
|
||||
</note>
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
The format for the <parameter>options</parameter> and
|
||||
<parameter>longopts</parameter> is almost the same, the only difference is
|
||||
that <parameter>longopts</parameter> takes an array of options (where each
|
||||
element is the option) where as <parameter>options</parameter> takes a
|
||||
string (where each character is the option).
|
||||
</para>
|
||||
</note>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
This function will return an array of option / argument pairs. If an
|
||||
option does not have an argument, the value will be set to &false;.
|
||||
This function will return an array of option / argument pairs or &false; on
|
||||
failure.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
|
@ -84,25 +119,125 @@
|
|||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
<example>
|
||||
<example xml:id="getopt.examples-1">
|
||||
<title><function>getopt</function> Example</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
// parse the command line ($GLOBALS['argv'])
|
||||
$options = getopt("f:hp:");
|
||||
var_dump($options);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
<para>
|
||||
Running the above script with <literal>php script.php -fvalue -h</literal>
|
||||
will output:
|
||||
</para>
|
||||
<screen>
|
||||
<![CDATA[
|
||||
array(2) {
|
||||
["f"]=>
|
||||
string(5) "value"
|
||||
["h"]=>
|
||||
bool(false)
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example xml:id="getopt.examples-2">
|
||||
<title><function>getopt</function> Example#2</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$shortopts = "";
|
||||
$shortopts .= "f:"; // Required value
|
||||
$shortopts .= "v::"; // Optional value
|
||||
$shortopts .= "abc"; // These options do not accept values
|
||||
|
||||
$longopts = array(
|
||||
"required:", // Required value
|
||||
"optional::", // Optional value
|
||||
"option", // No value
|
||||
"opt", // No value
|
||||
);
|
||||
$options = getopt($shortopts, $longopts);
|
||||
var_dump($options);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
<para>
|
||||
Running the above script with <literal>php script.php -f "value for f" -v
|
||||
-a --required value --optional="optional value" --option</literal>
|
||||
will output:
|
||||
</para>
|
||||
<screen>
|
||||
<![CDATA[
|
||||
array(6) {
|
||||
["f"]=>
|
||||
string(11) "value for f"
|
||||
["v"]=>
|
||||
bool(false)
|
||||
["a"]=>
|
||||
bool(false)
|
||||
["required"]=>
|
||||
string(5) "value"
|
||||
["optional"]=>
|
||||
string(14) "optional value"
|
||||
["option"]=>
|
||||
bool(false)
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example xml:id="getopt.examples-3">
|
||||
<title><function>getopt</function> Example#3</title>
|
||||
<para>Passing multiple options as one</para>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
$options = getopt("abc");
|
||||
var_dump($options);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
<para>
|
||||
Running the above script with <literal>php script.php -aaac</literal>
|
||||
will output:
|
||||
</para>
|
||||
<screen>
|
||||
<![CDATA[
|
||||
array(2) {
|
||||
["a"]=>
|
||||
array(3) {
|
||||
[0]=>
|
||||
bool(false)
|
||||
[1]=>
|
||||
bool(false)
|
||||
[2]=>
|
||||
bool(false)
|
||||
}
|
||||
["c"]=>
|
||||
bool(false)
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<!--
|
||||
<refsect1 role="notes">
|
||||
&reftitle.notes;
|
||||
<note>
|
||||
<para>
|
||||
The <link linkend="ini.register-argc-argv">register_argc_argv</link>
|
||||
option must be enabled for this function to work
|
||||
</para>
|
||||
</note>
|
||||
</refsect1>
|
||||
-->
|
||||
|
||||
</refentry>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue