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

Source for file question_dialog.php

Documentation is available at question_dialog.php

  1. <?php
  2. /**
  3.  * File containing the ezcConsoleQuestionDialog 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.  * Dialog class to ask a simple question.
  30.  * This dialog outputs a certain string to the user and requests a line of
  31.  * input. This is commonly used to ask questions like "Do you want to proceed?"
  32.  * and retrieve an answer like "y" for yes or "n" for no.
  33.  *
  34.  * The behaviour of this dialog is defined by an instance of
  35.  * {@link ezcConsoleQuestionDialogOptions}.
  36.  * 
  37.  * @package ConsoleTools
  38.  * @version //autogen//
  39.  *
  40.  * @property ezcConsoleQuestionDialogOptions $options 
  41.  *            Options for the dialog.
  42.  * @property ezcConsoleOutput $output 
  43.  *            Output object for displaying the dialog.
  44.  */
  45. class ezcConsoleQuestionDialog implements ezcConsoleDialog
  46. {
  47.  
  48.     /**
  49.      * Dialog result
  50.      * 
  51.      * @var mixed 
  52.      */
  53.     protected $result;
  54.  
  55.     /**
  56.      * Properties
  57.      * 
  58.      * @var array 
  59.      */
  60.     protected $properties = array(
  61.         "options"   => null,
  62.         "output"    => null,
  63.     );
  64.  
  65.     /**
  66.      * Creates a new question dialog.
  67.      * Creates a new menu dialog to be displayed to the user. All behaviour is
  68.      * defined through the $options parameter. The $output parameter is used to
  69.      * display the dialog in the {@link display()} method.
  70.      * 
  71.      * @param ezcConsoleOutput $output                 Output object.
  72.      * @param ezcConsoleQuestionDialogOptions $options Options.
  73.      * @return void 
  74.      */
  75.     public function __constructezcConsoleOutput $outputezcConsoleQuestionDialogOptions $options null )
  76.     {
  77.         $this->output  $output;
  78.         $this->options $options === null new ezcConsoleQuestionDialogOptions($options;
  79.     }
  80.  
  81.     /**
  82.      * Returns if the dialog retrieved a valid result.
  83.      * If a valid result has already been received, this method returns true,
  84.      * otherwise false.
  85.      * 
  86.      * @return bool If a valid result was retrieved.
  87.      */
  88.     public function hasValidResult()
  89.     {
  90.         return $this->result !== null;
  91.     }
  92.  
  93.     /**
  94.      * Returns the result retrieved.
  95.      * If no valid result was retreived, yet, this method should throw an
  96.      * ezcConsoleNoValidDialogResultException.
  97.      * 
  98.      * If no valid result was retreived, yet, this method throws an
  99.      * ezcConsoleNoValidDialogResultException. Use {@link hasValidResult()} to
  100.      * avoid this.
  101.      * 
  102.      * @return mixed The retreived result.
  103.      *
  104.      * @throws ezcDialogNoValidResultException
  105.      *          if this method is called without a valid result being retrieved
  106.      *          by the object. Use {@link hasValidResult()} to avoid this
  107.      *          exception.
  108.      */
  109.     public function getResult()
  110.     {
  111.         if $this->result === null )
  112.         {
  113.             throw new ezcConsoleNoValidDialogResultException();
  114.         }
  115.         return $this->result;
  116.     }
  117.  
  118.     /**
  119.      * Displays the dialog and retreives a value from the user.
  120.      * Displays the dialog and retreives the desired answer from the user. If
  121.      * the a valid result is retrieved, it can be obtained using {@link }
  122.      * getResult()}. The method {@link hasValidResult()} can be used to check
  123.      * if a valid result is available.
  124.      * 
  125.      * @return void 
  126.      * @throws ezcConsoleDialogAbortException
  127.      *          if the user closes STDIN using <CTRL>-D.
  128.      */
  129.     public function display()
  130.     {
  131.         $this->reset();
  132.  
  133.         $this->output->outputText(
  134.             $this->options->text $this->options->showResults === true " " $this->options->validator->getResultString("" " ",
  135.             $this->options->format
  136.         );
  137.         $result $this->options->validator->fixupezcConsoleDialogViewer::readLine() );
  138.         if $this->options->validator->validate$result ) )
  139.         {
  140.             $this->result = $result;
  141.         }
  142.     }
  143.  
  144.     /**
  145.      * Reset the dialog.
  146.      * Resets a possibly received result and all changes made to the dialog
  147.      * during {@link display()}. After that, the dialog can be re-used. All
  148.      * option values are kept.
  149.      * 
  150.      * @return void 
  151.      */
  152.     public function reset()
  153.     {
  154.         $this->result = null;
  155.     }
  156.  
  157.     /**
  158.      * Returns a ready to use yes/no question dialog.
  159.      * Returns a question dialog, which requests the answers "y" for "yes" or
  160.      * "n" for "no" from the user. The answer is converted to lower-case.
  161.      *
  162.      * <code>
  163.      * // Would you like to proceed? (y/n)
  164.      * $dialog = ezcConsoleDialog( $out, "Would you like to proceed?" );
  165.      *
  166.      * // Would you like to proceed? (y/n) [n]
  167.      * $dialog = ezcConsoleDialog( $out, "Would you like to proceed?", "n" );
  168.      * </code>
  169.      * 
  170.      * @param ezcConsoleOutput $out  Output object.
  171.      * @param string $questionString Question string.
  172.      * @param string $default        "y" or "n", if default value is desired.
  173.      * @return ezcConsoleQuestionDialog The created dialog.
  174.      */
  175.     public static function YesNoQuestionezcConsoleOutput $out$questionString$default null )
  176.     {
  177.         $opts new ezcConsoleQuestionDialogOptions();
  178.         $opts->text $questionString;
  179.         $opts->showResults true;
  180.         $opts->validator new ezcConsoleQuestionDialogMappingValidator(
  181.             array"y""n" ),
  182.             $default,
  183.             ezcConsoleQuestionDialogCollectionValidator::CONVERT_LOWER,
  184.             array(
  185.                 'yes' => 'y',
  186.                 'no'  => 'n',
  187.             )
  188.         );
  189.  
  190.         return new ezcConsoleQuestionDialog$out$opts );
  191.     }
  192.  
  193.     /**
  194.      * Property read access.
  195.      *
  196.      * @throws ezcBasePropertyNotFoundException
  197.      *          If the the desired property is not found.
  198.      * 
  199.      * @param string $propertyName Name of the property.
  200.      * @return mixed Value of the property or null.
  201.      * @ignore
  202.      */
  203.     public function __get$propertyName )
  204.     {
  205.         if array_key_exists$propertyName$this->properties ) )
  206.         {
  207.             return $this->properties[$propertyName];
  208.         }
  209.         throw new ezcBasePropertyNotFoundException$propertyName );
  210.     }
  211.  
  212.     /**
  213.      * Property write access.
  214.      * 
  215.      * @param string $propertyName Name of the property.
  216.      * @param mixed $propertyValue The value for the property.
  217.      *
  218.      * @throws ezcBasePropertyPermissionException
  219.      *          If the property you try to access is read-only.
  220.      * @throws ezcBasePropertyNotFoundException
  221.      *          If the the desired property is not found.
  222.      * @ignore
  223.      */
  224.     public function __set$propertyName$propertyValue )
  225.     {
  226.         switch $propertyName )
  227.         {
  228.             case "options":
  229.                 if ( ( $propertyValue instanceof ezcConsoleQuestionDialogOptions === false )
  230.                 {
  231.                     throw new ezcBaseValueException(
  232.                         $propertyName,
  233.                         is_object$propertyValue get_class$propertyValue gettype$propertyValue ) ),
  234.                         "instance of ezcConsoleQuestionDialogOptions"
  235.                     );
  236.                 }
  237.                 break;
  238.             case "output":
  239.                 if ( ( $propertyValue instanceof ezcConsoleOutput === false )
  240.                 {
  241.                     throw new ezcBaseValueException(
  242.                         $propertyName,
  243.                         is_object$propertyValue get_class$propertyValue gettype$propertyValue ) ),
  244.                         "instance of ezcConsoleOutput"
  245.                     );
  246.                 }
  247.                 break;
  248.             default:
  249.                 throw new ezcBasePropertyNotFoundException$propertyName );
  250.         }
  251.         $this->properties[$propertyName$propertyValue;
  252.     }
  253.  
  254.     /**
  255.      * Property isset access.
  256.      * 
  257.      * @param string $propertyName Name of the property to check.
  258.      * @return bool If the property exists or not.
  259.      * @ignore
  260.      */
  261.     public function __isset$propertyName )
  262.     {
  263.         return array_key_exists$propertyName$this->properties );
  264.     }
  265. }
  266.  
  267. ?>
Documentation generated by phpDocumentor 1.4.3