merged

Author: shabbyrobe

.gitignore

@@ -1,3 +1 @@
-.buildpath
-.settings
-.project
+vendor/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "py"]
+	path = py
+	url = https://github.com/docopt/docopt.git

.travis.yml

@@ -0,0 +1,19 @@
+language: php
+
+before_install:
+  - git submodule update --init
+  - composer install
+
+php:
+  - "hhvm"
+  - "5.6"
+  - "5.5"
+  - "5.4"
+  - "5.3"
+
+branches:
+  only:
+    - master
+    - develop
+
+script: php test.php

README.rst

@@ -1,6 +1,8 @@
 ``docopt`` creates *beautiful* command-line interfaces
 ======================================================================
 
+.. image:: https://travis-ci.org/docopt/docopt.php.svg?branch=master
+
 This is a straight PHP transliteration of Vladimir Keleshev's brilliant
 `docopt <https://github.com/docopt/docopt/>`_ Python library. There are a
 few artefacts in the code as a result that may seem inefficient and
@@ -9,34 +11,34 @@ efficient.
 
 As a result, unless a bug is present only in the PHP version, pull requests
 are unlikely to be accepted unless they are themselves direct transliterations
-of bugfixes in the Python version.
+of bugfixes in the Python version. 
 
+**This port has been marked version 1.0.0 RC1**. It is based on the Python version at
+commit `1937a1c9041e0f580d2890d38bb71c0a0623847f
+<https://github.com/docopt/docopt/commit/d5b96f878abbda51b62f1e28010d2b42b19a27dc>`_
+(labelled **0.6.1**).
 
-Video introduction to **docopt**: `PyCon UK 2012: Create *beautiful*
-command-line interfaces with Python <http://youtu.be/pXhcPJK5cMc>`_
+It has been quite stable for a long time and has barely been changed.  The Python version
+receives only occasional bugfixes and keeping the version numbers pinned has been more
+trouble than it has been worth.
 
-    New in version 0.6.0:
+There are also some major backward compatibility breaks. Rather than dwell in 0.x semver
+hell, the PHP port will liberally bump major numbers henceforth when BC breaks regardless
+of the reason.
 
-    - New argument ``options_first``, disallows interspersing options
-      and arguments.  If you supply ``options_first=True`` to
-      ``docopt``, it will interpret all arguments as positional
-      arguments after first positional argument.
+- The PHP API has changed slightly. ``Docopt\docopt()`` has been renamed to
+  ``Docopt::handle()`` to fix autoloader support. See `issue #3
+  <https://github.com/docopt/docopt.php/pull/3>`_.
 
-    - If option with argument could be repeated, its default value
-      will be interpreted as space-separated list. E.g. with
-      ``[default: ./here ./there]`` will be interpreted as
-      ``['./here', './there']``.
+- Docopt.py also has a significant BC break. Existing users should read the information
+  below about Usage and Option sections. See `issue 102
+  <https://github.com/docopt/docopt/issues/102>`_ for more info.
 
-    Breaking changes:
 
-    - Meaning of ``[options]`` shortcut slightly changed. Previously
-      it ment *"any known option"*. Now it means *"any option not in
-      usage-pattern"*.  This avoids the situation when an option is
-      allowed to be repeated unintentionaly.
+Please see the `Python version's README <https://github.com/docopt/docopt/blob/master/README.rst>`_ 
+for details of any new and breaking changes that are not specific to the PHP version.
 
-    - ``argv`` is ``None`` by default, not ``sys.argv[1:]``.
-      This allows ``docopt`` to always use the *latest* ``sys.argv``,
-      not ``sys.argv`` during import time.
+-----
 
 Isn't it awesome how ``optparse`` and ``argparse`` generate help
 messages based on your code?!
@@ -73,8 +75,7 @@ and instead can write only the help message--*the way you want it*.
     DOC;
     
     require('path/to/src/docopt.php');
-    $handler = new \Docopt\Handler(array('version'=>'Naval Fate 2.0'));
-    $args = $handler->handle($doc);
+    $args = Docopt::handle($doc, array('version'=>'Naval Fate 2.0'));
     foreach ($args as $k=>$v)
         echo $k.': '.json_encode($v).PHP_EOL;
 
@@ -98,7 +99,7 @@ Create a ``composer.json`` file for your project
 
     {
         "require": {
-            "docopt/docopt": "0.6.0"
+            "docopt/docopt": "1.0.0-rc1"
         }
     }
 
@@ -107,10 +108,25 @@ Install using composer::
     php composer.phar install
 
 
-Alternatively, you can just drop `docopt.php` file into your project--it is
+Alternatively, you can just drop ``docopt.php`` file into your project--it is
 self-contained. `Get source on github <http://github.com/docopt/docopt.php>`_.
 
