helpsingle.drush.inc

Functions

Namesort descending Description
drush_core_helpsingle Command callback. Show help for a single command.
drush_format_help_section Format one named help section from a command record
drush_help_section_default_formatter The default section formatter. Replaces '[command]' with the command name.
drush_help_section_formatter_options The options section formatter. Adds a "--" in front of each item label. Also handles short-form and example-value components in the help attributes.
drush_print_help Print the help for a single command to the screen.
helpsingle_drush_command Implementation of hook_drush_command().
_drush_format_help_subsection Format one named portion of a subsection from a command record. Subsections allow related parts of a help record to be grouped together. For example, in the 'options' section, sub-options that are related to a particular primary option are…
_drush_help_merge_subcommand_information Check to see if the specified command contains an 'allow-additional-options' record. If it does, find the additional options that are allowed, and add in the help text for the options of all of the sub-commands.
_drush_help_sort_command_options Sort command options alphabetically. Engine options at the end.

File

commands/core/helpsingle.drush.inc
View source
  1. <?php
  2. /**
  3. * Implementation of hook_drush_command().
  4. *
  5. * In this hook, you specify which commands your
  6. * drush module makes available, what it does and
  7. * description.
  8. *
  9. * Notice how this structure closely resembles how
  10. * you define menu hooks.
  11. *
  12. * @return
  13. * An associative array describing your command(s).
  14. */
  15. function helpsingle_drush_command() {
  16. $items = array();
  17. $items['helpsingle'] = array(
  18. 'description' => 'Print help for a single command',
  19. 'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  20. 'allow-additional-options' => TRUE,
  21. 'hidden' => TRUE,
  22. 'arguments' => array(
  23. 'command' => 'A command name, or command alias.',
  24. ),
  25. 'examples' => array(
  26. 'drush help pm-download' => 'Show help for one command.',
  27. 'drush help dl' => 'Show help for one command using an alias.',
  28. ),
  29. 'topics' => array('docs-readme'),
  30. );
  31. return $items;
  32. }
  33. /**
  34. * Command callback. Show help for a single command.
  35. */
  36. function drush_core_helpsingle($commandstring) {
  37. // First check and see if the command can already be found.
  38. $commands = drush_get_commands();
  39. if (!array_key_exists($commandstring, $commands)) {
  40. // If the command cannot be found, then bootstrap so that
  41. // additional commands will be brought in.
  42. // TODO: We need to do a full bootstrap in order to find module service
  43. // commands. We only need to do this for Drupal 8, though; 7 and earlier
  44. // can stop at DRUSH_BOOTSTRAP_DRUPAL_SITE. Perhaps we could use command
  45. // caching to avoid bootstrapping, if we have collected the commands for
  46. // this site once already.
  47. drush_bootstrap_max();
  48. $commands = drush_get_commands();
  49. }
  50. if (array_key_exists($commandstring, $commands)) {
  51. $command = $commands[$commandstring];
  52. annotationcommand_adapter_add_hook_options($command);
  53. drush_print_help($command);
  54. return TRUE;
  55. }
  56. $shell_aliases = drush_get_context('shell-aliases', array());
  57. if (array_key_exists($commandstring, $shell_aliases)) {
  58. $msg = dt("'@alias-name' is a shell alias. Its value is: !name. See `drush topic docs-shell-aliases` and `drush shell-alias` for more information.", array('@alias-name' => $commandstring, '!name' => $shell_aliases[$commandstring]));
  59. drush_log($msg, 'ok');
  60. return TRUE;
  61. }
  62. return drush_set_error('DRUSH_COMMAND_NOT_FOUND', dt('Invalid command !command.', array('!command' => $commandstring)));
  63. }
  64. /**
  65. * Print the help for a single command to the screen.
  66. *
  67. * @param array $command
  68. * A fully loaded $command array.
  69. */
  70. function drush_print_help($command) {
  71. _drush_help_merge_subcommand_information($command);
  72. if (!$help = drush_command_invoke_all('drush_help', 'drush:'. $command['command'])) {
  73. $help = array($command['description']);
  74. }
  75. if ($command['strict-option-handling']) {
  76. $command['topics'][] = 'docs-strict-options';
  77. }
  78. // Give commandfiles an opportunity to add examples and options to the command.
  79. drush_bootstrap_max(DRUSH_BOOTSTRAP_DRUPAL_SITE);
  80. drush_engine_add_help_topics($command);
  81. drush_command_invoke_all_ref('drush_help_alter', $command);
  82. drush_print(wordwrap(implode("\n", $help), drush_get_context('DRUSH_COLUMNS', 80)));
  83. drush_print();
  84. $global_options = drush_get_global_options();
  85. foreach ($command['global-options'] as $global_option) {
  86. $command['options'][$global_option] = $global_options[$global_option];
  87. }
  88. // Sort command options.
  89. uksort($command['options'], '_drush_help_sort_command_options');
  90. // Print command sections help.
  91. foreach ($command['sections'] as $key => $value) {
  92. if (!empty($command[$key])) {
  93. $rows = drush_format_help_section($command, $key);
  94. if ($rows) {
  95. drush_print(dt($value) . ':');
  96. drush_print_table($rows, FALSE, array('label' => 40));
  97. unset($rows);
  98. drush_print();
  99. }
  100. }
  101. }
  102. // Append aliases if any.
  103. if ($command['aliases']) {
  104. drush_print(dt("Aliases: ") . implode(', ', $command['aliases']));
  105. }
  106. }
  107. /**
  108. * Sort command options alphabetically. Engine options at the end.
  109. */
  110. function _drush_help_sort_command_options($a, $b) {
  111. $engine_a = strpos($a, '=');
  112. $engine_b = strpos($b, '=');
  113. if ($engine_a && !$engine_b) {
  114. return 1;
  115. }
  116. else if (!$engine_a && $engine_b) {
  117. return -1;
  118. }
  119. elseif ($engine_a && $engine_b) {
  120. if (substr($a, 0, $engine_a) == substr($b, 0, $engine_b)) {
  121. return 0;
  122. }
  123. }
  124. return ($a < $b) ? -1 : 1;
  125. }
  126. /**
  127. * Check to see if the specified command contains an 'allow-additional-options'
  128. * record. If it does, find the additional options that are allowed, and
  129. * add in the help text for the options of all of the sub-commands.
  130. */
  131. function _drush_help_merge_subcommand_information(&$command) {
  132. // 'allow-additional-options' will either be FALSE (default),
  133. // TRUE ("allow anything"), or an array that lists subcommands
  134. // that are or may be called via drush_invoke by this command.
  135. if (is_array($command['allow-additional-options'])) {
  136. $implemented = drush_get_commands();
  137. foreach ($command['allow-additional-options'] as $subcommand_name) {
  138. if (array_key_exists($subcommand_name, $implemented)) {
  139. $command['options'] += $implemented[$subcommand_name]['options'];
  140. $command['sub-options'] = array_merge_recursive($command['sub-options'], $implemented[$subcommand_name]['sub-options']);
  141. if (empty($command['arguments'])) {
  142. $command['arguments'] = $implemented[$subcommand_name]['arguments'];
  143. }
  144. $command['topics'] = array_merge($command['topics'], $implemented[$subcommand_name]['topics']);
  145. }
  146. }
  147. }
  148. }
  149. /**
  150. * Format one named help section from a command record
  151. *
  152. * @param $command
  153. * A command record with help information
  154. * @param $section
  155. * The name of the section to format ('options', 'topic', etc.)
  156. * @returns array
  157. * Formatted rows, suitable for printing via drush_print_table. The returned
  158. * array can be empty.
  159. */
  160. function drush_format_help_section($command, $section) {
  161. $rows = array();
  162. $formatter = (function_exists('drush_help_section_formatter_' . $section)) ? 'drush_help_section_formatter_' . $section : 'drush_help_section_default_formatter';
  163. foreach ($command[$section] as $name => $help_attributes) {
  164. if (!is_array($help_attributes)) {
  165. $help_attributes = array('description' => $help_attributes);
  166. }
  167. $help_attributes['label'] = $name;
  168. call_user_func_array($formatter, array($command, &$help_attributes));
  169. if (empty($help_attributes['hidden'])) {
  170. $rows[] = array('label' => $help_attributes['label'], 'description' => $help_attributes['description']);
  171. // Process the subsections too, if any
  172. if (!empty($command['sub-' . $section]) && array_key_exists($name, $command['sub-' . $section])) {
  173. $rows = array_merge($rows, _drush_format_help_subsection($command, $section, $name, $formatter));
  174. }
  175. }
  176. }
  177. return $rows;
  178. }
  179. /**
  180. * Format one named portion of a subsection from a command record.
  181. * Subsections allow related parts of a help record to be grouped
  182. * together. For example, in the 'options' section, sub-options that
  183. * are related to a particular primary option are stored in a 'sub-options'
  184. * section whose name == the name of the primary option.
  185. *
  186. * @param $command
  187. * A command record with help information
  188. * @param $section
  189. * The name of the section to format ('options', 'topic', etc.)
  190. * @param $subsection
  191. * The name of the subsection (e.g. the name of the primary option)
  192. * @param $formatter
  193. * The name of a function to use to format the rows of the subsection
  194. * @param $prefix
  195. * Characters to prefix to the front of the label (for indentation)
  196. * @returns array
  197. * Formatted rows, suitable for printing via drush_print_table.
  198. */
  199. function _drush_format_help_subsection($command, $section, $subsection, $formatter, $prefix = ' ') {
  200. $rows = array();
  201. foreach ($command['sub-' . $section][$subsection] as $name => $help_attributes) {
  202. if (!is_array($help_attributes)) {
  203. $help_attributes = array('description' => $help_attributes);
  204. }
  205. $help_attributes['label'] = $name;
  206. call_user_func_array($formatter, array($command, &$help_attributes));
  207. if (!array_key_exists('hidden', $help_attributes)) {
  208. $rows[] = array('label' => $prefix . $help_attributes['label'], 'description' => $help_attributes['description']);
  209. // Process the subsections too, if any
  210. if (!empty($command['sub-' . $section]) && array_key_exists($name, $command['sub-' . $section])) {
  211. $rows = array_merge($rows, _drush_format_help_subsection($command, $section, $name, $formatter, $prefix . ' '));
  212. }
  213. }
  214. }
  215. return $rows;
  216. }
  217. /**
  218. * The options section formatter. Adds a "--" in front of each
  219. * item label. Also handles short-form and example-value
  220. * components in the help attributes.
  221. */
  222. function drush_help_section_formatter_options($command, &$help_attributes) {
  223. if ($help_attributes['label'][0] == '-') {
  224. drush_log(dt("Option '!option' of command !command should instead be declared as '!fixed'", array('!option' => $help_attributes['label'], '!command' => $command['command'], '!fixed' => preg_replace('/^--*/', '', $help_attributes['label']))), 'debug');
  225. }
  226. else {
  227. $help_attributes['label'] = '--' . $help_attributes['label'];
  228. }
  229. if (!empty($help_attributes['required'])) {
  230. $help_attributes['description'] .= " " . dt("Required.");
  231. }
  232. $prefix = '<';
  233. $suffix = '>';
  234. if (array_key_exists('example-value', $help_attributes)) {
  235. if (isset($help_attributes['value']) && $help_attributes['value'] == 'optional') {
  236. $prefix = '[';
  237. $suffix = ']';
  238. }
  239. $help_attributes['label'] .= '=' . $prefix . $help_attributes['example-value'] . $suffix;
  240. if (array_key_exists('short-form', $help_attributes)) {
  241. $help_attributes['short-form'] .= " $prefix" . $help_attributes['example-value'] . $suffix;
  242. }
  243. }
  244. if (array_key_exists('short-form', $help_attributes)) {
  245. $help_attributes['label'] = '-' . $help_attributes['short-form'] . ', ' . $help_attributes['label'];
  246. }
  247. drush_help_section_default_formatter($command, $help_attributes);
  248. }
  249. /**
  250. * The default section formatter. Replaces '[command]' with the
  251. * command name.
  252. */
  253. function drush_help_section_default_formatter($command, &$help_attributes) {
  254. // '[command]' is a token representing the current command. @see pm_drush_engine_version_control().
  255. $help_attributes['label'] = str_replace('[command]', $command['command'], $help_attributes['label']);
  256. }