Update and license of cliopts.php.

* Updated the code to be closer to the latest upstream one.
* Updated the license: it used to be under the problematic PHP License,
  and is now under the BSD License, thanks to the original author and
  contributor agreement.

1 files changed, 164 insertions, 22 deletions

diff --git a/inc/cliopts.php b/inc/cliopts.php
index ede559a63..588f0bc6d 100644
--- a/inc/cliopts.php
+++ b/inc/cliopts.php
@@ -1,25 +1,27 @@
 <?php
 /**
  * Brutally chopped and modified from http://pear.php.net/package/Console_Getopts
+ *
+ * PHP Version 5
+ *
+ * Copyright (c) 1997-2004 The PHP Group
+ *
+  * LICENSE: This source file is subject to the New BSD license that is
+ * available through the world-wide-web at the following URI:
+ * http://www.opensource.org/licenses/bsd-license.php. If you did not receive
+ * a copy of the New BSD License and are unable to obtain it through the web,
+ * please send a note to license@php.net so we can mail you a copy immediately.
+ *
+ * @category Console
+ * @package  Console_Getopt
+ * @author   Andrei Zmievski <andrei@php.net>
+ * @modified Harry Fuecks hfuecks  gmail.com
+ * @modified Tanguy Ortolo <tanguy+dokuwiki@ortolo.eu>
+ * @license  http://www.opensource.org/licenses/bsd-license.php New BSD License
+ * @version  CVS: $Id$
+ * @link     http://pear.php.net/package/Console_Getopt
+ *
  */
-// +----------------------------------------------------------------------+
-// | PHP Version 4                                                        |
-// +----------------------------------------------------------------------+
-// | Copyright (c) 1997-2003 The PHP Group                                |
-// +----------------------------------------------------------------------+
-// | This source file is subject to version 3.0 of the PHP license,       |
-// | that is bundled with this package in the file LICENSE, and is        |
-// | available through the world-wide-web at the following url:           |
-// | http://www.php.net/license/3_0.txt.                                  |
-// | If you did not receive a copy of the PHP license and are unable to   |
-// | obtain it through the world-wide-web, please send a note to          |
-// | license@php.net so we can mail you a copy immediately.               |
-// +----------------------------------------------------------------------+
-// | Author: Andrei Zmievski <andrei@php.net>                             |
-// | Modified: Harry Fuecks hfuecks  gmail.com                   |
-// +----------------------------------------------------------------------+
-//
-
 
 //------------------------------------------------------------------------------
 /**
@@ -99,18 +101,74 @@ class Doku_Cli_Opts {
         return $container;
     }
 
+    /**
+     * Parses the command-line options.
+     *
+     * The first parameter to this function should be the list of command-line
+     * arguments without the leading reference to the running program.
+     *
+     * The second parameter is a string of allowed short options. Each of the
+     * option letters can be followed by a colon ':' to specify that the option
+     * requires an argument, or a double colon '::' to specify that the option
+     * takes an optional argument.
+     *
+     * The third argument is an optional array of allowed long options. The
+     * leading '--' should not be included in the option name. Options that
+     * require an argument should be followed by '=', and options that take an
+     * option argument should be followed by '=='.
+     *
+     * 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.
+     *
+     * Long and short options can be mixed.
+     *
+     * Most of the semantics of this function are based on GNU getopt_long().
+     *
+     * @param array  $args          an array of command-line arguments
+     * @param string $short_options specifies the list of allowed short options
+     * @param array  $long_options  specifies the list of allowed long options
+     *
+     * @return array two-element array containing the list of parsed options and
+     * the non-option arguments
+     * @access public
+     */
     function getopt2($args, $short_options, $long_options = null) {
         return Doku_Cli_Opts::doGetopt(
             2, $args, $short_options, $long_options
             );
     }
 
+    /**
+     * This function expects $args to start with the script name (POSIX-style).
+     * Preserved for backwards compatibility.
+     *
+     * @param array  $args          an array of command-line arguments
+     * @param string $short_options specifies the list of allowed short options
+     * @param array  $long_options  specifies the list of allowed long options
+     *
+     * @see getopt2()
+     * @return array two-element array containing the list of parsed options and
+     * the non-option arguments
+     */
     function getopt($args, $short_options, $long_options = null) {
         return Doku_Cli_Opts::doGetopt(
             1, $args, $short_options, $long_options
             );
     }
 