-``docopt.php`` is tested with PHP 5.3
+``docopt.php`` is tested with PHP 5.4 and PHP 5.3.
+
+
+Testing
+======================================================================
+
+Configure your repo for running tests::
+
+    ./dev-setup
+
+You can run unit tests with the following command::
+
+    php test.php
+
+This will run the Python language agnostic tests as well as the PHP
+docopt tests.
 
 
 API
@@ -121,24 +137,53 @@ API
     <?php
     require('/path/to/src/docopt.php');
     
+    // short form, simple API
+    $args = Docopt::handle($doc);
+
     // short form (5.4 or better)
     $args = (new \Docopt\Handler)->handle($sdoc);
 
-    // long form (equivalent to short)
+    // long form, simple API (equivalent to short)
     $params = array(
         'argv'=>array_slice($_SERVER['argv'], 1),
         'help'=>true,
         'version'=>null,
         'optionsFirst'=>false,
     );
-    $handler = new \Docopt\Handler($params);
-    $args = $handler->handle($doc);
+    $args = Docopt::handle($doc, $params);
+    
+    // long form, full API
+    $handler = new \Docopt\Handler(array(
+        'help'=>true,
+        'optionsFirst'=>false,
+    ));
+    $handler->handle($doc, $argv);
 
 
-The constructor for ``Docopt\Handler`` takes one optional argument (the
-defaults are listed in the above example):
+``Docopt::handle()`` takes 1 required and 1 optional argument:
+
+- ``doc`` is a string that contains a **help message** that will be parsed to
+  create the option parser.  The simple rules of how to write such a
+  help message are given in next sections.  Here is a quick example of
+  such a string:
 
-- ``params`` is an array of additional data to influence
+.. code:: php
+    
+    <?php
+    $doc = <<<DOC
+    Usage: my_program.php [-hso FILE] [--quiet | --verbose] [INPUT ...]
+    
+    Options:
+      -h --help    show this
+      -s --sorted  sorted output
+      -o FILE      specify output file [default: ./test.txt]
+      --quiet      print less text
+      --verbose    print more text
+
+    DOC;
+
+
+- ``params`` is an optional array of additional data to influence
   ``docopt``. The following keys are supported: 
 
   - ``argv`` is an optional argument vector; by default ``docopt`` uses
@@ -221,27 +266,39 @@ the return dictionary will be:
 Help message format
 ======================================================================
 
-Help message consists of 2 parts:
+Help message consists of 2 sections:
 
-- Usage pattern, e.g.::
+- Usage section, starting with ``Usage:`` e.g.::
 
     Usage: my_program.php [-hso FILE] [--quiet | --verbose] [INPUT ...]
 
-- Option descriptions, e.g.::
+- Option section, starting with ``Options:`` e.g.::
 
-    -h --help    show this
-    -s --sorted  sorted output
-    -o FILE      specify output file [default: ./test.txt]
-    --quiet      print less text
-    --verbose    print more text
+    Options:
+      -h --help    show this
+      -s --sorted  sorted output
+      -o FILE      specify output file [default: ./test.txt]
+      --quiet      print less text
+      --verbose    print more text
+
+Sections consist of a header and a body. The section body can begin on
+the same line as the header, but if it spans multiple lines, it must be 
+indented. A section is terminated by an empty line or a string with no
+indentation::
+
+    Section header: Section body
+    
+    Section header:
+      Section body, which is indented at least
+      one space or tab from the section header
+
+    Section header: Section body, which is indented at least
+      one space or tab from the section header
 
-Their format is described below; other text is ignored.
 
-Usage pattern format
+Usage section format
 ----------------------------------------------------------------------
 
-**Usage pattern** is a substring of ``doc`` that starts with
-``usage:`` (case *insensitive*) and ends with a *visibly* empty line.
 Minimum example::
 
     Usage: my_program.php
@@ -259,14 +316,16 @@ Each pattern can consist of the following elements:
 - **<arguments>**, **ARGUMENTS**. Arguments are specified as either
   upper-case words, e.g. ``my_program.php CONTENT-PATH`` or words
   surrounded by angular brackets: ``my_program.php <content-path>``.
+  
 - **--options**.  Options are words started with dash (``-``), e.g.
   ``--output``, ``-o``.  You can "stack" several of one-letter
   options, e.g. ``-oiv`` which will be the same as ``-o -i -v``. The
   options can have arguments, e.g.  ``--input=FILE`` or ``-i FILE`` or
   even ``-iFILE``. However it is important that you specify option
-  descriptions if you want for option to have an argument, a default
+  descriptions if you want your option to have an argument, a default
   value, or specify synonymous short/long versions of option (see next
   section on option descriptions).
+  
 - **commands** are words that do *not* follow the described above
   conventions of ``--options`` or ``<arguments>`` or ``ARGUMENTS``,
   plus two special commands: dash "``-``" and double dash "``--``"
