Apache Zeta Components Manual :: File Source for option.php

Source for file option.php

Documentation is available at option.php

  1. <?php
  2. /**
  3.  * File containing the ezcConsoleOption class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @package ConsoleTools
  23.  * @version //autogentag//
  24.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  25.  * @filesource
  26.  */
  27.  
  28. /**
  29.  * Objects of this class store data about a single option for ezcConsoleInput.
  30.  *
  31.  * This class represents a single command line option, which can be handled by
  32.  * the ezcConsoleInput class. This classes only purpose is the storage of
  33.  * the parameter data, the handling of options and arguments is done by the
  34.  * class {@link ezcConsoleInput}.
  35.  * 
  36.  * @property-read string $short 
  37.  *                 Short name of the parameter without '-' (eg. 'f').
  38.  * @property-read string $long 
  39.  *                 Long name of the parameter without '--' (eg. 'file').
  40.  * @property int $type 
  41.  *            Value type of this parameter, default is ezcConsoleInput::TYPE_NONE.
  42.  *            See {@link ezcConsoleInput::TYPE_NONE},
  43.  *            {@link ezcConsoleInput::TYPE_INT} and
  44.  *            {@link ezcConsoleInput::TYPE_STRING}.
  45.  * @property mixed $default 
  46.  *            Default value if the parameter is submitted without value.  If a
  47.  *            parameter is eg. of type ezcConsoleInput::TYPE_STRING and
  48.  *            therefore expects a value when being submitted, it may be
  49.  *            submitted without a value and automatically get the default value
  50.  *            specified here.
  51.  * @property bool $multiple 
  52.  *            Is the submission of multiple instances of this parameters
  53.  *            allowed?
  54.  * @property string $shorthelp 
  55.  *            Short help text. Usually displayed when showing parameter help
  56.  *            overview.
  57.  * @property string $longhelp 
  58.  *            Long help text. Usually displayed when showing parameter detailed
  59.  *            help.
  60.  * @property bool $arguments 
  61.  *            Whether arguments to the program are allowed, when this parameter
  62.  *            is submitted.
  63.  * @property bool $mandatory 
  64.  *            Whether a parameter is mandatory to be set.  If this flag is true,
  65.  *            the parameter must be submitted whenever the program is run.
  66.  * @property bool $isHelpOption 
  67.  *            Whether a parameter is a help option.  If this flag is true, and
  68.  *            the parameter is set, all options marked as mandatory may be
  69.  *            skipped.
  70.  *
  71.  * @package ConsoleTools
  72.  * @version //autogen//
  73.  */
  74. {
  75.     /**
  76.      * Container to hold the properties
  77.      *
  78.      * @var array(string=>mixed) 
  79.      */
  80.     protected $properties;
  81.  
  82.     /**
  83.      * Dependency rules of this parameter.
  84.      * 
  85.      * @see ezcConsoleOption::addDependency()
  86.      * @see ezcConsoleOption::removeDependency()
  87.      * @see ezcConsoleOption::hasDependency()
  88.      * @see ezcConsoleOption::getDependencies()
  89.      * @see ezcConsoleOption::resetDependencies()
  90.      * 
  91.      * @var array(string=>ezcConsoleParamemterRule) 
  92.      */
  93.     protected $dependencies = array();
  94.  
  95.     /**
  96.      * Exclusion rules of this parameter.
  97.      * 
  98.      * @see ezcConsoleOption::addExclusion()
  99.      * @see ezcConsoleOption::removeExclusion()
  100.      * @see ezcConsoleOption::hasExclusion()
  101.      * @see ezcConsoleOption::getExclusions()
  102.      * @see ezcConsoleOption::resetExclusions()
  103.      * 
  104.      * @var array(string=>ezcConsoleParamemterRule) 
  105.      */
  106.     protected $exclusions = array();
  107.  
  108.     /**
  109.      * The value the parameter was assigned to when being submitted.
  110.      * Boolean false indicates the parameter was not submitted, boolean
  111.      * true means the parameter was submitted, but did not have a value.
  112.      * In any other case, this caries the submitted value.
  113.      * 
  114.      * @var mixed 
  115.      */
  116.     public $value = false;
  117.  
  118.     /**
  119.      * Create a new parameter struct.
  120.      * Creates a new basic parameter struct with the base information "$short"
  121.      * (the short name of the parameter) and "$long" (the long version). You
  122.      * simply apply these parameters as strings (without '-' or '--'). So
  123.      *
  124.      * <code>
  125.      * $param = new ezcConsoleOption( 'f', 'file' );
  126.      * </code>
  127.      *
  128.      * will result in a parameter that can be accessed using
  129.      * 
  130.      * <code>
  131.      * $ mytool -f
  132.      * </code>
  133.      *
  134.      * or
  135.      * 
  136.      * <code>
  137.      * $ mytool --file
  138.      * </code>
  139.      * .
  140.      *
  141.      * The newly created parameter contains only it's 2 names and each other
  142.      * attribute is set to it's default value. You can simply manipulate
  143.      * those attributes by accessing them directly.
  144.      * 
  145.      * @param string $short      Short name of the parameter without '-' (eg. 'f').
  146.      * @param string $long       Long name of the parameter without '--' (eg. 'file').
  147.      * @param int $type          Value type of the parameter. One of ezcConsoleInput::TYPE_*.
  148.      * @param mixed $default     Default value the parameter holds if not submitted.
  149.      * @param bool $multiple     If the parameter may be submitted multiple times.
  150.      * @param string $shorthelp  Short help text.
  151.      * @param string $longhelp   Long help text.
  152.      * @param array(ezcConsoleOptionRule) $dependencies Dependency rules.
  153.      * @param array(ezcConsoleOptionRule) $exclusions   Exclusion rules.
  154.      * @param bool $arguments    Whether supplying arguments is allowed when this parameter is set.
  155.      * @param bool $mandatory    Whether the parameter must be always submitted.
  156.      * @param bool $isHelpOption Indicates that the given parameter is a help
  157.      *                            option. If a help option is set, all rule
  158.      *                            checking is skipped (dependency/exclusion/
  159.      *                            mandatory).
  160.      *
  161.      * @throws ezcConsoleInvalidOptionNameException If the option names start with a "-"
  162.      *                                               sign or contain whitespaces.
  163.      */
  164.     public function __construct
  165.         $short ''
  166.         $long
  167.         $type ezcConsoleInput::TYPE_NONE
  168.         $default null
  169.         $multiple false,
  170.         $shorthelp 'No help available.',
  171.         $longhelp 'Sorry, there is no help text available for this parameter.'
  172.         array $dependencies array(),
  173.         array $exclusions array()
  174.         $arguments true,
  175.         $mandatory false,
  176.         $isHelpOption false
  177.     )
  178.     {
  179.         $this->properties['short''';
  180.         $this->properties['long''';
  181.         $this->properties['arguments'$arguments;
  182.  
  183.         if !self::validateOptionName$short ) )
  184.         {
  185.             throw new ezcConsoleInvalidOptionNameException$short );
  186.         }
  187.         $this->properties['short'$short;
  188.         
  189.         if !self::validateOptionName$long ) )
  190.         {
  191.             throw new ezcConsoleInvalidOptionNameException$long );
  192.         }
  193.         $this->properties['long'$long;
  194.         
  195.         $this->__set"type",      $type         !== null $type      ezcConsoleInput::TYPE_NONE  );
  196.         $this->__set"multiple",  $multiple     !== null $multiple  false  );
  197.         $this->__set"default",   $default      !== null $default   null );
  198.         $this->__set"shorthelp"$shorthelp    !== null $shorthelp 'No help available.' );
  199.         $this->__set"longhelp",  $longhelp     !== null $longhelp  'Sorry, there is no help text available for this parameter.' );
  200.         
  201.         $dependencies    $dependencies !== null && is_array$dependencies $dependencies array();
  202.         foreach $dependencies as $dep )
  203.         {
  204.             $this->addDependency$dep );
  205.         }
  206.         
  207.         $exclusions $exclusions !== null && is_array$exclusions $exclusions array();
  208.         foreach $exclusions as $exc )
  209.         {
  210.             $this->addExclusion$exc );
  211.         }
  212.  
  213.         $this->__set"mandatory",    $mandatory !== null $mandatory false );
  214.         $this->__set"isHelpOption"$isHelpOption !== null $isHelpOption false );
  215.     }
  216.  
  217.     /**
  218.      * Add a new dependency for a parameter.
  219.      * This registeres a new dependency rule with the parameter. If you try
  220.      * to add an already registered rule it will simply be ignored. Else,
  221.      * the submitted rule will be added to the parameter as a dependency.
  222.      *
  223.      * @param ezcConsoleOptionRule $rule The rule to add.
  224.      * @return void 
  225.      */
  226.     public function addDependencyezcConsoleOptionRule $rule )
  227.     {
  228.         foreach $this->dependencies as $existRule )
  229.         {
  230.             if $rule == $existRule )
  231.             {
  232.                 return;
  233.             }
  234.         }
  235.         $this->dependencies[$rule;
  236.     }
  237.     
  238.     /**
  239.      * Remove a dependency rule from a parameter.
  240.      * This removes a given rule from a parameter, if it exists. If the rule is
  241.      * not registered with the parameter, the method call will simply be ignored.
  242.      * 
  243.      * @param ezcConsoleOptionRule $rule The rule to be removed.
  244.      * @return void 
  245.      */
  246.     public function removeDependencyezcConsoleOptionRule $rule )
  247.     {
  248.         foreach $this->dependencies as $id => $existRule )
  249.         {
  250.             if $rule == $existRule )
  251.             {
  252.                 unset$this->dependencies[$id);
  253.             }
  254.         }
  255.     }
  256.     
  257.     /**
  258.      * Remove all dependency rule referring to a parameter.
  259.      * This removes all dependency rules from a parameter, that refer to as specific
  260.      * parameter. If no rule is registered with this parameter as reference, the
  261.      * method call will simply be ignored.
  262.      * 
  263.      * @param ezcConsoleOption $param The param to be check for rules.
  264.      * @return void 
  265.      */
  266.     public function removeAllDependenciesezcConsoleOption $param )
  267.     {
  268.         foreach $this->dependencies as $id => $rule )
  269.         {
  270.             if $rule->option == $param )
  271.             {
  272.                 unset$this->dependencies[$id);
  273.             }
  274.         }
  275.     }
  276.     
  277.     /**
  278.      * Returns if a dependency to the given option exists.
  279.      * Returns true if a dependency rule to the given option is registered,
  280.      * otherwise false.
  281.      * 
  282.      * @param ezcConsoleOption $param The param to check if a dependency exists to.
  283.      * @return bool True if rule is registered, otherwise false.
  284.      */
  285.     public function hasDependencyezcConsoleOption $param )
  286.     {
  287.         foreach $this->dependencies as $id => $rule )
  288.         {
  289.             if $rule->option == $param )
  290.             {
  291.                 return true;
  292.             }
  293.         }
  294.         return false;
  295.     }
  296.     
  297.     /**
  298.      * Returns the dependency rules registered with this parameter.
  299.      * Returns an array of registered dependencies.
  300.      *
  301.      * For example:
  302.      * <code>
  303.      * array(
  304.      *      0 => ezcConsoleOptionRule,
  305.      *      1 => ezcConsoleOptionRule,
  306.      *      2 => ezcConsoleOptionRule,
  307.      * );
  308.      * </code>
  309.      * 
  310.      * @return array(ezcConsoleOptionRule) Dependency definition.
  311.      */
  312.     public function getDependencies()
  313.     {
  314.         return $this->dependencies;
  315.     }
  316.  
  317.     /**
  318.      * Reset existing dependency rules.
  319.      * Deletes all registered dependency rules from the option definition.
  320.      * 
  321.      * @return void 
  322.      */
  323.     public function resetDependencies(
  324.     {
  325.         $this->dependencies = array();
  326.     }
  327.  
  328.     /**
  329.      * Add a new exclusion for an option.
  330.      * This registeres a new exclusion rule with the option. If you try
  331.      * to add an already registered rule it will simply be ignored. Else,
  332.      * the submitted rule will be added to the option as a exclusion.
  333.      *
  334.      * @param ezcConsoleOptionRule $rule The rule to add.
  335.      * @return void 
  336.      */
  337.     public function addExclusionezcConsoleOptionRule $rule )
  338.     {
  339.         foreach $this->exclusions as $existRule )
  340.         {
  341.             if $rule == $existRule )
  342.             {
  343.                 return;
  344.             }
  345.         }
  346.         $this->exclusions[$rule;
  347.     }
  348.     
  349.     /**
  350.      * Remove a exclusion rule from a option.
  351.      * This removes a given rule from a option, if it exists. If the rule is
  352.      * not registered with the option, the method call will simply be ignored.
  353.      * 
  354.      * @param ezcConsoleOptionRule $rule The rule to be removed.
  355.      * @return void 
  356.      */
  357.     public function removeExclusionezcConsoleOptionRule $rule )
  358.     {
  359.         foreach $this->exclusions as $id => $existRule )
  360.         {
  361.             if $rule == $existRule )
  362.             {
  363.                 unset$this->exclusions[$id);
  364.             }
  365.         }
  366.     }
  367.     
  368.     /**
  369.      * Remove all exclusion rule referring to a option.
  370.      * This removes all exclusion rules from a option, that refer to as specific
  371.      * option. If no rule is registered with this option as reference, the
  372.      * method call will simply be ignored.
  373.      * 
  374.      * @param ezcConsoleOption $param The option to remove rule for.
  375.      * @return void 
  376.      */
  377.     public function removeAllExclusionsezcConsoleOption $param )
  378.     {
  379.         foreach $this->exclusions as $id => $rule )
  380.         {
  381.             if $rule->option == $param )
  382.             {
  383.                 unset$this->exclusions[$id);
  384.             }
  385.         }
  386.     }
  387.     
  388.     /**
  389.      * Returns if a given exclusion rule is registered with the option.
  390.      * Returns true if a exclusion rule to the given option is registered,
  391.      * otherwise false.
  392.      * 
  393.      * @param ezcConsoleOption $param The param to check if exclusions exist for.
  394.      * @return bool True if rule is registered, otherwise false.
  395.      */
  396.     public function hasExclusionezcConsoleOption $param )
  397.     {
  398.         foreach $this->exclusions as $id => $rule )
  399.         {
  400.             if $rule->option == $param )
  401.             {
  402.                 return true;
  403.             }
  404.         }
  405.         return false;
  406.     }
  407.     
  408.     /**
  409.      * Returns the exclusion rules registered with this parameter.
  410.      * Returns an array of registered exclusions.
  411.      *
  412.      * For example:
  413.      * <code>
  414.      * array(
  415.      *      0 => ezcConsoleOptionRule,
  416.      *      1 => ezcConsoleOptionRule,
  417.      *      2 => ezcConsoleOptionRule,
  418.      * );
  419.      * </code>
  420.      * 
  421.      * @return array(ezcConsoleOptionRule) Exclusions definition.
  422.      */
  423.     public function getExclusions()
  424.     {
  425.         return $this->exclusions;
  426.     }
  427.  
  428.     /**
  429.      * Reset existing exclusion rules.
  430.      * Deletes all registered exclusion rules from the option definition.
  431.      *
  432.      * @return void 
  433.      */
  434.     public function resetExclusions(
  435.     {
  436.         $this->exclusions = array();
  437.     }
  438.     
  439.     /**
  440.      * Property read access.
  441.      * Provides read access to the properties of the object.
  442.      * 
  443.      * @param string $key The name of the property.
  444.      * @return mixed The value if property exists and isset, otherwise null.
  445.      * @ignore
  446.      */
  447.     public function __get$key )
  448.     {
  449.         switch $key  )
  450.         {
  451.             case 'short':
  452.             case 'long':
  453.             case 'type':
  454.             case 'default':
  455.             case 'multiple':
  456.             case 'shorthelp':
  457.             case 'longhelp':
  458.             case 'arguments':
  459.             case 'isHelpOption':
  460.             case 'mandatory':
  461.                 return $this->properties[$key];
  462.             case 'dependencies':
  463.             default:
  464.                 throw new ezcBasePropertyNotFoundException$key );
  465.         }
  466.     }
  467.  
  468.     /**
  469.      * Property write access.
  470.      * 
  471.      * @param string $key Name of the property.
  472.      * @param mixed $val  The value for the property.
  473.      *
  474.      * @throws ezcBasePropertyPermissionException
  475.      *          If the property you try to access is read-only.
  476.      * @throws ezcBasePropertyNotFoundException
  477.      *          If the the desired property is not found.
  478.      * @ignore
  479.      */
  480.     public function __set$key$val )
  481.     {
  482.         switch $key )
  483.         {
  484.             case 'type':
  485.                 if $val !== ezcConsoleInput::TYPE_NONE 
  486.                      && $val !== ezcConsoleInput::TYPE_INT 
  487.                      && $val !== ezcConsoleInput::TYPE_STRING )
  488.                 {
  489.                     throw new ezcBaseValueException
  490.                         $key,  
  491.                         $val
  492.                         'ezcConsoleInput::TYPE_STRING, ezcConsoleInput::TYPE_INT or ezcConsoleInput::TYPE_NONE' 
  493.                     );
  494.                 }
  495.                 break;
  496.             case 'default':
  497.                 if ( ( is_scalar$val === false && $val !== null ) )
  498.                 {
  499.                     // Newly allow arrays, if multiple is true
  500.                     if $this->multiple === true && is_array$val === true )
  501.                     {
  502.                         break;
  503.                     }
  504.                     throw new ezcBaseValueException$key$val'a string or a number, if multiple == true also an array' );
  505.                 }
  506.                 break;
  507.             case 'multiple':
  508.                 if !is_bool$val ) )
  509.                 {
  510.                     throw new ezcBaseValueException$key$val'bool' );
  511.                 }
  512.                 break;
  513.             case 'shorthelp':
  514.                 if !is_string$val ) )
  515.                 {
  516.                     throw new ezcBaseValueException$key$val'string' );
  517.                 }
  518.                 break;
  519.             case 'longhelp':
  520.                 if !is_string$val ) )
  521.                 {
  522.                     throw new ezcBaseValueException$key$val'string' );
  523.                 }
  524.                 break;
  525.             case 'arguments':
  526.                 if !is_bool$val ) )
  527.                 {
  528.                     throw new ezcBaseValueException$key$val'bool' );
  529.                 }
  530.                 break;
  531.             case 'mandatory':
  532.                 if !is_bool$val ) )
  533.                 {
  534.                     throw new ezcBaseValueException$key$val'bool' );
  535.                 }
  536.                 break;
  537.             case 'isHelpOption':
  538.                 if !is_bool$val ) )
  539.                 {
  540.                     throw new ezcBaseValueException$key$val'bool' );
  541.                 }
  542.                 break;
  543.             case 'long':
  544.             case 'short':
  545.                 throw new ezcBasePropertyPermissionException$keyezcBasePropertyPermissionException::READ );
  546.                 break;
  547.             default:
  548.                 throw new ezcBasePropertyNotFoundException$key );
  549.                 break;
  550.         }
  551.         $this->properties[$key$val;
  552.     }
  553.  
  554.     /**
  555.      * Property isset access.
  556.      * 
  557.      * @param string $key Name of the property.
  558.      * @return bool True is the property is set, otherwise false.
  559.      * @ignore
  560.      */
  561.     public function __isset$key )
  562.     {
  563.         switch $key  )
  564.         {
  565.             case 'short':
  566.             case 'long':
  567.             case 'type':
  568.             case 'default':
  569.             case 'multiple':
  570.             case 'shorthelp':
  571.             case 'longhelp':
  572.             case 'arguments':
  573.             case 'isHelpOption':
  574.             case 'mandatory':
  575.                 return $this->properties[$key!== null );
  576.         }
  577.         return false;
  578.     }
  579.  
  580.     /**
  581.      * Returns if a given name if valid for use as a parameter name a parameter.
  582.      * Checks if a given parameter name is generally valid for use. It checks a)
  583.      * that the name does not start with '-' or '--' and b) if it contains
  584.      * whitespaces. Note, that this method does not check any conflicts with already
  585.      * used parameter names.
  586.      * 
  587.      * @param string $name The name to check.
  588.      * @return bool True if the name is valid, otherwise false.
  589.      */
  590.     public static function validateOptionName$name )
  591.     {
  592.         if substr$name0=== '-' || strpos$name' ' !== false )
  593.         {
  594.             return false;
  595.         }
  596.         return true;
  597.     }
  598. }
  599.  
  600. ?>
Documentation generated by phpDocumentor 1.4.3