extlib/Console/Getopt.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4: */
   3 /**
   4  * PHP Version 5
   5  *
   6  * Copyright (c) 1997-2004 The PHP Group
   7  *
   8  * This source file is subject to version 3.0 of the PHP license,
   9  * that is bundled with this package in the file LICENSE, and is
  10  * available through the world-wide-web at the following url:
  11  * http://www.php.net/license/3_0.txt.
  12  * If you did not receive a copy of the PHP license and are unable to
  13  * obtain it through the world-wide-web, please send a note to
  14  * license@php.net so we can mail you a copy immediately.
  15  *
  16  * @category Console
  17  * @package  Console_Getopt
  18  * @author   Andrei Zmievski <andrei@php.net>
  19  * @license  http://www.php.net/license/3_0.txt PHP 3.0
  20  * @version  CVS: $Id: Getopt.php 306067 2010-12-08 00:13:31Z dufuz $
  21  * @link     http://pear.php.net/package/Console_Getopt
  22  */
  23
  24 require_once 'PEAR.php';
  25
  26 /**
  27  * Command-line options parsing class.
  28  *
  29  * @category Console
  30  * @package  Console_Getopt
  31  * @author   Andrei Zmievski <andrei@php.net>
  32  * @license  http://www.php.net/license/3_0.txt PHP 3.0
  33  * @link     http://pear.php.net/package/Console_Getopt
  34  */
  35 class Console_Getopt
  36 {
  37
  38     /**
  39      * Parses the command-line options.
  40      *
  41      * The first parameter to this function should be the list of command-line
  42      * arguments without the leading reference to the running program.
  43      *
  44      * The second parameter is a string of allowed short options. Each of the
  45      * option letters can be followed by a colon ':' to specify that the option
  46      * requires an argument, or a double colon '::' to specify that the option
  47      * takes an optional argument.
  48      *
  49      * The third argument is an optional array of allowed long options. The
  50      * leading '--' should not be included in the option name. Options that
  51      * require an argument should be followed by '=', and options that take an
  52      * option argument should be followed by '=='.
  53      *
  54      * The return value is an array of two elements: the list of parsed
  55      * options and the list of non-option command-line arguments. Each entry in
  56      * the list of parsed options is a pair of elements - the first one
  57      * specifies the option, and the second one specifies the option argument,
  58      * if there was one.
  59      *
  60      * Long and short options can be mixed.
  61      *
  62      * Most of the semantics of this function are based on GNU getopt_long().
  63      *
  64      * @param array  $args          an array of command-line arguments
  65      * @param string $short_options specifies the list of allowed short options
  66      * @param array  $long_options  specifies the list of allowed long options
  67      * @param boolean $skip_unknown suppresses Console_Getopt: unrecognized option
  68      *
  69      * @return array two-element array containing the list of parsed options and
  70      * the non-option arguments
  71      * @access public
  72      */
  73     function getopt2($args, $short_options, $long_options = null, $skip_unknown = false)
  74     {
  75         return Console_Getopt::doGetopt(2, $args, $short_options, $long_options, $skip_unknown);
  76     }
  77
  78     /**
  79      * This function expects $args to start with the script name (POSIX-style).
  80      * Preserved for backwards compatibility.
  81      *
  82      * @param array  $args          an array of command-line arguments
  83      * @param string $short_options specifies the list of allowed short options
  84      * @param array  $long_options  specifies the list of allowed long options
  85      *
  86      * @see getopt2()
  87      * @return array two-element array containing the list of parsed options and
  88      * the non-option arguments
  89      */
  90     function getopt($args, $short_options, $long_options = null, $skip_unknown = false)
  91     {
  92         return Console_Getopt::doGetopt(1, $args, $short_options, $long_options, $skip_unknown);
  93     }
  94
  95     /**
  96      * The actual implementation of the argument parsing code.
  97      *
  98      * @param int    $version       Version to use
  99      * @param array  $args          an array of command-line arguments
 100      * @param string $short_options specifies the list of allowed short options
 101      * @param array  $long_options  specifies the list of allowed long options
 102      * @param boolean $skip_unknown suppresses Console_Getopt: unrecognized option
 103      *
 104      * @return array
 105      */
 106     function doGetopt($version, $args, $short_options, $long_options = null, $skip_unknown = false)
 107     {
 108         // in case you pass directly readPHPArgv() as the first arg
 109         if (PEAR::isError($args)) {
 110             return $args;
 111         }
 112
 113         if (empty($args)) {
 114             return array(array(), array());
 115         }
 116
 117         $non_opts = $opts = array();
 118
 119         settype($args, 'array');
 120
 121         if ($long_options) {
 122             sort($long_options);
 123         }
 124
 125         /*
 126          * Preserve backwards compatibility with callers that relied on
 127          * erroneous POSIX fix.
 128          */
 129         if ($version < 2) {
 130             if (isset($args[0]{0}) && $args[0]{0} != '-') {
 131                 array_shift($args);
 132             }
 133         }
 134
 135         reset($args);
 136         while (list($i, $arg) = each($args)) {
 137             /* The special element '--' means explicit end of
 138                options. Treat the rest of the arguments as non-options
 139                and end the loop. */
 140             if ($arg == '--') {
 141                 $non_opts = array_merge($non_opts, array_slice($args, $i + 1));
 142                 break;
 143             }
 144
 145             if ($arg{0} != '-' || (strlen($arg) > 1 && $arg{1} == '-' && !$long_options)) {
 146                 $non_opts = array_merge($non_opts, array_slice($args, $i));
 147                 break;
 148             } elseif (strlen($arg) > 1 && $arg{1} == '-') {
 149                 $error = Console_Getopt::_parseLongOption(substr($arg, 2),
 150                                                           $long_options,
 151                                                           $opts,
 152                                                           $args,
 153                                                           $skip_unknown);
 154                 if (PEAR::isError($error)) {
 155                     return $error;
 156                 }
 157             } elseif ($arg == '-') {
 158                 // - is stdin
 159                 $non_opts = array_merge($non_opts, array_slice($args, $i));
 160                 break;
 161             } else {
 162                 $error = Console_Getopt::_parseShortOption(substr($arg, 1),
 163                                                            $short_options,
 164                                                            $opts,
 165                                                            $args,
 166                                                            $skip_unknown);
 167                 if (PEAR::isError($error)) {
 168                     return $error;
 169                 }
 170             }
 171         }
 172
 173         return array($opts, $non_opts);
 174     }
 175
 176     /**
 177      * Parse short option
 178      *
 179      * @param string     $arg           Argument
 180      * @param string[]   $short_options Available short options
 181      * @param string[][] &$opts
 182      * @param string[]   &$args
 183      * @param boolean    $skip_unknown suppresses Console_Getopt: unrecognized option
 184      *
 185      * @access private
 186      * @return void
 187      */
 188     function _parseShortOption($arg, $short_options, &$opts, &$args, $skip_unknown)
 189     {
 190         for ($i = 0; $i < strlen($arg); $i++) {
 191             $opt     = $arg{$i};
 192             $opt_arg = null;
 193
 194             /* Try to find the short option in the specifier string. */
 195             if (($spec = strstr($short_options, $opt)) === false || $arg{$i} == ':') {
 196                 if ($skip_unknown === true) {
 197                     break;
 198                 }
 199
 200                 $msg = "Console_Getopt: unrecognized option -- $opt";
 201                 return PEAR::raiseError($msg);
 202             }
 203
 204             if (strlen($spec) > 1 && $spec{1} == ':') {
 205                 if (strlen($spec) > 2 && $spec{2} == ':') {
 206                     if ($i + 1 < strlen($arg)) {
 207                         /* Option takes an optional argument. Use the remainder of
 208                            the arg string if there is anything left. */
 209                         $opts[] = array($opt, substr($arg, $i + 1));
 210                         break;
 211                     }
 212                 } else {
 213                     /* Option requires an argument. Use the remainder of the arg
 214                        string if there is anything left. */
 215                     if ($i + 1 < strlen($arg)) {
 216                         $opts[] = array($opt,  substr($arg, $i + 1));
 217                         break;
 218                     } else if (list(, $opt_arg) = each($args)) {
 219                         /* Else use the next argument. */;
 220                         if (Console_Getopt::_isShortOpt($opt_arg)
 221                             || Console_Getopt::_isLongOpt($opt_arg)) {
 222                             $msg = "option requires an argument --$opt";
 223                             return PEAR::raiseError("Console_Getopt:" . $msg);
 224                         }
 225                     } else {
 226                         $msg = "option requires an argument --$opt";
 227                         return PEAR::raiseError("Console_Getopt:" . $msg);
 228                     }
 229                 }
 230             }
 231
 232             $opts[] = array($opt, $opt_arg);
 233         }
 234     }
 235
 236     /**
 237      * Checks if an argument is a short option
 238      *
 239      * @param string $arg Argument to check
 240      *
 241      * @access private
 242      * @return bool
 243      */
 244     function _isShortOpt($arg)
 245     {
 246         return strlen($arg) == 2 && $arg[0] == '-'
 247                && preg_match('/[a-zA-Z]/', $arg[1]);
 248     }
 249
 250     /**
 251      * Checks if an argument is a long option
 252      *
 253      * @param string $arg Argument to check
 254      *
 255      * @access private
 256      * @return bool
 257      */
 258     function _isLongOpt($arg)
 259     {
 260         return strlen($arg) > 2 && $arg[0] == '-' && $arg[1] == '-' &&
 261                preg_match('/[a-zA-Z]+$/', substr($arg, 2));
 262     }
 263
 264     /**
 265      * Parse long option
 266      *
 267      * @param string     $arg          Argument
 268      * @param string[]   $long_options Available long options
 269      * @param string[][] &$opts
 270      * @param string[]   &$args
 271      *
 272      * @access private
 273      * @return void|PEAR_Error
 274      */
 275     function _parseLongOption($arg, $long_options, &$opts, &$args, $skip_unknown)
 276     {
 277         @list($opt, $opt_arg) = explode('=', $arg, 2);
 278
 279         $opt_len = strlen($opt);
 280
 281         for ($i = 0; $i < count($long_options); $i++) {
 282             $long_opt  = $long_options[$i];
 283             $opt_start = substr($long_opt, 0, $opt_len);
 284
 285             $long_opt_name = str_replace('=', '', $long_opt);
 286
 287             /* Option doesn't match. Go on to the next one. */
 288             if ($long_opt_name != $opt) {
 289                 continue;
 290             }
 291
 292             $opt_rest = substr($long_opt, $opt_len);
 293
 294             /* Check that the options uniquely matches one of the allowed
 295                options. */
 296             if ($i + 1 < count($long_options)) {
 297                 $next_option_rest = substr($long_options[$i + 1], $opt_len);
 298             } else {
 299                 $next_option_rest = '';
 300             }
 301
 302             if ($opt_rest != '' && $opt{0} != '=' &&
 303                 $i + 1 < count($long_options) &&
 304                 $opt == substr($long_options[$i+1], 0, $opt_len) &&
 305                 $next_option_rest != '' &&
 306                 $next_option_rest{0} != '=') {
 307
 308                 $msg = "Console_Getopt: option --$opt is ambiguous";
 309                 return PEAR::raiseError($msg);
 310             }
 311
 312             if (substr($long_opt, -1) == '=') {
 313                 if (substr($long_opt, -2) != '==') {
 314                     /* Long option requires an argument.
 315                        Take the next argument if one wasn't specified. */;
 316                     if (!strlen($opt_arg) && !(list(, $opt_arg) = each($args))) {
 317                         $msg = "Console_Getopt: option requires an argument --$opt";
 318                         return PEAR::raiseError($msg);
 319                     }
 320
 321                     if (Console_Getopt::_isShortOpt($opt_arg)
 322                         || Console_Getopt::_isLongOpt($opt_arg)) {
 323                         $msg = "Console_Getopt: option requires an argument --$opt";
 324                         return PEAR::raiseError($msg);
 325                     }
 326                 }
 327             } else if ($opt_arg) {
 328                 $msg = "Console_Getopt: option --$opt doesn't allow an argument";
 329                 return PEAR::raiseError($msg);
 330             }
 331
 332             $opts[] = array('--' . $opt, $opt_arg);
 333             return;
 334         }
 335
 336         if ($skip_unknown === true) {
 337             return;
 338         }
 339
 340         return PEAR::raiseError("Console_Getopt: unrecognized option --$opt");
 341     }
 342
 343     /**
 344      * Safely read the $argv PHP array across different PHP configurations.
 345      * Will take care on register_globals and register_argc_argv ini directives
 346      *
 347      * @access public
 348      * @return mixed the $argv PHP array or PEAR error if not registered
 349      */
 350     function readPHPArgv()
 351     {
 352         global $argv;
 353         if (!is_array($argv)) {
 354             if (!@is_array($_SERVER['argv'])) {
 355                 if (!@is_array($GLOBALS['HTTP_SERVER_VARS']['argv'])) {
 356                     $msg = "Could not read cmd args (register_argc_argv=Off?)";
 357                     return PEAR::raiseError("Console_Getopt: " . $msg);
 358                 }
 359                 return $GLOBALS['HTTP_SERVER_VARS']['argv'];
 360             }
 361             return $_SERVER['argv'];
 362         }
 363         return $argv;
 364     }
 365
 366 }