Author: Tobias Schlitt
Date: 2007-01-25 10:07:31 +0100 (Thu, 25 Jan 2007)
New Revision: 4568

Log:
- Updated regarding the discussion about result validation on the list.

Modified:
   trunk/ConsoleTools/design/design-1.3.txt

Modified: trunk/ConsoleTools/design/design-1.3.txt
===================================================================
--- trunk/ConsoleTools/design/design-1.3.txt    2007-01-25 09:04:41 UTC (rev 
4567)
+++ trunk/ConsoleTools/design/design-1.3.txt    2007-01-25 09:07:31 UTC (rev 
4568)
@@ -14,7 +14,7 @@
 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
+with a user through console options and arguments. A `feature request`_ was
 filed with the need for another possibility of interaction with the user:
 Through STDIN.
 
@@ -51,13 +51,13 @@
 Basic design
 -------------
 
-The core of the new feature decribed in this document is a dialog. The dialog
+The core of the new feature described 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 
+- Validate the result for its purpose.
+- Returning the result to the developer.
 
 A dialog is usually used in a loop, which displays the dialog again and again
 until it received a valid result.
@@ -77,7 +77,7 @@
 __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
+  receive 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
@@ -95,7 +95,8 @@
 
 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.
+pre-configured state (for example a standard yes/no question, where only the
+text needs to be set).
 
 ezcConsoleDialogOptions
 -----------------------
@@ -130,6 +131,23 @@
   line from standard in. It returns the input provided by a user, trimmed of
   leading and trailing whitespaces.
 
+ezcConsoleDialogValidator
+-------------------------
+
+The ezcConsoleValidator interface provides signatures for methods that can be 
used
+by a dialog to validate the result it retrieved. The validator is configured by
+the user and submitted to the dialog via an option (if a dialog supports this
+mechanism).
+
+__construct( ... )
+  The signature of the constructor is left to the validator implementation to
+  retrieve settings (e.g. the valid results).
+validate( mixed $result )
+  This method is responsible for validating and manipulating a given result.
+  The dialog will submit the result it received and return the manipulated
+  result back. If the result was invalid, this method will throw an exception,
+  which should be caught by the dialog.
+
 Dialog implementations
 ======================
 
@@ -154,14 +172,9 @@
 
 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.
+validator
+  The validator is an instance of ezcConsoleDialogValidator, which expects a
+  single value for verification.
 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
@@ -197,11 +210,11 @@
 ezcConsoleMenuDialogOptions:
 
 text
-  The text displyed before the menu.
+  The text displayed 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
+  The character used to divide the numbering of menu entries from their text
   representation.
 markerSpace
   The padding of whitespaces between the number and the text representation of
@@ -210,7 +223,19 @@
   The text displayed after the menu to indicate to the user that he should make
   a selection.
 
+Validator implementations
+=========================
 
+ezcConsoleDialogSingleValidator
+-------------------------------
+
+This validator can check for the correctness of a single value (meant for the
+ezcConsoleQuestionDialog class). It will expect an array of valid results on
+construction, against which the answer to a question will be matched to
+validate it. Beside this, the validator can be configured to transform the
+given result to upper or lower case, before validation.
+
+
 
 ..
    Local Variables:

-- 
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components

Reply via email to