## 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. */
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. {
48. /**
49. * Dialog result
50. *
51. * @var mixed
52. */
53. protected $result ;
55. /**
56. * Properties
57. *
58. * @var array
59. */
60. protected $properties = array(
61. "options" => null,
62. "output" => null,
63. );
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 __construct ( ezcConsoleOutput $output, ezcConsoleQuestionDialogOptions $options = null )
76. {
77. $this->output = $output;
78. $this->options = $options === null ? new ezcConsoleQuestionDialogOptions () : $options;
79. }
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. }
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. }
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 ();
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->fixup( ezcConsoleDialogViewer :: readLine () );
138. if ( $this->options->validator->validate( $result ) )
139. {
140. $this-> result = $result;
141. }
142. }
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. }
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 YesNoQuestion ( ezcConsoleOutput $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. );
190. return new ezcConsoleQuestionDialog ( $out, $opts );
191. }
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. }
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. }
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. }
267. ?>

Documentation generated by phpDocumentor 1.4.3