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

Source for file input_help_generator.php

Documentation is available at input_help_generator.php

  1. <?php
  2. /**
  3.  * File containing the ezcConsoleInputHelpGenerator interface.
  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.  * Interface for help generators used in ezcConsoleInput.
  30.  *
  31.  * An instance of a class implementing this interface is used in {@link }
  32.  * ezcConsoleInput} to generate the help information.
  33.  *
  34.  * @package ConsoleTools
  35.  * @version //autogen//
  36.  *
  37.  * @access private
  38.  * @TODO Verify interface and make it public to replace the validation in
  39.  *        {@link ezcConsoleInput}.
  40.  */
  41. interface ezcConsoleInputHelpGenerator
  42. {
  43.     /**
  44.      * Creates a new help generator.
  45.      *
  46.      * Creates a new help generator for the given $input.
  47.      * 
  48.      * @param ezcConsoleInput $input 
  49.      */
  50.     public function __constructezcConsoleInput $input );
  51.  
  52.     /**
  53.      * Generates help information as a multidimensional array.
  54.      *
  55.      * This method generates a tabular view on the help information of a
  56.      * program. The returned array has the following structure:
  57.      *
  58.      * <code>
  59.      * <?php
  60.      * array(
  61.      *  0 => array(
  62.      *      0 => '<option short/long name>',
  63.      *      1 => '<option help, depending on the $long parameter>'
  64.      *  ),
  65.      *  1 => array(
  66.      *      0 => '<option short name> / <option long name>',
  67.      *      1 => '<option help, depending on the $long parameter>'
  68.      *  ),
  69.      *  // ...
  70.      * );
  71.      * ?>
  72.      * </code>
  73.      *
  74.      * Each row of the array represents the help information for a single option.
  75.      * The first cell of a row contains the option name (maybe short, long or
  76.      * both), the second cell contains the help text of the option.
  77.      *
  78.      * The returned array is used by {@link ezcConsoleInput} for different
  79.      * purposes.
  80.      * For example, the user can retrieve it raw through the
  81.      * {@link ezcConsoleInput::getHelp()} method, he can generate a help
  82.      * {@link ezcConsoleTable} through {@link ezcConsoleInput::getHelpTable()}
  83.      * are can generate a printable help text through {@link }
  84.      * ezcConsoleInput::getHelpText()}.
  85.      *
  86.      * The parameter $long defines if the long or short help text of the
  87.      * options should be used in the second cell of the returned array. The
  88.      * $optionsFilter parameter is used to restrict the generated help to a certain
  89.      * sub-set of options. It consists of an array of short or long names of
  90.      * the options to include.
  91.      * 
  92.      * @param bool $long 
  93.      * @param array(string) $optionsFilter 
  94.      * @return array(array(string)) 
  95.      */
  96.     public function generateUngroupedOptionHelp$long falsearray $optionsFilter null );
  97.  
  98.     /**
  99. /**
  100.      * Generates help information as a multidimensional array, grouped in categories.
  101.      *
  102.      * This method behaves similar to {@link generateUngroupedOptionHelp()}. In
  103.      * contrast to the latter one, this method returns an array with 1
  104.      * dimension more, grouping options into categories. The $groups parameter
  105.      * defines the categories to generate. Each category may contain an
  106.      * arbitrary number of options, options might occur in different
  107.      * categories.
  108.      *
  109.      * The returned array has the follorwing format:
  110.      *
  111.      * <code>
  112.      * <?php
  113.      * array(
  114.      *  '<category name>' => array(
  115.      *      0 => array(
  116.      *          0 => '<option short/long name>',
  117.      *          1 => '<option help, depending on the $long parameter>'
  118.      *      ),
  119.      *      1 => array(
  120.      *          0 => '<option short name> / <option long name>',
  121.      *          1 => '<option help, depending on the $long parameter>'
  122.      *      ),
  123.      *      // ...
  124.      *  ),
  125.      *  '<category name>' => array(
  126.      *      // ...
  127.      *  ),
  128.      *  // ...
  129.      * );
  130.      * ?>
  131.      * </code>
  132.      *
  133.      * The $long parameter, as in {@link generateUngroupedOptionHelp()}
  134.      * determines if the options short or long help is to be used. The
  135.      * $params array can in addition be used to determine if a parameter
  136.      * is displayed at all. If $optionsFilter is submitted and is not null,
  137.      * only options listed in it will be shown in the help at all.
  138.      * 
  139.      * @param array(string=>array(string)) $groups 
  140.      * @param bool $long 
  141.      * @param array(string) $params 
  142.      * @return array(string=>array(array(string))) 
  143.      */
  144.     public function generateGroupedOptionHelparray $groups$long falsearray $optionsFilter null );
  145.  
  146.     /**
  147. /**
  148.      * Generates help information as a multi-dimensonal array for the given $argumentDefinition.
  149.      *
  150.      * This method generates a tabular help information for the given
  151.      * $argumentDefinition in the following format:
  152.      *
  153.      * <code>
  154.      * <?php
  155.      * array(
  156.      *  0 => array(
  157.      *      0 => '<argument synopsis>',
  158.      *      1 => '<argument help text>'
  159.      *  ),
  160.      *  1 => array(
  161.      *      0 => '<argument synopsis>',
  162.      *      1 => '<argument help text>'
  163.      *  ),
  164.      *  // ...
  165.      * )
  166.      * ?>
  167.      * </code>
  168.      *
  169.      * The $long parameter defines if the long of short help text should be
  170.      * used.
  171.      * 
  172.      * @param bool $long 
  173.      * @return array(array(string)) 
  174.      */
  175.     public function generateArgumentHelp$long false );
  176.  
  177.     /**
  178.      * Generates a command line synopsis for the options and arguments.
  179.      *
  180.      * This method generates a synopsis string that lists the options and
  181.      * parameters available, indicating their usage.
  182.      *
  183.      * @return string 
  184.      */
  185.     public function generateSynopsisarray $optionFilter null );
  186. }
  187.  
  188. ?>
Documentation generated by phpDocumentor 1.4.3