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