cvs: peardoc /en/core console.xml

alexmerz Sun Jan 27 09:35:21 2002 EDT Added files: /peardoc/en/core console.xml Log: initial checkin Index: peardoc/en/core/console.xml +++ peardoc/en/core/console.xml <?xml encoding="iso-8859-1"?> <!-- $Id: console.xml,v 1.1 2002/01/27 14:35:21 alexmerz Exp $ --> <reference id="core.console"> <title>PEAR Console</title> <titleabbrev>Functions for PHP-based console applications</titleabbrev> <partintro> <simpara> </simpara> </partintro> <refentry id="core.console.getopt"> <refnamediv> <refname>Console_Getopt</refname> <refpurpose>Command-line options parsing class</refpurpose> </refnamediv> <refsect1 id="core.console.getopt.readphpargv"> <title>Console_Getopt::readPHPArgv</title> <funcsynopsis> <funcprototype> <funcdef>array <function>readPHPArgv</function></funcdef> <paramdef></paramdef> </funcprototype> </funcsynopsis> <para> Safely read the $argv PHP array across different PHP configurations. Will take care on register_globals and register_argc_argv ini directives </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - array or <classname>PEAR_Error</classname> if not registered </para> </listitem> </itemizedlist> </para> <example> <title>Using</title> <programlisting role="php"> <![CDATA[ $con = new Console_Getopt; $args = $con->readPHPArgv(); array_shift($args); $options = $con->getopt( $args, $shortopt); ]]> </programlisting> </example> </refsect1> <refsect1 id="core.console.getopt.getopt"> <title>Console_Getopt::getopt</title> <funcsynopsis> <funcprototype> <funcdef>array <function>getopt</function></funcdef> <paramdef>string <parameter>$args</parameter></paramdef> <paramdef>string <parameter>$shortoptions</parameter></paramdef> <paramdef>array <parameter><optional>$longoptions</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> parses the command-line options </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$args</parameter> - an array of command-line arguments </para> </listitem> <listitem> <para> <parameter>$shortoptions</parameter> - specifies the list of allowed short options. See the <link linkend="core.console.getopt.getopt.options">"Options" section</link>. </para> </listitem> <listitem> <para> <parameter>$longoptions</parameter> - specifies the list of allowed long options. Default is <parameter>NULL</parameter>. See the <link linkend="core.console.getopt.getopt.options">"Options" section</link>. </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>mixed</parameter> - two-element array containing the list of parsed options and the non-option arguments or <classname>PEAR_Error</classname> </para> </listitem> </itemizedlist> </para> <refsect2 id="core.console.getopt.getopt.options"> <title>Options</title> <para> <function>Getopt</function> support two types of options: <parameter> short options</parameter> and <parameter>long options</parameter> <example> <title>Calling a script with short and long options</title> <para> <programlisting> # Using short options <command>myphpscript</command> <parameter>-q -l en -o</parameter> # Using long options instead <command>myphpscript</command> <parameter>--quite --lang=en --option</parameter> # Mixing both <command>myphpscript</command> <parameter>-q --lang=en -o</parameter> </programlisting> You have to define which options you want to support. The second argument of <function>getopt</function> requires a string containing all supported chars. For the example above this would be at least: <programlisting role="php"> $shortoptions = "qlo"; </programlisting> The order of the chars isn't important. Often you have to define options with (optional) parameters. To express, that a option requires a parameter, you have to add a colon. If the parameter is optional add a double colon, ie: <programlisting role="php"> $shortoptions = "ql:o::"; </programlisting> this means the following script calls are permitted, ie. <programlisting> <command>myphpscript</command> <parameter></parameter> <command>myphpscript</command> <parameter>-q</parameter> <command>myphpscript</command> <parameter>-q -l en </parameter> <command>myphpscript</command> <parameter>-o text </parameter> <command>myphpscript</command> <parameter>-o</parameter> </programlisting> not permitted would be: <programlisting> <command>myphpscript</command> <parameter>-l</parameter> </programlisting> The <parameter>-l</parameter> option requires a parameter, if the option is used. </para> <para> The long options work equal, but you have to define them in an array <programlisting role="php"> $longoptions = array("quite", "lang", "option"); </programlisting> For defining option parameters, use <parameter>'='</parameter> and <parameter>'=='</parameter> like the colon in short options. <programlisting role="php"> $longoptions = array("quite", "lang=", "option=="); </programlisting> </para> </example> </para> </refsect2> <refsect2 id="core.console.getopt.getopt.return"> <title>The returned array</title> <para> The return value is an array of two elements: the list of parsed options and the list of non-option command-line arguments. Each entry in the list of parsed options is a pair of elements - the first one specifies the option, and the second one specifies the option argument, if there was one, else the value is <parameter>NULL</parameter>. </para> </refsect2> </refsect1> </refentry> </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->