Added ParameterParser halting functionality, added ParameterResult cl…

…ass, added helper functions for ParameterResult.
nathan-fiscaletti · Jun 5, 2018 · be6d274 · be6d274
1 parent 0ec3146
commit be6d274
Show file tree

Hide file tree

Showing 10 changed files with 270 additions and 4 deletions.
diff --git a/examples/Example1.md b/examples/Example1.md
@@ -5,6 +5,7 @@
 * [Example 4: Using Aliases](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example4.md)
 * [Example 5: Using Error Handlers](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example5.md)
 * [Example 6: Using Required Parameters](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example6.md)
+* [Example 7: Halting the Parser](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example7.md)
 
 ----
 ### Example 1 : Using the ParameterParser to parse simple parameters.

diff --git a/examples/Example2.md b/examples/Example2.md
@@ -5,6 +5,7 @@
 * [Example 4: Using Aliases](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example4.md)
 * [Example 5: Using Error Handlers](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example5.md)
 * [Example 6: Using Required Parameters](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example6.md)
+* [Example 7: Halting the Parser](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example7.md)
 
 ----
 ### Example 2 : Using ParameterCluster to parse more advanced parameters.

diff --git a/examples/Example3.md b/examples/Example3.md
@@ -5,6 +5,7 @@
 * [Example 4: Using Aliases](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example4.md)
 * [Example 5: Using Error Handlers](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example5.md)
 * [Example 6: Using Required Parameters](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example6.md)
+* [Example 7: Halting the Parser](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example7.md)
 
 ----
 ### Example 3 : Using ParameterCluster and the splat operator `...` (aka. Variadic Closures)

diff --git a/examples/Example4.md b/examples/Example4.md
@@ -5,6 +5,7 @@
 * Example 4: Using Aliases
 * [Example 5: Using Error Handlers](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example5.md)
 * [Example 6: Using Required Parameters](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example6.md)
+* [Example 7: Halting the Parser](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example7.md)
 
 ----
 ### Example 4 : Using aliases with ParameterClosures

diff --git a/examples/Example5.md b/examples/Example5.md
@@ -5,6 +5,7 @@
 * [Example 4: Using Aliases](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example4.md)
 * Example 5: Using Error Handlers
 * [Example 6: Using Required Parameters](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example6.md)
+* [Example 7: Halting the Parser](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example7.md)
 
 ----
 ### Example 5 : Using Error Handlers

