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

Source for file standard.php

Documentation is available at standard.php

  1. <?php
  2. /**
  3.  * File containing the ezcConsoleInputStandardHelpGenerator 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.  * Standard help generator for {@link ezcConsoleInput}.
  29.  *
  30.  * Standard help generation as {@link ezcConsoleInput} did from the start.
  31.  *
  32.  * @package ConsoleTools
  33.  * @version //autogen//
  34.  *
  35.  * @access private
  36.  * @TODO Verify interface and make it public to replace the validation in
  37.  *        {@link ezcConsoleInput}.
  38.  */
  39. class ezcConsoleInputStandardHelpGenerator implements ezcConsoleInputHelpGenerator
  40. {
  41.     /**
  42.      * Input object.
  43.      * 
  44.      * @var ezcConsoleInput 
  45.      */
  46.     private $input;
  47.  
  48.     /**
  49.      * Creates a new help generator.
  50.      *
  51.      * Creates a new help generator for the given $input.
  52.      * 
  53.      * @param ezcConsoleInput $input 
  54.      */
  55.     public function __constructezcConsoleInput $input )
  56.     {
  57.         $this->input $input;
  58.     }
  59.  
  60.     /**
  61.      * Generates help information as a multidimensional array.
  62.      *
  63.      * This method generates a tabular view on the help information of a
  64.      * program. The returned array has the following structure:
  65.      *
  66.      * <code>
  67.      * <?php
  68.      * array(
  69.      *  0 => array(
  70.      *      0 => '<option short/long name>',
  71.      *      1 => '<option help, depending on the $long parameter>'
  72.      *  ),
  73.      *  1 => array(
  74.      *      0 => '<option short name> / <option long name>',
  75.      *      1 => '<option help, depending on the $long parameter>'
  76.      *  ),
  77.      *  // ...
  78.      * );
  79.      * ?>
  80.      * </code>
  81.      *
  82.      * Each row of the array represents the help information for a single option.
  83.      * The first cell of a row contains the option name (maybe short, long or
  84.      * both), the second cell contains the help text of the option.
  85.      *
  86.      * The returned array is used by {@link ezcConsoleInput} for different
  87.      * purposes.
  88.      * For example, the user can retrieve it raw through the
  89.      * {@link ezcConsoleInput::getHelp()} method, he can generate a help
  90.      * {@link ezcConsoleTable} through {@link ezcConsoleInput::getHelpTable()}
  91.      * are can generate a printable help text through {@link }
  92.      * ezcConsoleInput::getHelpText()}.
  93.      *
  94.      * The parameter $long defines if the long or short help text of the
  95.      * options should be used in the second cell of the returned array. The
  96.      * $optionsFilter parameter is used to restrict the generated help to a certain
  97.      * sub-set of options. It consists of an array of short or long names of
  98.      * the options to include.
  99.      * 
  100.      * @param bool $long 
  101.      * @param array(string) $optionsFilter 
  102.      * @return array(array(string)) 
  103.      */
  104.     public function generateUngroupedOptionHelp$long falsearray $optionsFilter null )
  105.     {
  106.         $help array();
  107.         foreach $this->input->getOptions(as $id => $param )
  108.         {
  109.             if $optionsFilter === null || in_array$param->short$optionsFilter || in_array$param->long$optionsFilter ) )
  110.             {
  111.                 $help[$this->getOptionHelpRow$long$param );
  112.             }
  113.         }
  114.         return $help;
  115.     }
  116.  
  117.     /**
  118.      * Generates help information as a multidimensional array, grouped in categories.
  119.      *
  120.      * This method behaves similar to {@link generateUngroupedOptionHelp()}. In
  121.      * contrast to the latter one, this method returns an array with 1
  122.      * dimension more, grouping options into categories. The $groups parameter
  123.      * defines the categories to generate. Each category may contain an
  124.      * arbitrary number of options, options might occur in different
  125.      * categories.
  126.      *
  127.      * The returned array has the follorwing format:
  128.      *
  129.      * <code>
  130.      * <?php
  131.      * array(
  132.      *  '<category name>' => array(
  133.      *      0 => array(
  134.      *          0 => '<option short/long name>',
  135.      *          1 => '<option help, depending on the $long parameter>'
  136.      *      ),
  137.      *      1 => array(
  138.      *          0 => '<option short name> / <option long name>',
  139.      *          1 => '<option help, depending on the $long parameter>'
  140.      *      ),
  141.      *      // ...
  142.      *  ),
  143.      *  '<category name>' => array(
  144.      *      // ...
  145.      *  ),
  146.      *  // ...
  147.      * );
  148.      * ?>
  149.      * </code>
  150.      *
  151.      * The $long parameter, as in {@link generateUngroupedOptionHelp()}
  152.      * determines if the options short or long help is to be used. The
  153.      * $params array can in addition be used to determine if a parameter
  154.      * is displayed at all. If $optionsFilter is submitted and is not null,
  155.      * only options listed in it will be shown in the help at all.
  156.      * 
  157.      * @param array(string=>array(string)) $groups 
  158.      * @param bool $long 
  159.      * @param array(string) $params 
  160.      * @return array(string=>array(array(string))) 
  161.      */
  162.     public function generateGroupedOptionHelparray $groups$long falsearray $optionsFilter null )
  163.     {
  164.         $help array();
  165.         foreach $groups as $groupName => $groupOptions )
  166.         {
  167.             foreach $groupOptions as $optionName )
  168.             {
  169.                 $option $this->input->getOption$optionName );
  170.                 if $optionsFilter === null || in_array$option->short$optionsFilter || in_array$option->long$optionsFilter ) )
  171.                 {
  172.                     $help[$groupName][$this->getOptionHelpRow(
  173.                         $long,
  174.                         $option
  175.                     );
  176.                 }
  177.             }
  178.         }
  179.         return $help;
  180.     }
  181.  
  182.     /**
  183.      * Generates help information as a multi-dimensonal array for the given $argumentDefinition.
  184.      *
  185.      * This method generates a tabular help information for the given
  186.      * $argumentDefinition in the following format:
  187.      *
  188.      * <code>
  189.      * <?php
  190.      * array(
  191.      *  0 => array(
  192.      *      0 => '<argument synopsis>',
  193.      *      1 => '<argument help text>'
  194.      *  ),
  195.      *  1 => array(
  196.      *      0 => '<argument synopsis>',
  197.      *      1 => '<argument help text>'
  198.      *  ),
  199.      *  // ...
  200.      * )
  201.      * ?>
  202.      * </code>
  203.      * 
  204.      * The $long parameter defines if the long of short help text should be
  205.      * used.
  206.      *
  207.      * @param bool $long 
  208.      * @return array(array(string)) 
  209.      */
  210.     public function generateArgumentHelp$long false )
  211.     {
  212.         $help array();
  213.         if $this->input->argumentDefinition !== null )
  214.         {
  215.             foreach $this->input->argumentDefinition as $arg )
  216.             {
  217.                 $argSynopsis "<%s:%s>";
  218.                 switch $arg->type )
  219.                 {
  220.                     case ezcConsoleInput::TYPE_INT:
  221.                         $type "int";
  222.                         break;
  223.                     case ezcConsoleInput::TYPE_STRING:
  224.                         $type "string";
  225.                         break;
  226.                 }
  227.                 $argSynopsis sprintf$argSynopsis$type$arg->name );
  228.                 $help[$long === true )
  229.                         ? array
  230.                             $argSynopsis,
  231.                             $arg->longhelp $arg->mandatory === false 
  232.                                                ? ' (optional' $arg->default !== null 
  233.                                                                   ? ', default = ' is_array$arg->default 
  234.                                                                                        ? "'" implode"' '"$arg->default "'" 
  235.                                                                                        : "'$arg->default'
  236.                                                                                      )
  237.                                                                   : '' 
  238.                                                                 ')'
  239.                                                : ''
  240.                                              )
  241.                           )
  242.                         : array$argSynopsis$arg->shorthelp );
  243.             }
  244.         }
  245.         return $help;
  246.     }
  247.  
  248.     /**
  249.      * Creates 1 text row for displaying options help.
  250.      *
  251.      * Returns a single array entry for the {@link getOptionHelpRow()} method.
  252.      *
  253.      * @param bool $long 
  254.      * @param ezcConsoleOption $param 
  255.      * @return string 
  256.      */
  257.     private function getOptionHelpRow$longezcConsoleOption $param )
  258.     {
  259.         return array
  260.             $param->short !== "" '-' $param->short ' / ' "" '--' $param->long,
  261.             $long == false $param->shorthelp $param->longhelp,
  262.         );
  263.     }
  264.  
  265.     /**
  266.      * Generates a command line synopsis for the options and arguments.
  267.      *
  268.      * This method generates a synopsis string that lists the options and
  269.      * parameters available, indicating their usage. If $optionsFilter is
  270.      * submitted, only the options named in this array (short or long variant)
  271.      * will be included in the synopsis.
  272.      *
  273.      * @param array(string) $optionsFilter 
  274.      * @return string 
  275.      */
  276.     public function generateSynopsisarray $optionFilter null )
  277.     {
  278.         $usedOptions array'short' => array()'long' => array() );
  279.         $allowsArgs true;
  280.         $synopsis '$ ' isset$argv && sizeof$argv $argv[0$_SERVER['argv'][0' ';
  281.         foreach $this->input->getOptions(as $option )
  282.         {
  283.             if $optionFilter === null || in_array$option->short$optionFilter ||  in_array$option->long$optionFilter ) )
  284.             {
  285.                 $synopsis .= $this->createOptionSynopsis$option$usedOptions$allowsArgs );
  286.             }
  287.         }
  288.         if $this->input->argumentDefinition === null )
  289.         {
  290.             // Old handling
  291.             $synopsis .= " [[--] <args>]";
  292.         }
  293.         else
  294.         {
  295.             $synopsis .= "[--] " $this->createArgumentsSynopsis();
  296.         }
  297.         return $synopsis;
  298.     }
  299.  
  300.     /**
  301.      * Returns the synopsis string for a single option and its dependencies.
  302.      *
  303.      * This method returns a part of the program synopsis, specifically for a
  304.      * certain parameter. The method recursively adds depending parameters up
  305.      * to the 2nd depth level to the synopsis. The second parameter is used
  306.      * to store the short names of all options that have already been used in
  307.      * the synopsis (to avoid adding an option twice). The 3rd parameter
  308.      * determines the actual deps in the option dependency recursion to
  309.      * terminate that after 2 recursions.
  310.      * 
  311.      * @param ezcConsoleOption $option        The option to include.
  312.      * @param array(string) $usedOptions Array of used option short names.
  313.      * @param int $depth                      Current recursion depth.
  314.      * @return string The synopsis for this parameter.
  315.      */
  316.     private function createOptionSynopsisezcConsoleOption $option&$usedOptions$depth )
  317.     {
  318.         $synopsis '';
  319.  
  320.         // Break after a nesting level of 2
  321.         if $depth++ > || in_array$option->short$usedOptions['short'&& in_array$option->long$usedOptions['long') ) ) return $synopsis;
  322.         
  323.         $usedOptions['short'][$option->short;
  324.         $usedOptions['long'][]  $option->long;
  325.         
  326.         $synopsis .= $option->short !== "" "-{$option->short}"--{$option->long}";
  327.  
  328.         if isset$option->default ) )
  329.         {
  330.             $synopsis .= " " $option->type === ezcConsoleInput::TYPE_STRING '"' '' $option->default $option->type === ezcConsoleInput::TYPE_STRING '"' '' );
  331.         }
  332.         else if $option->type !== ezcConsoleInput::TYPE_NONE )
  333.         {
  334.             $synopsis .= " ";
  335.             switch $option->type )
  336.             {
  337.                 case ezcConsoleInput::TYPE_STRING:
  338.                     $synopsis .= "<string>";
  339.                     break;
  340.                 case ezcConsoleInput::TYPE_INT:
  341.                     $synopsis .= "<int>";
  342.                     break;
  343.             }
  344.         }
  345.  
  346.         foreach $option->getDependencies(as $rule )
  347.         {
  348.             $deeperSynopsis $this->createOptionSynopsis$rule->option$usedOptions$depth );
  349.             $synopsis .= iconv_strlentrim$deeperSynopsis )'UTF-8' 
  350.                 ? ' ' $deeperSynopsis
  351.                 : ''
  352.             );
  353.         }
  354.         
  355.         if $option->arguments === false )
  356.         {
  357.             $allowsArgs false;
  358.         }
  359.         
  360.         // Make the whole thing optional?
  361.         if $option->mandatory === false )
  362.         {
  363.             $synopsis "[$synopsis]";
  364.         }
  365.  
  366.         return $synopsis ' ';
  367.     }
  368.  
  369.     /**
  370.      * Generate synopsis for arguments.
  371.      * 
  372.      * @return string The synopsis string.
  373.      */
  374.     private function createArgumentsSynopsis()
  375.     {
  376.         $mandatory true;
  377.         $synopsises array();
  378.         foreach $this->input->argumentDefinition as $arg )
  379.         {
  380.             $argSynopsis "";
  381.             if $arg->mandatory === false )
  382.             {
  383.                 $mandatory false;
  384.             }
  385.             $argSynopsis .= "<%s:%s>";
  386.             switch $arg->type )
  387.             {
  388.                 case ezcConsoleInput::TYPE_INT:
  389.                     $type "int";
  390.                     break;
  391.                 case ezcConsoleInput::TYPE_STRING:
  392.                     $type "string";
  393.                     break;
  394.             }
  395.             $argSynopsis sprintf$argSynopsis$type$arg->name );
  396.             $synopsises[$mandatory === false "[$argSynopsis]$argSynopsis;
  397.             if $arg->multiple === true )
  398.             {
  399.                 $synopsises["[$argSynopsis ...]";
  400.                 break;
  401.             }
  402.         }
  403.         return implode" "$synopsises );
  404.     }
  405. }
  406.  
  407. ?>
Documentation generated by phpDocumentor 1.4.3