+    /**
+     * The actual implementation of the argument parsing code.
+     *
+     * @param int    $version       Version to use
+     * @param array  $args          an array of command-line arguments
+     * @param string $short_options specifies the list of allowed short options
+     * @param array  $long_options  specifies the list of allowed long options
+     *
+     * @return array
+     */
     function doGetopt($version, $args, $short_options, $long_options = null) {
 
         // in case you pass directly readPHPArgv() as the first arg
@@ -157,6 +215,10 @@ class Doku_Cli_Opts {
                 $error = Doku_Cli_Opts::_parseLongOption(substr($arg, 2), $long_options, $opts, $args);
                 if (Doku_Cli_Opts::isError($error))
                     return $error;
+            } elseif ($arg == '-') {
+                // - is stdin
+                $non_opts = array_merge($non_opts, array_slice($args, $i));
+                break;
             } else {
                 $error = Doku_Cli_Opts::_parseShortOption(substr($arg, 1), $short_options, $opts, $args);
                 if (Doku_Cli_Opts::isError($error))
@@ -167,6 +229,17 @@ class Doku_Cli_Opts {
         return array($opts, $non_opts);
     }
 
+    /**
+     * Parse short option
+     *
+     * @param string     $arg           Argument
+     * @param string[]   $short_options Available short options
+     * @param string[][] &$opts
+     * @param string[]   &$args
+     *
+     * @access private
+     * @return void
+     */
     function _parseShortOption($arg, $short_options, &$opts, &$args) {
         $len = strlen($arg);
         for ($i = 0; $i < $len; $i++) {
@@ -196,8 +269,14 @@ class Doku_Cli_Opts {
                     if ($i + 1 < strlen($arg)) {
                         $opts[] = array($opt,  substr($arg, $i + 1));
                         break;
-                    } else if (list(, $opt_arg) = each($args))
+                    } else if (list(, $opt_arg) = each($args)) {
                         /* Else use the next argument. */;
+                        if (Doku_Cli_Opts::_isShortOpt($opt_arg) || Doku_Cli_Opts::_isLongOpt($opt_arg))
+                            return Doku_Cli_Opts::raiseError(
+                                DOKU_CLI_OPTS_OPT_ARG_REQUIRED,
+                                "option requires an argument --$opt"
+                                );
+                    }
                     else
                         return Doku_Cli_Opts::raiseError(
                             DOKU_CLI_OPTS_OPT_ARG_REQUIRED,
@@ -210,8 +289,47 @@ class Doku_Cli_Opts {
         }
     }
 
+    /**
+     * Checks if an argument is a short option
+     *
+     * @param string $arg Argument to check
+     *
+     * @access private
+     * @return bool
+     */
+    function _isShortOpt($arg)
+    {
+        return strlen($arg) == 2 && $arg[0] == '-' 
+               && preg_match('/[a-zA-Z]/', $arg[1]);
+    }
+
+    /**
+     * Checks if an argument is a long option
+     *
+     * @param string $arg Argument to check
+     *
+     * @access private
+     * @return bool
+     */
+    function _isLongOpt($arg)
+    {
+        return strlen($arg) > 2 && $arg[0] == '-' && $arg[1] == '-' &&
+               preg_match('/[a-zA-Z]+$/', substr($arg, 2));
+    }
+
+    /**
+     * Parse long option
+     *
+     * @param string     $arg          Argument
+     * @param string[]   $long_options Available long options
+     * @param string[][] &$opts
+     * @param string[]   &$args
+     *
+     * @access private
+     * @return void|PEAR_Error
+     */
     function _parseLongOption($arg, $long_options, &$opts, &$args) {
-        @list($opt, $opt_arg) = explode('=', $arg);
+        @list($opt, $opt_arg) = explode('=', $arg, 2);
         $opt_len = strlen($opt);
         $opt_cnt = count($long_options);
 
@@ -219,17 +337,27 @@ class Doku_Cli_Opts {
             $long_opt  = $long_options[$i];
             $opt_start = substr($long_opt, 0, $opt_len);
 
+            $long_opt_name = str_replace('=', '', $long_opt);
+
             /* Option doesn't match. Go on to the next one. */
             if ($opt_start != $opt)
                 continue;
 
-            $opt_rest  = substr($long_opt, $opt_len);
+            $opt_rest = substr($long_opt, $opt_len);
 
             /* Check that the options uniquely matches one of the allowed
                options. */
+            if ($i + 1 < count($long_options)) {
+                $next_option_rest = substr($long_options[$i + 1], $opt_len);
+            } else {
+                $next_option_rest = '';
+            }
+
             if ($opt_rest != '' && $opt{0} != '=' &&
                 $i + 1 < $opt_cnt &&
-                $opt == substr($long_options[$i+1], 0, $opt_len)) {
+                $opt == substr($long_options[$i+1], 0, $opt_len) &&
+                $next_option_rest != '' &&
+                $next_option_rest{0} != '=') {
                 return Doku_Cli_Opts::raiseError(
                     DOKU_CLI_OPTS_OPT_ABIGUOUS,
                     "Option --$opt is ambiguous"
@@ -246,6 +374,13 @@ class Doku_Cli_Opts {
                             "Option --$opt requires an argument"
                             );
                     }
+
+                    if (Doku_Cli_Opts::_isShortOpt($opt_arg)
+                        || Doku_Cli_Opts::_isLongOpt($opt_arg))
+                        return Doku_Cli_Opts::raiseError(
+                            DOKU_CLI_OPTS_OPT_ARG_REQUIRED,
+                            "Option --$opt requires an argument"
+                            );
                 }
             } else if ($opt_arg) {
                 return Doku_Cli_Opts::raiseError(
@@ -264,6 +399,13 @@ class Doku_Cli_Opts {
             );
     }
 
+    /**
+     * Safely read the $argv PHP array across different PHP configurations.
+     * Will take care on register_globals and register_argc_argv ini directives
+     *
+     * @access public
+     * @return mixed the $argv PHP array or PEAR error if not registered
+     */
     function readPHPArgv() {
         global $argv;
         if (!is_array($argv)) {