getArgumentValues and getFlagValues added

tests added
README improved

README.md

@@ -115,15 +115,23 @@ When an error occurs, print character to make the terminal "beep".
 
 ### `getOptions`
 
-Return an array of the values for each options provided to the command.
+Return an array of `Option`s for each options provided to the command.
 
 ### `getFlags`
 
-Return an array of the values for only the flags provided to the command.
+Return an array of `Option`s for only the flags provided to the command.
 
 ### `getArguments`
 
-Return an array of the values for only the arguments provided to the command.  The order of the array is the same as the order of the arguments.
+Return an array of `Options` for only the arguments provided to the command.  The order of the array is the same as the order of the arguments.
+
+### `getFlagValues`
+
+Return associative array of values for arguments provided to the command.  E.g. `array('f' => 'value1')`.
+
+### `getArgumentValues`
+
+Return array of values for arguments provided to the command. E.g. `array('value1', 'value2')`.
 
 ## Command Option Definition Methods
 
@@ -135,6 +143,14 @@ Aliases: `o`
 
 Define a new option.  When `name` is set, the option will be a named "flag" option.  Can be a short form option (e.g. `f` for option `-f`) or long form (e.g. `foo` for option --foo).  When no `name` is defined, the option is an annonymous argument and is referenced in the future by it's position.
 
+### `flag (mixed name = null)`
+
+Same as `option` except that it can only be used to define "flag" type options (a.k.a. those options that must be specified with a -flag on the command line).
+
+### `argument`
+
+Same as `option` except that it can only be used to define "argument" type options (a.k.a those options that are specified WITHOUT a -flag on the command line).
+
 ### `alias (string alias)`
 
 Aliases: `a`, `aka`
@@ -165,6 +181,12 @@ Aliases: `cast`, `castTo`
 
 Perform a map operation on the value for this option.  Takes function that accepts a string $value and return mixed (you can map to whatever you wish).
 
+### `referToAs (string name)`
+
+Aliases: `title`, `referredToAs`
+
+Add a name to refer to an argument option by.  Makes the help docs a little cleaner for annonymous "argument" options.
+
 ## Contributing
 
 Commando highly encourages sending in pull requests.  When submitting a pull request please:

examples/argumentsVsFlags.php

@@ -0,0 +1,37 @@
+<?php
+// Clearer definition of Arguments vs. Flags
+
+require dirname(__DIR__) . '/vendor/autoload.php';
+
+// v0.2.0 started to add a clearer definition between "flag" type options
+// and "argument" type options for those that may prefer it.
+// In Commando, flags are options that require a name when they are being
+// specified on the command line. Arguments are options that are not named in
+// this way. In the example below, '-f' and '--long' are described as "flags"
+// type options in Commando terms with the values 'value1' and 'value2'
+// respectively, whereas value3, value4, and value5 are described as "argument"
+// type options.
+// php argumentsVsFlags.php -f value1 --long value2 value3 value4 value5
+
+$cmd = new Commando\Command();
+$cmd
+    ->flag('f')
+    ->flag('l')
+        ->aka('long')
+    ->argument()
+    ->argument()
+    ->argument();
+
+var_dump($cmd->getArgumentValues());
+var_dump($cmd->getFlagValues());
+
+// This is equivalent to...
+
+// $cmd = new Commando\Command();
+// $cmd
+//     ->option('f')
+//     ->option('l')
+//         ->aka('long')
+//     ->option()
+//     ->option()
+//     ->option();

src/Commando/Command.php

@@ -418,27 +418,65 @@ public function getOption($option)
     }
 
     /**
-     * @return array of arguments only
+     * @return array of argument `Option` only
+     */
+    public function getArguments()
+    {
+        $this->parseIfNotParsed();
+        return $this->arguments;
+    }
+
+    /**
+     * @return array of flag `Option` only
+     */
+    public function getFlags()
+    {
+        $this->parseIfNotParsed();
+        return $this->flags;
+    }
+
+    /**
+     * @return array of argument values only
      *
      * If your command was `php filename -f flagvalue argument1 argument2`
      * `getArguments` would return array("argument1", "argument2");
      */
-    public function getArguments()
+    public function getArgumentValues()
     {
         $this->parseIfNotParsed();
-        return $this->arguments;
+        return array_map(function(Option $argument) {
+            return $argument->getValue();
+        }, $this->arguments);
     }
 
     /**
-     * @return array of flags only
+     * @return array of flag values only
      *
      * If your command was `php filename -f flagvalue argument1 argument2`
      * `getFlags` would return array("-f" => "flagvalue");
      */
-    public function getFlags()
+    public function getFlagValues()
     {
         $this->parseIfNotParsed();
-        return $this->flags;
+        return array_map(function(Option $flag) {
+            return $flag->getValue();
+        }, $this->dedupeFlags());
+    }
+
+    /**
+     * @return array of deduped flag Options.  Needed because of
+     *    how the flags are mapped internally to make alias lookup
+     *    simpler/faster.
+     */
+    private function dedupeFlags()
+    {
+        $seen = array();
+        foreach ($this->flags as $flag) {
+            if (empty($flags[$flag->getName()])) {
+                $seen[$flag->getName()] = $flag;
+            }
+        }
+        return $seen;
     }
 
     /**
@@ -645,4 +683,4 @@ public function valid()
     {
         return isset($this->sorted_keys[$this->position]);
     }
-}
+}

tests/Commando/CommandTest.php

@@ -108,4 +108,16 @@ public function testRevtrievingOptionAnon()
         $this->assertEquals(1, $cmd->getSize());
     }
 
+    public function testGetValues()
+    {
+        $tokens = array('filename', '-a', 'v1', '-b', 'v2', 'v3', 'v4', 'v5');
+        $cmd = new Command($tokens);
+        $cmd
+            ->flag('a')
+            ->flag('b')->aka('boo');
+
+        $this->assertEquals(array('v3', 'v4', 'v5'), $cmd->getArgumentValues());
+        $this->assertEquals(array('a' => 'v1', 'b' => 'v2'), $cmd->getFlagValues());
+    }
+
 }