## Apache Zeta Components Manual :: File Source for standard.php

## Source for file standard.php

Documentation is available at standard.php

1. <?php
2. /**
3. * File containing the ezcConsoleInputStandardHelpGenerator 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. * Standard help generator for {@link ezcConsoleInput}.
29. *
30. * Standard help generation as {@link ezcConsoleInput} did from the start.
31. *
32. * @package ConsoleTools
33. * @version //autogen//
34. *
35. * @access private
36. * @TODO Verify interface and make it public to replace the validation in
37. * {@link ezcConsoleInput}.
38. */
39. class ezcConsoleInputStandardHelpGenerator implements ezcConsoleInputHelpGenerator
40. {
41. /**
42. * Input object.
43. *
44. * @var ezcConsoleInput
45. */
46. private $input;
48. /**
49. * Creates a new help generator.
50. *
51. * Creates a new help generator for the given $input.
52. *
53. * @param ezcConsoleInput $input
54. */
55. public function __construct( ezcConsoleInput $input )
56. {
57. $this->input = $input;
58. }
60. /**
61. * Generates help information as a multidimensional array.
62. *
63. * This method generates a tabular view on the help information of a
64. * program. The returned array has the following structure:
65. *
66. * <code>
67. * <?php
68. * array(
69. * 0 => array(
70. * 0 => '<option short/long name>',
71. * 1 => '<option help, depending on the $long parameter>'
72. * ),
73. * 1 => array(
74. * 0 => '<option short name> / <option long name>',
75. * 1 => '<option help, depending on the $long parameter>'
76. * ),
77. * // ...
78. * );
79. * ?>
80. * </code>
81. *
82. * Each row of the array represents the help information for a single option.
83. * The first cell of a row contains the option name (maybe short, long or
84. * both), the second cell contains the help text of the option.
85. *
86. * The returned array is used by {@link ezcConsoleInput} for different
87. * purposes.
88. * For example, the user can retrieve it raw through the
89. * {@link ezcConsoleInput::getHelp()} method, he can generate a help
90. * {@link ezcConsoleTable} through {@link ezcConsoleInput::getHelpTable()}
91. * are can generate a printable help text through {@link }
92. * ezcConsoleInput::getHelpText()}.
93. *
94. * The parameter $long defines if the long or short help text of the
95. * options should be used in the second cell of the returned array. The
96. * $optionsFilter parameter is used to restrict the generated help to a certain
97. * sub-set of options. It consists of an array of short or long names of
98. * the options to include.
99. *
100. * @param bool $long
101. * @param array(string) $optionsFilter
102. * @return array(array(string))
103. */
104. public function generateUngroupedOptionHelp( $long = false, array $optionsFilter = null )
105. {
106. $help = array();
107. foreach ( $this->input->getOptions() as $id => $param )
108. {
109. if ( $optionsFilter === null || in_array ( $param->short, $optionsFilter ) || in_array ( $param->long, $optionsFilter ) )
110. {
111. $help[] = $this->getOptionHelpRow( $long, $param );
112. }
113. }
114. return $help;
115. }
117. /**
118. * Generates help information as a multidimensional array, grouped in categories.
119. *
120. * This method behaves similar to {@link generateUngroupedOptionHelp()}. In
121. * contrast to the latter one, this method returns an array with 1
122. * dimension more, grouping options into categories. The $groups parameter
123. * defines the categories to generate. Each category may contain an
124. * arbitrary number of options, options might occur in different
125. * categories.
126. *
127. * The returned array has the follorwing format:
128. *
129. * <code>
130. * <?php
131. * array(
132. * '<category name>' => array(
133. * 0 => array(
134. * 0 => '<option short/long name>',
135. * 1 => '<option help, depending on the $long parameter>'
136. * ),
137. * 1 => array(
138. * 0 => '<option short name> / <option long name>',
139. * 1 => '<option help, depending on the $long parameter>'
140. * ),
141. * // ...
142. * ),
143. * '<category name>' => array(
144. * // ...
145. * ),
146. * // ...
147. * );
148. * ?>
149. * </code>
150. *
151. * The $long parameter, as in {@link generateUngroupedOptionHelp()}
152. * determines if the options short or long help is to be used. The
153. * $params array can in addition be used to determine if a parameter
154. * is displayed at all. If $optionsFilter is submitted and is not null,
155. * only options listed in it will be shown in the help at all.
156. *
157. * @param array(string=>array(string)) $groups
158. * @param bool $long
159. * @param array(string) $params
160. * @return array(string=>array(array(string)))
161. */
162. public function generateGroupedOptionHelp( array $groups, $long = false, array $optionsFilter = null )
163. {
164. $help = array();
165. foreach ( $groups as $groupName => $groupOptions )
166. {
167. foreach ( $groupOptions as $optionName )
168. {
169. $option = $this->input->getOption( $optionName );
170. if ( $optionsFilter === null || in_array ( $option->short, $optionsFilter ) || in_array ( $option->long, $optionsFilter ) )
171. {
172. $help[$groupName][] = $this->getOptionHelpRow(
173. $long,
174. $option
175. );
176. }
177. }
178. }
179. return $help;
180. }
182. /**
183. * Generates help information as a multi-dimensonal array for the given $argumentDefinition.
184. *
185. * This method generates a tabular help information for the given
186. * $argumentDefinition in the following format:
187. *
188. * <code>
189. * <?php
190. * array(
191. * 0 => array(
192. * 0 => '<argument synopsis>',
193. * 1 => '<argument help text>'
194. * ),
195. * 1 => array(
196. * 0 => '<argument synopsis>',
197. * 1 => '<argument help text>'
198. * ),
199. * // ...
200. * )
201. * ?>
202. * </code>
203. *
204. * The $long parameter defines if the long of short help text should be
205. * used.
206. *
207. * @param bool $long
208. * @return array(array(string))
209. */
210. public function generateArgumentHelp( $long = false )
211. {
212. $help = array();
213. if ( $this->input->argumentDefinition !== null )
214. {
215. foreach ( $this->input->argumentDefinition as $arg )
216. {
217. $argSynopsis = "<%s:%s>";
218. switch ( $arg->type )
219. {
220. case ezcConsoleInput ::TYPE_INT:
221. $type = "int";
222. break;
223. case ezcConsoleInput ::TYPE_STRING:
224. $type = "string";
225. break;
226. }
227. $argSynopsis = sprintf ( $argSynopsis, $type, $arg->name );
228. $help[] = ( $long === true )
229. ? array(
230. $argSynopsis,
231. $arg->longhelp . ( $arg->mandatory === false
232. ? ' (optional' . ( $arg->default !== null
233. ? ', default = ' . ( is_array ( $arg->default )
234. ? "'" . implode ( "' '", $arg->default ) . "'"
235. : "'$arg->default'"
236. )
237. : ''
238. ) . ')'
239. : ''
240. )
241. )
242. : array( $argSynopsis, $arg->shorthelp );
243. }
244. }
245. return $help;
246. }
248. /**
249. * Creates 1 text row for displaying options help.
250. *
251. * Returns a single array entry for the {@link getOptionHelpRow()} method.
252. *
253. * @param bool $long
254. * @param ezcConsoleOption $param
255. * @return string
256. */
257. private function getOptionHelpRow( $long, ezcConsoleOption $param )
258. {
259. return array(
260. ( $param->short !== "" ? '-' . $param->short . ' / ' : "" ) . '--' . $param->long,
261. $long == false ? $param->shorthelp : $param->longhelp,
262. );
263. }
265. /**
266. * Generates a command line synopsis for the options and arguments.
267. *
268. * This method generates a synopsis string that lists the options and
269. * parameters available, indicating their usage. If $optionsFilter is
270. * submitted, only the options named in this array (short or long variant)
271. * will be included in the synopsis.
272. *
273. * @param array(string) $optionsFilter
274. * @return string
275. */
276. public function generateSynopsis( array $optionFilter = null )
277. {
278. $usedOptions = array( 'short' => array(), 'long' => array() );
279. $allowsArgs = true;
280. $synopsis = '$ ' . ( isset( $argv ) && sizeof ( $argv ) > 0 ? $argv[0] : $_SERVER['argv'][0] ) . ' ';
281. foreach ( $this->input->getOptions() as $option )
282. {
283. if ( $optionFilter === null || in_array ( $option->short, $optionFilter ) || in_array ( $option->long, $optionFilter ) )
284. {
285. $synopsis .= $this->createOptionSynopsis( $option, $usedOptions, $allowsArgs );
286. }
287. }
288. if ( $this->input->argumentDefinition === null )
289. {
290. // Old handling
291. $synopsis .= " [[--] <args>]";
292. }
293. else
294. {
295. $synopsis .= "[--] " . $this->createArgumentsSynopsis();
296. }
297. return $synopsis;
298. }
300. /**
301. * Returns the synopsis string for a single option and its dependencies.
302. *
303. * This method returns a part of the program synopsis, specifically for a
304. * certain parameter. The method recursively adds depending parameters up
305. * to the 2nd depth level to the synopsis. The second parameter is used
306. * to store the short names of all options that have already been used in
307. * the synopsis (to avoid adding an option twice). The 3rd parameter
308. * determines the actual deps in the option dependency recursion to
309. * terminate that after 2 recursions.
310. *
311. * @param ezcConsoleOption $option The option to include.
312. * @param array(string) $usedOptions Array of used option short names.
313. * @param int $depth Current recursion depth.
314. * @return string The synopsis for this parameter.
315. */
316. private function createOptionSynopsis( ezcConsoleOption $option, &$usedOptions, $depth = 0 )
317. {
318. $synopsis = '';
320. // Break after a nesting level of 2
321. if ( $depth++ > 2 || ( in_array ( $option->short, $usedOptions['short'] ) && in_array ( $option->long, $usedOptions['long'] ) ) ) return $synopsis;
323. $usedOptions['short'][] = $option->short;
324. $usedOptions['long'][] = $option->long;
326. $synopsis .= $option->short !== "" ? "-{$option->short}

" : "--{$option->long}";
- if ( isset( $option->default ) )
- {
- $synopsis .= " " . ( $option->type === ezcConsoleInput ::TYPE_STRING ? '"' : '' ) . $option->default . ( $option->type === ezcConsoleInput ::TYPE_STRING ? '"' : '' );
- }
- else if ( $option->type !== ezcConsoleInput ::TYPE_NONE )
- {
- $synopsis .= " ";
- switch ( $option->type )
- {
- case ezcConsoleInput ::TYPE_STRING:
- $synopsis .= "<string>";
- break;
- case ezcConsoleInput ::TYPE_INT:
- $synopsis .= "<int>";
- break;
- }
- }
- foreach ( $option->getDependencies() as $rule )
- {
- $deeperSynopsis = $this->createOptionSynopsis( $rule->option, $usedOptions, $depth );
- $synopsis .= ( iconv_strlen ( trim ( $deeperSynopsis ), 'UTF-8' ) > 0
- ? ' ' . $deeperSynopsis
- : ''
- );
- }
- if ( $option->arguments === false )
- {
- $allowsArgs = false;
- }
- // Make the whole thing optional?
- if ( $option->mandatory === false )
- {
- $synopsis = "[$synopsis]";
- }
- return $synopsis . ' ';
- }
- /**
- * Generate synopsis for arguments.
- *
- * @return string The synopsis string.
- */
- private function createArgumentsSynopsis()
- {
- $mandatory = true;
- $synopsises = array();
- foreach ( $this->input->argumentDefinition as $arg )
- {
- $argSynopsis = "";
- if ( $arg->mandatory === false )
- {
- $mandatory = false;
- }
- $argSynopsis .= "<%s:%s>";
- switch ( $arg->type )
- {
- case ezcConsoleInput ::TYPE_INT:
- $type = "int";
- break;
- case ezcConsoleInput ::TYPE_STRING:
- $type = "string";
- break;
- }
- $argSynopsis = sprintf ( $argSynopsis, $type, $arg->name );
- $synopsises[] = $mandatory === false ? "[$argSynopsis]" : $argSynopsis;
- if ( $arg->multiple === true )
- {
- $synopsises[] = "[$argSynopsis ...]";
- break;
- }
- }
- return implode ( " ", $synopsises );
- }
- }
- ?>
Documentation generated by phpDocumentor 1.4.3