cvs: phpdoc /en/reference/info/functions getopt.xml

bjori Wed Nov 21 10:19:51 2007 UTC Modified files: /phpdoc/en/reference/info/functions getopt.xml Log: Really document this function http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/info/functions/getopt.xml?r1=1.16&r2=1.17&diff_format=u Index: phpdoc/en/reference/info/functions/getopt.xml diff -u phpdoc/en/reference/info/functions/getopt.xml:1.16 phpdoc/en/reference/info/functions/getopt.xml:1.17 --- phpdoc/en/reference/info/functions/getopt.xml:1.16 Sat Oct 13 15:39:27 2007 +++ phpdoc/en/reference/info/functions/getopt.xml Wed Nov 21 10:19:51 2007 @@ -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>