@@ -276,29 +335,33 @@ Use the following constructs to specify patterns:
 
 - **[ ]** (brackets) **optional** elements.  e.g.: ``my_program.php
   [-hvqo FILE]``
+  
 - **( )** (parens) **required** elements.  All elements that are *not*
   put in **[ ]** are also required, e.g.: ``my_program.php
   --path=<path> <file>...`` is the same as ``my_program.php
   (--path=<path> <file>...)``.  (Note, "required options" might be not
   a good idea for your users).
-- **|** (pipe) **mutualy exclusive** elements. Group them using **(
+  
+- **|** (pipe) **mutually exclusive** elements. Group them using **(
   )** if one of the mutually exclusive elements is required:
   ``my_program.php (--clockwise | --counter-clockwise) TIME``. Group
   them using **[ ]** if none of the mutually-exclusive elements are
   required: ``my_program.php [--left | --right]``.
+  
 - **...** (ellipsis) **one or more** elements. To specify that
   arbitrary number of repeating elements could be accepted, use
   ellipsis (``...``), e.g.  ``my_program.php FILE ...`` means one or
   more ``FILE``-s are accepted.  If you want to accept zero or more
   elements, use brackets, e.g.: ``my_program.php [FILE ...]``. Ellipsis
   works as a unary operator on the expression to the left.
+  
 - **[options]** (case sensitive) shortcut for any options.  You can
   use it if you want to specify that the usage pattern could be
   provided with any options defined below in the option-descriptions
-  and do not want to enumerate them all in usage-pattern.  -
+  and do not want to enumerate them all in usage-pattern.
   "``[--]``". Double dash "``--``" is used by convention to separate
   positional arguments that can be mistaken for options. In order to
-  support this convention add "``[--]``" to you usage patterns.  -
+  support this convention add "``[--]``" to you usage patterns.
   "``[-]``". Single dash "``-``" is used by convention to signify that
   ``stdin`` is used instead of a file. To support this add "``[-]``"
   to you usage patterns. "``-``" act as a normal command.
@@ -308,7 +371,7 @@ times::
 
     Usage: my_program.php [-v | -vv | -vvv]
 
-then number of occurences of the option will be counted. I.e.
+then number of occurrences of the option will be counted. I.e.
 ``args['-v']`` will be ``2`` if program was invoked as ``my_program
 -vv``. Same works for commands.
 
@@ -323,11 +386,11 @@ I.e. invoked with ``my_program.php file1 file2 --path=./here
 ['file1', 'file2']`` and ``args['--path'] == ['./here', './there']``.
 
 
-Option descriptions format
+Options section format
 ----------------------------------------------------------------------
 
-**Option descriptions** consist of a list of options that you put
-below your usage patterns.
+The **Option section** is an optional section that contains a list of 
+options that can document or supplement your usage pattern.
 
 It is necessary to list option descriptions in order to specify:
 
@@ -337,8 +400,9 @@ It is necessary to list option descriptions in order to specify:
 
 The rules are as follows:
 
-- Every line in ``doc`` that starts with ``-`` or ``--`` (not counting
-  spaces) is treated as an option description, e.g.::
+- Every line in the options section body that starts with one or more
+  horizontal whitespace characters, followed by ``-`` or ``--`` is treated
+  as an option description, e.g.::
 
     Options:
       --verbose   # GOOD
@@ -353,7 +417,7 @@ The rules are as follows:
   to stick to a single style.::
 
     -o FILE --output=FILE       # without comma, with "=" sign
-    -i <file>, --input <file>   # with comma, wihtout "=" sing
+    -i <file>, --input <file>   # with comma, wihtout "=" sign
 
 - Use two spaces to separate options with their informal description::
 
@@ -372,7 +436,7 @@ The rules are as follows:
     --directory=DIR  Some directory [default: ./]
 
 - If the option is not repeatable, the value inside ``[default: ...]``
-  will be interpeted as string.  If it *is* repeatable, it will be
+  will be interpreted as string.  If it *is* repeatable, it will be
   splited into a list on whitespace::
 
     Usage: my_program.php [--repeatable=<arg> --repeatable=<arg>]
@@ -388,6 +452,7 @@ The rules are as follows:
     # will be './here ./there', because it is not repeatable
     --not-repeatable=<arg>      [default: ./here ./there]
 
+
 Examples
 ----------------------------------------------------------------------
 
@@ -396,11 +461,12 @@ We have an extensive list of `examples
 every aspect of functionality of **docopt**.  Try them out, read the
 source if in doubt.
 
+
 Subparsers, multi-level help and *huge* applications (like git)
 ----------------------------------------------------------------------
 
 If you want to split your usage-pattern into several, implement
-multi-level help (whith separate help-screen for each subcommand),
+multi-level help (with separate help-screen for each subcommand),
 want to interface with existing scripts that don't use **docopt**, or
 you're building the next "git", you will need the new ``options_first``
 parameter (described in API section above). To get you started quickly