diff --git a/examples/Example7.md b/examples/Example7.md
@@ -0,0 +1,76 @@
+## Index:
+* [Example 1: Using ParameterParser](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example1.md)
+* [Example 2: Using ParameterCluster](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example2.md)
+* [Example 3: Using Variadic Closures (...)](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example3.md)
+* [Example 4: Using Aliases](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example4.md)
+* [Example 5: Using Error Handlers](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example5.md)
+* [Example 6: Using Required Parameters](https://github.com/nathan-fiscaletti/parameterparser/blob/master/examples/Example6.md)
+* Example 7: Halting the Parser
+
+----
+### Example 6 : Using Required Parameters
+
+#### Usage: 
+    php Test.php -load Test -exec 'some code'
+#### Output: 
+    Halted By: load
+    Array
+    (
+        [load] => Test
+    )
+#### Code:
+```php
+// Create a new ParameterCluster.
+$parameters = new ParameterCluster;
+
+// Create out first parameter
+$loadClosure = parameter('-', 'load', function ($file) {
+    // This will return a value for the parameter, and 
+    // will then halt the ParameterParser.
+    return parameter_result_and_halt($file);
+
+    // This will return no value for the parameter
+    // but will halt the ParameterParser.
+    // return parameter_result_halt();
+
+    // This will simply return a value for the parameter.
+    // return parameter_result($file);
+
+    // This will also return a value for the parameter.
+    // return $file;
+});
+
+// Create a second parameter
+$execClosure = parameter('-', 'exec', function ($code) {
+    return $code;
+});
+
+// Use the ->addMany function to add multiple closures to the ParameterCluster.
+$parameters->addMany([
+    $loadClosure,
+    $execClosure
+]);
+
+// Create a ParameterParser using the ParameterCluster.
+$parameterParser = new ParameterParser($argv, $parameters);
+
+// Parse the arguments using the ParameterCluster.
+$results = $parameterParser->parse();
+
+// Check if the ParameterParser has been halted.
+if ($parameterParser->haltedBy() != null) {
+    echo 'Halted By: ';
+    // You can either use ->haltedBy() or ->haltedByName()
+    //     ->haltedBy()     : Will return a ParameterClosure object.
+    //     ->haltedByName() : Will return the name of the Parameter.
+    echo $parameterParser->haltedByName() . PHP_EOL;
+}
+
+// Validate the ParameterParser and if it's invalid, print the usage.
+if (! $parameterParser->isValid()) {
+    echo 'Usage: ' . $parameters->getFullUsage();
+    echo PHP_EOL;
+} else {
+    print_r($results);
+}
+```
diff --git a/src/ParameterParser/Functions.php b/src/ParameterParser/Functions.php
@@ -17,8 +17,12 @@
      *
      * @return \ParameterParser\ParameterClosure
      */
-    function parameter($prefix, $parameterName, \Closure $closure, $required = false)
-    {
+    function parameter(
+        $prefix,
+        $parameterName,
+        \Closure $closure,
+        $required = false
+    ) {
         return new \ParameterParser\ParameterClosure(
             $prefix,
             $parameterName,
@@ -27,3 +31,49 @@ function parameter($prefix, $parameterName, \Closure $closure, $required = false
         );
     }
 }
+
+if (! function_exists('parameter_result')) {
+    /**
+     * Create a new ParameterResult object and return it.
+     *
+     * @param  mixed $value
+     *
+     * @return \ParameterParser\ParameterResult
+     */
+    function parameter_result($value)
+    {
+        return new \ParameterParser\ParameterResult($value);
+    }
+}
+
+
+if (! function_exists('parameter_result_and_halt')) {
+    /**
+     * Create a new ParameterResult object and return it,
+     * once this is returned the parser will be halted.
+     *
+     * @param  mixed $value
+     *
+     * @return \ParameterParser\ParameterResult
+     */
+    function parameter_result_and_halt($value)
+    {
+        return new \ParameterParser\ParameterResult($value, true);
+    }
+}
+
+if (! function_exists('parameter_result_halt')) {
+    /**
+     * Create a new ParameterResult object that when
+     * returned will halt the parser.
+     *
+     * @return \ParameterParser\ParameterResult
+     */
+    function parameter_result_halt()
+    {
+        return new \ParameterParser\ParameterResult(
+            \ParameterParser\ParameterParser::HALT_PARSE,
+            true
+        );
+    }
+}
diff --git a/src/ParameterParser/ParameterClosure.php b/src/ParameterParser/ParameterClosure.php
@@ -64,8 +64,12 @@ class ParameterClosure
      * @param Closure $parameterClosure
      * @param bool    $required
      */
-    public function __construct($prefix, $parameterName, Closure $parameterClosure, $required = false)
-    {
+    public function __construct(
+        $prefix,
+        $parameterName,
+        Closure $parameterClosure,
+        $required = false
+    ) {
         $this->parameterName = $parameterName;
         $this->parameterClosure = $parameterClosure;
         $this->prefix = $prefix;

diff --git a/src/ParameterParser/ParameterParser.php b/src/ParameterParser/ParameterParser.php
@@ -7,6 +7,11 @@
 
 class ParameterParser
 {
+    /**
+     * The constant value that is used to halt the parser.
+     */
+    public const HALT_PARSE = "parameter_parser_halt_parser";
+
     /**
      * The array of arguments to use.
      *
@@ -35,6 +40,14 @@ class ParameterParser
      */
     private $errorHandler;
 
+    /**
+     * If a parameter halts the execution fot he parser,
+     * it will be stored here.
+     *
+     * @var string
+     */
+    private $haltedBy = null;
+
     /**
      * Construct the Parameter Parser using an array of arguments.
      *
@@ -88,6 +101,7 @@ public function parse(
             $parameter = $this->argv[$i];
             if ($this->prefixExists($parameter)) {
                 $closure = $this->getClosure($parameter);
+
                 if ($closure != null) {
                     $prefix = $this->getPrefix($parameter);
                     $closure_arguments = [];
@@ -112,6 +126,31 @@ public function parse(
                             $rFunction
                         );
                     }
+
+                    $result_key = substr(
+                        $parameter,
+                        strlen($prefix),
+                        strlen($parameter) - strlen($prefix)
+                    );
+                    $result = $results[$result_key];
+
+                    if (! $result instanceof ParameterResult) {
+                        if ($result == ParameterParser::HALT_PARSE) {
+                            $this->haltedBy = $this->getParameterClosure($parameter);
+                            unset($results[$result_key]);
+                            break;
+                        }
+                    } else {
+                        if ($result->shouldHalt()) {
+                            $this->haltedBy = $this->getParameterClosure($parameter);
+                            if ($result->isHaltOnly()) {
+                                unset($results[$result_key]);
+                            } else {
+                                $results[$result_key] = $result->getValue();    
+                            }
+                            break;
+                        }
+                    }
                 } else {
                     $this->respondDefault($i, $results, $parameter);
                 }
@@ -153,6 +192,32 @@ public function isValid()
         return $this->valid;
     }
 
+    /**
+     * Retrieves the parameter that halted the execution
+     * of the parser, if any. If the parser was not halted
+     * null will be returned.
+     *
+     * @return \ParameterParser\ParameterClosure
+     */
+    public function haltedBy()
+    {
+        return $this->haltedBy;
+    }
+
+     /**
+     * Retrieves name of the parameter that halted the execution
+     * of the parser, if any. If the parser was not halted
+     * null will be returned.
+     *
+     * @return \ParameterParser\ParameterClosure
+     */
+    public function haltedByName()
+    {
+        return ($this->haltedBy == null)
+            ? null
+            : $this->haltedBy->parameterName;
+    }
+
     /**
      * Validates the parameter list by verifying that it contains
      * all required parameters. Returns the ParameterClosure if a parameter
@@ -200,6 +265,8 @@ private function validateRequiredParameters()
      */
     private function initialize($argv, $parameterCluster)
     {
+        $this->valid = true;
+        $this->haltedBy = null;
         if ($parameterCluster != null) {
             $this->parameterCluster = $parameterCluster;
             if ($argv != null) {

diff --git a/src/ParameterParser/ParameterResult.php b/src/ParameterParser/ParameterResult.php
@@ -0,0 +1,64 @@
+<?php
+
+namespace ParameterParser;
+
+class ParameterResult
+{
+    /**
+     * Resulting value.
+     *
+     * @var mixed
+     */
+    private $value = null;
+
+    /**
+     * If set to true, the parser will be halted.
+     *
+     * @var boolean
+     */
+    private $shouldHalt = false;
+
+    /**
+     * Construct the parameter result with a value
+     * and a halt value.
+     *
+     * @param mixed $value
+     * @param bool  $halt
+     */
+    public function __construct($value, $halt = false)
+    {
+        $this->value = $value;
+        $this->shouldHalt = $halt;
+    }
+
+    /**
+     * Retrieve the value of the ParameterResult.
+     *
+     * @return mixed
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+
+    /**
+     * Check if this ParameterResult should ONLY halt the parser.
+     *
+     * @return bool
+     */
+    public function isHaltOnly()
+    {
+        return $this->value == ParameterParser::HALT_PARSE;
+    }
+
+    /**
+     * Check if apart of the result includes halting
+     * the parser.
+     *
+     * @return bool
+     */
+    public function shouldHalt()
+    {
+       return $this->shouldHalt;
+    }
+}