Author: Tobias Schlitt
Date: 2007-01-18 10:47:26 +0100 (Thu, 18 Jan 2007)
New Revision: 4521
Log:
- Added design and proof-of-concept implementation for feature request #8803:
[ConsoleTools] Support for user interaction through STDIN.
# Test cases will follow soon.
Added:
trunk/ConsoleTools/design/design-1.3.txt
trunk/ConsoleTools/src/dialog/
trunk/ConsoleTools/src/dialog/menu_dialog.php
trunk/ConsoleTools/src/dialog/question_dialog.php
trunk/ConsoleTools/src/dialog_viewer.php
trunk/ConsoleTools/src/exceptions/no_valid_dialog_result.php
trunk/ConsoleTools/src/interfaces/
trunk/ConsoleTools/src/interfaces/dialog.php
trunk/ConsoleTools/src/options/dialog.php
trunk/ConsoleTools/src/options/menu_dialog.php
trunk/ConsoleTools/src/options/question_dialog.php
Modified:
trunk/ConsoleTools/src/console_autoload.php
trunk/ConsoleTools/src/exceptions/invalid_output_target.php
Added: trunk/ConsoleTools/design/design-1.3.txt
===================================================================
--- trunk/ConsoleTools/design/design-1.3.txt 2007-01-17 11:04:59 UTC (rev
4520)
+++ trunk/ConsoleTools/design/design-1.3.txt 2007-01-18 09:47:26 UTC (rev
4521)
@@ -0,0 +1,220 @@
+eZ component: ConsoleTools, Design, 1.3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:Author: Tobias Schlitt
+:Revision: $Rev$
+:Date: $Date$
+:Status: Draft
+
+.. contents::
+
+Scope
+=====
+
+The scope of this document is to describe the enhancements of the ConsoleTools
+component for version 1.3 of the component.
+
+The ConsoleTools component so far provides only the possibility to interact
+with a user through console options and agruments. A `feature request`_ was
+filed with the need for another possibility of interaction with the user:
+Through STDIN.
+
+This document describes a new range of classes, which will be added to
+ConsoleTools, to fulfill this need.
+
+Design overview
+===============
+
+The following section gives a brief introduction of the concept behind this
+document.
+
+Clarification of terms
+----------------------
+
+User
+~~~~
+
+The "user" is the person using a program and interacting with it during
+runtime.
+
+Developer
+~~~~~~~~~
+
+In contrast to the "user", the term "developer" in this document refers to the
+person who creates a program, using the ConsoleTools component.
+
+Dialog
+~~~~~~
+
+The basic idea of a new mechanism to interact with the user through STDIN in
+this document is called a "dialog".
+
+Basic design
+-------------
+
+The core of the new feature decribed in this document is a dialog. The dialog
+is an object, must have the following capabilities:
+
+- To presents itself to the user on the command line
+- Requests a result (answer) from the user through STDIN.
+- Check if the result is valid for its purpose.
+- Returning the result to the
+
+A dialog is usually used in a loop, which displays the dialog again and again
+until it received a valid result.
+
+Class design
+============
+
+The following classes will realize the idea of dialogs in ConsoleTools.
+
+ezcConsoleDialog
+----------------
+
+This interface describes the external API, which is used in common to work with
+dialog objects. Each dialog class must implement this interface. The API looks
+as follows:
+
+__construct( ezcConsoleOutput $output, ezcConsoleDialogOptions $options )
+ The constructor of a dialog receives an instance of ezcConsoleOutput, which
+ it must use for presenting its output, when requested. In addition, it can
+ recieve an option object, which must be an instance or subclass instance of
+ ezcConsoleDialogOptions.
+hasValidResult()
+ This method must return a boolean value, which indicates, if the dialog
+ already received a result from the user, which is valid in its context.
+getResult()
+ After the hasValidResult() method returned true, this method will return the
+ value received from the dialog.
+display()
+ Using this method, the developer can instruct the dialog object to display
+ itself to the user. The dialog must use the instance of eczConsoleOutput it
+ received in the constructor for displaying.
+reset()
+ This method resets the dialog internally to the state it had directly after
+ construction, so that it can be reused by the developer.
+
+In addition to this interface, an implementation of ezcConsoleDialog can
+contain a set of static factory methods, which return a dialog in a
+preconfigured state.
+
+ezcConsoleDialogOptions
+-----------------------
+
+This is the base option class, which must be accepted by a dialog. It contains
+options, which must be valid for each dialog class. A dialog class may request,
+that the options it receives are instances of a subclass, if it expects
+additional options. Each of the options defined in ezcConsoleDialogOptions must
+also be available in this subclass. Every option defined must have a sensible
+default value, so that there is no need for the developer to change it.
+
+The base option class provides the following options:
+
+format
+ The name of the format this dialog uses to be displayed. The format
+ identifier must be defined in the ezcConsoleOutput instance submitted to the
+ constructor of the dialog.
+
+ezcConsoleDialogViewer
+----------------------
+
+The ezcConsoleDialogViewer class provides a set of static convenience methods
+that can be used by a developer that works with dialogs and by a developer that
+creates new dialogs. These methods are:
+
+displayDialog( ezcConsoleDialog $dialog )
+ This method is recommended to be used for displaying dialogs. It performs the
+ typical loop: Display the dialog over and over again until it received a
+ valid result. When this state is reached, it returns the dialogs value.
+readLine()
+ The readLine() method is commonly used in a dialog implementation to read a
+ line from standard in. It returns the input provided by a user, trimmed of
+ leading and trailing whitespaces.
+
+Dialog implementations
+======================
+
+The new feature set comes with a collection of basic dialog implementations,
+which will be described in this section.
+
+ezcConsoleQuestionDialog
+------------------------
+
+The ezcConsoleQuestionDialog is the most basic imaginable dialog. It asks the
+user a simply question and expects a free-form answer or a set of predefined
+answers. A typical output from an ezcConsoleQuestionDialog object could look
+like this: ::
+
+ Do you want to continue? (y/n)
+
+This dialog implementation provides a set of rudimentary options, which can be
+used to customize its appearance and enhance its capabilities. For this
+purpose, it comes with a custom options class ezcConsoleQuestionDialogOptions,
+that accepts the following options in addition to those provided by
+ezcConsoleDialogOptions:
+
+text
+ This option defines the main "question" text, displayed to the user.
+type
+ Using this option, a developer can request the dialog to check the result
+ provided by the user for a given format. The format is defined usin the
+ syntax of PHPs sprintf() function (better to say: sscanf()).
+validResults
+ If this option is set, it must contain an array of expected results for this
+ dialog. The dialog will then verify, that the received result is among this
+ set.
+defaultResult
+ This option can be used to define a default value, which is used by the
+ dialog, if the user does not provide any value at all (in other words: simply
+ hits <RETURN>).
+showResults
+ If this boolean option is set to true, the dialog will display the possible
+ result values behind the question text itself. If a default value is
+ provided, it will also indicate, which one this is. For example: ::
+
+ Do you want to continue? (y/n) [y]
+
+ While here "y" and "n" are valid results and "y" is the default result, which
+ is selected when simply skipping this question by hitting just <RETURN>.
+
+ezcConsoleMenuDialog
+--------------------
+
+The second dialog implementation shipped with ConsoleTools is the menu dialog,
+which is an enhanced version of the question dialog. The menu dialog will
+display an ordered set of options and let the user select one of these. A
+typical menu can look like this: ::
+
+ You can choose one of the following actions.
+
+ 1) Create something new
+ 2) Edit something
+ 3) Delete something
+ 4) Do something else
+
+ Please choose an action:
+
+The menu dialog also comes with its own set of options, the
+ezcConsoleMenuDialogOptions:
+
+text
+ The text displyed before the menu.
+entries
+ An array of strings, defining the possibilities shown in the menu.
+marker
+ The character used to devide the numbering of menu entries from their text
+ representation.
+markerSpace
+ The padding of whitespaces between the number and the text representation of
+ a menu entry.
+selectText
+ The text displayed after the menu to indicate to the user that he should make
+ a selection.
+
+
+
+..
+ Local Variables:
+ mode: rst
+ fill-column: 79
+ End:
+ vim: et syn=rst tw=79
Property changes on: trunk/ConsoleTools/design/design-1.3.txt
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/ConsoleTools/src/console_autoload.php
===================================================================
--- trunk/ConsoleTools/src/console_autoload.php 2007-01-17 11:04:59 UTC (rev
4520)
+++ trunk/ConsoleTools/src/console_autoload.php 2007-01-18 09:47:26 UTC (rev
4521)
@@ -47,6 +47,17 @@
'ezcConsoleOptionMissingValueException' =>
'ConsoleTools/exceptions/option_missing_value.php',
'ezcConsoleOptionNotExistsException' =>
'ConsoleTools/exceptions/option_not_exists.php',
'ezcConsoleOptionTooManyValuesException' =>
'ConsoleTools/exceptions/option_too_many_values.php',
+
+ 'ezcConsoleDialog' =>
'ConsoleTools/interfaces/dialog.php',
+ 'ezcConsoleDialogViewer' =>
'ConsoleTools/dialog_viewer.php',
+ 'ezcConsoleQuestionDialog' =>
'ConsoleTools/dialog/question_dialog.php',
+ 'ezcConsoleMenuDialog' =>
'ConsoleTools/dialog/menu_dialog.php',
+
+ 'ezcConsoleDialogOptions' =>
'ConsoleTools/options/dialog.php',
+ 'ezcConsoleQuestionDialogOptions' =>
'ConsoleTools/options/question_dialog.php',
+ 'ezcConsoleMenuDialogOptions' =>
'ConsoleTools/options/menu_dialog.php',
+
+ 'ezcConsoleNoValidDialogResultException' =>
'ConsoleTools/exceptions/no_valid_dialog_result.php',
);
?>
Added: trunk/ConsoleTools/src/dialog/menu_dialog.php
===================================================================
--- trunk/ConsoleTools/src/dialog/menu_dialog.php 2007-01-17 11:04:59 UTC
(rev 4520)
+++ trunk/ConsoleTools/src/dialog/menu_dialog.php 2007-01-18 09:47:26 UTC
(rev 4521)
@@ -0,0 +1,164 @@
+<?php
+
+/**
+ * Dialog class to ask a simple question.
+ *
+ * @package Framework
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @author
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+class ezcConsoleMenuDialog implements ezcConsoleDialog
+{
+
+ protected $result;
+
+ protected $properties = array(
+ "options" => null,
+ "output" => null,
+ );
+
+ /**
+ * Create a new question dialog.
+ *
+ * @param ezcConsoleOutput $output Output object.
+ * @return void
+ */
+ public function __construct( ezcConsoleOutput $output,
ezcConsoleMenuDialogOptions $options = null )
+ {
+ $this->output = $output;
+ $this->options = $options === null ? new ezcConsoleMenuDialogOptions()
: $options;
+ }
+
+ /**
+ * Returns if the dialog retrieved a valid result.
+ * Dialogs are displayed in a loop until they return true here.
+ *
+ * @return bool If a valid result was retrieved.
+ */
+ public function hasValidResult()
+ {
+ return ( $this->result !== null );
+ }
+
+ /**
+ * Returns the result retrieved.
+ * If no valid result was retreived, yet, this method should throw an
+ * ezcConsoleNoValidDialogResultException.
+ *
+ * @return mixed The retreived result.
+ */
+ public function getResult()
+ {
+ if ( $this->result === null )
+ {
+ throw new ezcConsoleNoValidDialogResultException();
+ }
+ return $this->result;
+ }
+
+ /**
+ * Show the dialog.
+ * Display the dialog and retreive the desired answer from the user.
+ *
+ * @return void
+ */
+ public function display()
+ {
+ $text = "{$this->options->text}\n";
+ $results = array();
+ foreach ( $this->options->entries as $key => $entry )
+ {
+ $text .= sprintf(
+ "%{$this->options->markerSpace}s{$this->options->marker} %s\n",
+ $key,
+ $entry
+ );
+ $results[] = $key;
+ }
+ $text .= "\n{$this->options->selectText}";
+
+ $question = new ezcConsoleQuestionDialog( $this->output );
+ $question->options->text = $text;
+ $question->options->validResults = $results;
+ $question->options->format = $this->options->format;
+ $question->display();
+
+ if ( $question->hasValidResult() )
+ {
+ $this->result = $question->getResult();
+ }
+ }
+
+ /**
+ * Reset the dialog.
+ *
+ * @return void
+ */
+ public function reset()
+ {
+ $this->result = null;
+ $this->options = new ezcConsoleMenuDialogOptions();
+ }
+
+ /**
+ * Property get access.
+ *
+ * @param string $propertyName
+ * @return void
+ * @ignore
+ */
+ public function __get( $propertyName )
+ {
+ if ( array_key_exists( $propertyName, $this->properties ) )
+ {
+ return $this->properties[$propertyName];
+ }
+ throw new ezcBasePropertyNotFoundException( $propertyName );
+ }
+
+ /**
+ * Property get access.
+ *
+ * @param string $propertyName Name of the property to set.
+ * @param string $propertyValue Vakue to set.
+ * @return void
+ * @ignore
+ */
+ public function __set( $propertyName, $propertyValue )
+ {
+ switch ( $propertyName )
+ {
+ case "options":
+ if ( ( $propertyValue instanceof ezcConsoleMenuDialogOptions )
=== false )
+ {
+ throw new ezcBaseValueException( $propertyName, get_class(
$propertyValue ), "instance of ezcConsoleMenuDialogOptions" );
+ }
+ break;
+ case "output":
+ if ( ( $propertyValue instanceof ezcConsoleOutput ) === false )
+ {
+ throw new ezcBaseValueException( $propertyName, get_class(
$propertyValue ), "instance of ezcConsoleOutput" );
+ }
+ break;
+ default:
+ throw new ezcBasePropertyNotFoundException( $propertyName );
+ }
+ $this->properties[$propertyName] = $propertyValue;
+ }
+
+ /**
+ * Property isset access.
+ *
+ * @param string $propertyName Name of the property to check.
+ * @return void
+ * @ignore
+ */
+ public function __isset( $propertyName )
+ {
+ return array_key_exists( $propertyName, $this->properties );
+ }
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/dialog/menu_dialog.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: trunk/ConsoleTools/src/dialog/question_dialog.php
===================================================================
--- trunk/ConsoleTools/src/dialog/question_dialog.php 2007-01-17 11:04:59 UTC
(rev 4520)
+++ trunk/ConsoleTools/src/dialog/question_dialog.php 2007-01-18 09:47:26 UTC
(rev 4521)
@@ -0,0 +1,168 @@
+<?php
+
+/**
+ * Dialog class to ask a simple question.
+ *
+ * @package Framework
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @author
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+class ezcConsoleQuestionDialog implements ezcConsoleDialog
+{
+
+ protected $result;
+
+ protected $properties = array(
+ "options" => null,
+ "output" => null,
+ );
+
+ /**
+ * Create a new question dialog.
+ *
+ * @param ezcConsoleOutput $output Output object.
+ * @return void
+ */
+ public function __construct( ezcConsoleOutput $output,
ezcConsoleQuestionDialogOptions $options = null )
+ {
+ $this->output = $output;
+ $this->options = $options === null ? new
ezcConsoleQuestionDialogOptions() : $options;
+ }
+
+ /**
+ * Returns if the dialog retrieved a valid result.
+ * Dialogs are displayed in a loop until they return true here.
+ *
+ * @return bool If a valid result was retrieved.
+ */
+ public function hasValidResult()
+ {
+ return ( $this->result !== null );
+ }
+
+ /**
+ * Returns the result retrieved.
+ * If no valid result was retreived, yet, this method should throw an
+ * ezcConsoleNoValidDialogResultException.
+ *
+ * @return mixed The retreived result.
+ */
+ public function getResult()
+ {
+ if ( $this->result === null )
+ {
+ throw new ezcConsoleNoValidDialogResultException();
+ }
+ return $this->result;
+ }
+
+ /**
+ * Show the dialog.
+ * Display the dialog and retreive the desired answer from the user.
+ *
+ * @return void
+ */
+ public function display()
+ {
+ $this->output->outputText(
+ $this->options->text .
+ ( ( $this->options->showResults === true )
+ ? " (" . implode( "/", $this->options->validResults ) . ")" .
+ ( ( $this->options->defaultResult !== null )
+ ? " [{$this->options->defaultResult}]"
+ : "" ) .
+ " "
+ : " " ),
+ $this->options->format
+ );
+ $line = ezcConsoleDialogViewer::readLine();
+ $line = ( $line === "" && $this->options->defaultResult !== null ) ?
$this->options->defaultResult : $line;
+ if ( ( $resCount = sscanf( $line, $this->options->type, $res ) ) === 1
+ && ( is_array( $this->options->validResults ) === false
+ || in_array( $res, $this->options->validResults )
+ )
+ )
+ {
+ $this->result = $res;
+ }
+ }
+
+ /**
+ * Reset the result in this question.
+ *
+ * @return void
+ */
+ public function reset()
+ {
+ $this->result = null;
+ $this->options = new ezcConsoleQuestionDialogOptions();
+ }
+
+ /**
+ * Property get access.
+ *
+ * @param string $propertyName
+ * @return void
+ */
+ public function __get( $propertyName )
+ {
+ if ( array_key_exists( $propertyName, $this->properties ) )
+ {
+ return $this->properties[$propertyName];
+ }
+ throw new ezcBasePropertyNotFoundException( $propertyName );
+ }
+
+ /**
+ * Property get access.
+ *
+ * @param string $propertyName Name of the property to set.
+ * @param string $propertyValue Value to set.
+ * @return void
+ */
+ public function __set( $propertyName, $propertyValue )
+ {
+ switch ( $propertyName )
+ {
+ case "options":
+ if ( ( $propertyValue instanceof
ezcConsoleQuestionDialogOptions ) === false )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ get_class( $propertyValue ),
+ "instance of ezcConsoleQuestionDialogOptions"
+ );
+ }
+ break;
+ case "output":
+ if ( ( $propertyValue instanceof ezcConsoleOutput ) === false )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ get_class( $propertyValue ),
+ "instance of ezcConsoleOutput"
+ );
+ }
+ break;
+ default:
+ throw new ezcBasePropertyNotFoundException( $propertyName );
+ }
+ $this->properties[$propertyName] = $propertyValue;
+ }
+
+ /**
+ * Property isset access.
+ *
+ * @param string $propertyName Name of the property to check.
+ * @return void
+ * @ignore
+ */
+ public function __isset( $propertyName )
+ {
+ return array_key_exists( $propertyName, $this->properties );
+ }
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/dialog/question_dialog.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: trunk/ConsoleTools/src/dialog_viewer.php
===================================================================
--- trunk/ConsoleTools/src/dialog_viewer.php 2007-01-17 11:04:59 UTC (rev
4520)
+++ trunk/ConsoleTools/src/dialog_viewer.php 2007-01-18 09:47:26 UTC (rev
4521)
@@ -0,0 +1,44 @@
+<?php
+
+/**
+ * Manager class to work with ezcConsoleDialog objects.
+ *
+ * @package Framework
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @author
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+class ezcConsoleDialogViewer
+{
+ /**
+ * Displays a dialog and returns a valid result from it.
+ * This methods displays a dialog in a loop, until it received a valid
+ * result from it and returns this result.
+ *
+ * @param ezcConsoleDialogDialog $dialog The dialog to display.
+ * @return mixed The result from this dialog.
+ */
+ public static function displayDialog( ezcConsoleDialog $dialog )
+ {
+ do
+ {
+ $dialog->display();
+ }
+ while ( $dialog->hasValidResult() === false );
+ return $dialog->getResult();
+ }
+
+ /**
+ * Returns a line from STDIN.
+ * The returned line is fully trimmed.
+ *
+ * @return string
+ */
+ public static function readLine()
+ {
+ return ( trim( fgets( STDIN ) ) );
+ }
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/dialog_viewer.php
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/ConsoleTools/src/exceptions/invalid_output_target.php
===================================================================
--- trunk/ConsoleTools/src/exceptions/invalid_output_target.php 2007-01-17
11:04:59 UTC (rev 4520)
+++ trunk/ConsoleTools/src/exceptions/invalid_output_target.php 2007-01-18
09:47:26 UTC (rev 4521)
@@ -1,6 +1,6 @@
<?php
/**
- * File containing the ezcConsoleInvalidOutputTargetException.
+ * File containing the ezcConsoleNoValidDialogResultException.
*
* @package ConsoleTools
* @version //autogen//
@@ -9,17 +9,18 @@
*/
/**
- * Thrown if a given target [EMAIL PROTECTED] ezcConsoleOutputFormat} could
not be opened.
+ * Thrown if [EMAIL PROTECTED] ezcConsoleDialog::getResult()} is called before
a valid
+ * result was received.
*
* @package ConsoleTools
* @version //autogen//
*/
-class ezcConsoleInvalidOutputTargetException extends ezcConsoleException
+class ezcConsoleNoValidDialogResultException extends ezcConsoleException
{
- public function __construct( $target )
+ public function __construct()
{
- parent::__construct( "The target '{$target}' could not be opened for
writing." );
+ parent::__construct( "The dialog did not receive a valid result, yet."
);
}
}
Added: trunk/ConsoleTools/src/exceptions/no_valid_dialog_result.php
===================================================================
--- trunk/ConsoleTools/src/exceptions/no_valid_dialog_result.php
2007-01-17 11:04:59 UTC (rev 4520)
+++ trunk/ConsoleTools/src/exceptions/no_valid_dialog_result.php
2007-01-18 09:47:26 UTC (rev 4521)
@@ -0,0 +1,27 @@
+<?php
+/**
+ * File containing the ezcConsoleNoValidDialogResultException.
+ *
+ * @package ConsoleTools
+ * @version //autogen//
+ * @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved.
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+
+/**
+ * Thrown if [EMAIL PROTECTED] ezcConsoleDialog::getResult()} is called before
a valid
+ * result was received.
+ *
+ * @package ConsoleTools
+ * @version //autogen//
+ */
+class ezcConsoleNoValidDialogResultException extends ezcConsoleException
+{
+
+ public function __construct()
+ {
+ parent::__construct( "The dialog did not receive a valid result, yet."
);
+ }
+
+}
+?>
Property changes on:
trunk/ConsoleTools/src/exceptions/no_valid_dialog_result.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: trunk/ConsoleTools/src/interfaces/dialog.php
===================================================================
--- trunk/ConsoleTools/src/interfaces/dialog.php 2007-01-17 11:04:59 UTC
(rev 4520)
+++ trunk/ConsoleTools/src/interfaces/dialog.php 2007-01-18 09:47:26 UTC
(rev 4521)
@@ -0,0 +1,65 @@
+<?php
+
+/**
+ * Interface that every console dialog class must implement.
+ * Console dialogs can either be used on their own or using the
+ * [EMAIL PROTECTED] ezcConsoleDialogViewer} (recommended). In the dialog
viewer, a dialog
+ * is instanciated and displayed in a loop, until it receives a valid result
+ * value.
+ *
+ * @package ConsoleTools
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+interface ezcConsoleDialog
+{
+
+ const TYPE_STRING = "%s";
+ const TYPE_INT = "%d";
+ const TYPE_FLOAT = "%f";
+
+ /**
+ * Create a new dialog object.
+ * This method retrieves an ezcConsoleOutput object for printing its
+ * content.
+ *
+ * @param ezcConsoleOutput $output Output object.
+ * @return void
+ */
+ public function __construct( ezcConsoleOutput $output,
ezcConsoleDialogOptions $options = null );
+
+ /**
+ * Returns if the dialog retrieved a valid result.
+ * Dialogs are displayed in a loop until they return true here.
+ *
+ * @return bool If a valid result was retrieved.
+ */
+ public function hasValidResult();
+
+ /**
+ * Returns the result retrieved.
+ * If no valid result was retreived, yet, this method should throw an
+ * ezcDialogNoValidResultException.
+ *
+ * @return mixed The retreived result.
+ */
+ public function getResult();
+
+ /**
+ * Show the dialog.
+ * Display the dialog and retreive the desired answer from the user.
+ *
+ * @return void
+ */
+ public function display();
+
+ /**
+ * Resets the dialog to its initial state.
+ *
+ * @return void
+ */
+ public function reset();
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/interfaces/dialog.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: trunk/ConsoleTools/src/options/dialog.php
===================================================================
--- trunk/ConsoleTools/src/options/dialog.php 2007-01-17 11:04:59 UTC (rev
4520)
+++ trunk/ConsoleTools/src/options/dialog.php 2007-01-18 09:47:26 UTC (rev
4521)
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * Basic options class for ezcConsoleDialog implementations.
+ *
+ * @package ConsoleTools
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+class ezcConsoleDialogOptions extends ezcBaseOptions
+{
+ /**
+ * Properties.
+ *
+ * @var array(string=>mixed)
+ */
+ protected $properties = array(
+ "format" => "default",
+ );
+
+ /**
+ * Property set access.
+ *
+ * @param string $propertyName
+ * @param string $propertyValue
+ * @ignore
+ * @return void
+ */
+ public function __set( $propertyName, $propertyValue )
+ {
+ switch ( $propertyName )
+ {
+ case "format":
+ if ( !is_string( $propertyValue ) || strlen( $propertyValue )
< 1 )
+ {
+ throw new ezcBaseValueException( $propertyName,
$propertyValue, "string, length > 0" );
+ }
+ break;
+ default:
+ throw new ezcBasePropertyNotFoundException( $propertyName );
+ }
+ $this->properties[$propertyName] = $propertyValue;
+ }
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/options/dialog.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: trunk/ConsoleTools/src/options/menu_dialog.php
===================================================================
--- trunk/ConsoleTools/src/options/menu_dialog.php 2007-01-17 11:04:59 UTC
(rev 4520)
+++ trunk/ConsoleTools/src/options/menu_dialog.php 2007-01-18 09:47:26 UTC
(rev 4521)
@@ -0,0 +1,96 @@
+<?php
+
+/**
+ * Basic options class for ezcConsoleDialog implementations.
+ *
+ * @package ConsoleTools
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+class ezcConsoleMenuDialogOptions extends ezcConsoleDialogOptions
+{
+ /**
+ * Properties.
+ *
+ * @var array(string=>mixed)
+ */
+ protected $properties = array(
+ "format" => "default",
+ "text" => "Please choose:",
+ "entries" => array(),
+ "marker" => ")",
+ "markerSpace" => 4,
+ "selectText" => "Selection: ",
+ );
+
+ /**
+ * Property set access.
+ *
+ * @param string $propertyName
+ * @param string $propertyValue
+ * @ignore
+ * @return void
+ */
+ public function __set( $propertyName, $propertyValue )
+ {
+ switch ( $propertyName )
+ {
+ case "text":
+ if ( is_string( $propertyValue ) === false || strlen(
$propertyValue ) < 1 )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "string, length > 0"
+ );
+ }
+ break;
+ case "entries":
+ if ( is_array( $propertyValue ) === false )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "array"
+ );
+ }
+ break;
+ case "marker":
+ if ( is_string( $propertyValue ) === false || strlen(
$propertyValue ) < 1 )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "string, length > 0"
+ );
+ }
+ break;
+ case "markerSpace":
+ if ( is_int( $propertyValue ) === false || $propertyValue < 1 )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "int > 0"
+ );
+ }
+ break;
+ case "selectText":
+ if ( is_string( $propertyValue ) === false )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "string"
+ );
+ }
+ break;
+ default:
+ parent::__set( $propertyName, $propertyValue );
+ }
+ $this->properties[$propertyName] = $propertyValue;
+ }
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/options/menu_dialog.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: trunk/ConsoleTools/src/options/question_dialog.php
===================================================================
--- trunk/ConsoleTools/src/options/question_dialog.php 2007-01-17 11:04:59 UTC
(rev 4520)
+++ trunk/ConsoleTools/src/options/question_dialog.php 2007-01-18 09:47:26 UTC
(rev 4521)
@@ -0,0 +1,84 @@
+<?php
+
+/**
+ * Basic options class for ezcConsoleDialog implementations.
+ *
+ * @package ConsoleTools
+ * @version //autogen//
+ * @copyright Copyright (C) 2006 eZ systems as. All rights reserved.
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ */
+class ezcConsoleQuestionDialogOptions extends ezcConsoleDialogOptions
+{
+ /**
+ * Properties.
+ *
+ * @var array(string=>mixed)
+ */
+ protected $properties = array(
+ "format" => "default",
+ "text" => "Please enter a value: ",
+ "type" => ezcConsoleDialog::TYPE_STRING,
+ "validResults" => null,
+ "defaultResult" => null,
+ "showResults" => false,
+ );
+
+ /**
+ * Property set access.
+ *
+ * @param string $propertyName
+ * @param string $propertyValue
+ * @ignore
+ * @return void
+ */
+ public function __set( $propertyName, $propertyValue )
+ {
+ switch ( $propertyName )
+ {
+ case "text":
+ if ( is_string( $propertyValue ) === false || strlen(
$propertyValue ) < 1 )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "string, length > 0"
+ );
+ }
+ break;
+ case "type":
+ if ( is_string( $propertyValue ) === false )
+ {
+ throw new ezcBaseValueException(
+ $propertyName,
+ $propertyValue,
+ "one of ezcConsoleDialog::TYPE_STRING,
ezcConsoleDialog::TYPE_INT, ezcConsoleDialog::TYPE_FLOAT or custom sscanf()
format"
+ );
+ }
+ break;
+ case "validResults":
+ if ( $propertyValue !== null && is_array( $propertyValue ) ===
false )
+ {
+ throw new ezcBaseValueException( $propertyName,
$propertyValue, "null or array(int=>string)" );
+ }
+ break;
+ case "showResults":
+ if ( is_bool( $propertyValue ) === false )
+ {
+ throw new ezcBaseValueException( $propertyName,
$propertyValue, "bool" );
+ }
+ break;
+ case "defaultResult":
+ if ( is_scalar( $propertyValue ) === false )
+ {
+ throw new ezcBaseValueException( $propertyName,
$propertyValue, "scalar" );
+ }
+ break;
+ default:
+ parent::__set( $propertyName, $propertyValue );
+ }
+ $this->properties[$propertyName] = $propertyValue;
+ }
+}
+
+?>
Property changes on: trunk/ConsoleTools/src/options/question_dialog.php
___________________________________________________________________
Name: svn:eol-style
+ native
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
