help.drush.inc

  1. 8.0.x commands/core/help.drush.inc
  2. 6.x commands/core/help.drush.inc
  3. 7.x commands/core/help.drush.inc
  4. 4.x commands/core/help.drush.inc
  5. 5.x commands/core/help.drush.inc
  6. master commands/core/help.drush.inc

Functions

Namesort descending Description
core_help_complete Command argument complete callback.
drush_core_help Command callback for help command. This is the default command, when none other has been specified.
drush_global_options_command Build a fake command for the purposes of showing examples and options.
drush_help_listing_print Print CLI table listing all commands.
drush_help_visible
help_drush_command Implementation of hook_drush_command().
help_drush_help Implementation of hook_drush_help().

File

commands/core/help.drush.inc
View source
  1. <?php
  2. /**
  3. * Implementation of hook_drush_help().
  4. *
  5. * This function is called whenever a drush user calls
  6. * 'drush help <name-of-your-command>'
  7. *
  8. * @param
  9. * A string with the help section (prepend with 'drush:')
  10. *
  11. * @return
  12. * A string with the help text for your command.
  13. */
  14. function help_drush_help($section) {
  15. switch ($section) {
  16. case 'drush:help':
  17. return dt("Drush provides an extensive help system that describes both drush commands and topics of general interest. Use `drush help --filter` to present a list of command categories to view, and `drush topic` for a list of topics that go more in-depth on how to use and extend drush.");
  18. }
  19. }
  20. /**
  21. * Implementation of hook_drush_command().
  22. *
  23. * In this hook, you specify which commands your
  24. * drush module makes available, what it does and
  25. * description.
  26. *
  27. * Notice how this structure closely resembles how
  28. * you define menu hooks.
  29. *
  30. * @return
  31. * An associative array describing your command(s).
  32. */
  33. function help_drush_command() {
  34. $items = array();
  35. $items['help'] = array(
  36. 'description' => 'Print this help message. See `drush help help` for more options.',
  37. 'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  38. 'allow-additional-options' => array('helpsingle'),
  39. 'options' => array(
  40. 'sort' => 'Sort commands in alphabetical order. Drush waits for full bootstrap before printing any commands when this option is used.',
  41. 'filter' => array(
  42. 'description' => 'Restrict command list to those commands defined in the specified file. Omit value to choose from a list of names.',
  43. 'example-value' => 'category',
  44. 'value' => 'optional',
  45. ),
  46. ),
  47. 'arguments' => array(
  48. 'command' => 'A command name, or command alias.',
  49. ),
  50. 'examples' => array(
  51. 'drush' => 'List all commands.',
  52. 'drush --filter=devel_generate' => 'Show only commands defined in devel_generate.drush.inc',
  53. 'drush help pm-download' => 'Show help for one command.',
  54. 'drush help dl' => 'Show help for one command using an alias.',
  55. 'drush help --format=html' => 'Show an HTML page detailing all available commands.',
  56. 'drush help --format=json' => 'All available comamnds, in a machine parseable format.',
  57. ),
  58. // Use output format system for all formats except the default presentation.
  59. 'outputformat' => array(
  60. 'default' => 'table',
  61. 'field-labels' => array('name' => 'Name', 'description' => 'Description'),
  62. 'output-data-type' => 'format-table',
  63. ),
  64. 'topics' => array('docs-readme'),
  65. );
  66. return $items;
  67. }
  68. /**
  69. * Command argument complete callback.
  70. *
  71. * For now, this can't move to helpsingle since help command is the entry point for both.
  72. *
  73. * @return
  74. * Array of available command names.
  75. */
  76. function core_help_complete() {
  77. return array('values' => array_keys(drush_get_commands()));
  78. }
  79. /**
  80. * Command callback for help command. This is the default command, when none
  81. * other has been specified.
  82. */
  83. function drush_core_help($name = '') {
  84. $format = drush_get_option('format', 'table');
  85. if ($name) {
  86. // helpsingle command builds output when a command is specified.
  87. $options = drush_redispatch_get_options();
  88. if ($name != 'help') {
  89. unset($options['help']);
  90. }
  91. $return = drush_invoke_process('@self' ,'helpsingle', func_get_args(), $options);
  92. drush_backend_set_result($return['object']);
  93. return;
  94. }
  95. drush_bootstrap_max();
  96. drush_get_commands(true);
  97. $implemented = drush_get_commands();
  98. ksort($implemented);
  99. $command_categories = drush_commands_categorize($implemented);
  100. if ($format != 'table') {
  101. return $command_categories;
  102. }
  103. else {
  104. $visible = drush_help_visible($command_categories);
  105. // If the user specified --filter w/out a value, then
  106. // present a choice list of help categories.
  107. if (drush_get_option('filter', FALSE) === TRUE) {
  108. $help_categories = array();
  109. foreach ($command_categories as $key => $info) {
  110. $description = $info['title'];
  111. if (array_key_exists('summary', $info)) {
  112. $description .= ": " . $info['summary'];
  113. }
  114. $help_categories[$key] = $description;
  115. }
  116. $result = drush_choice($help_categories, 'Select a help category:');
  117. if (!$result) {
  118. return drush_user_abort();
  119. }
  120. drush_set_option('filter', $result);
  121. }
  122. // Filter out categories that the user does not want to see
  123. $filter_category = drush_get_option('filter');
  124. if (!empty($filter_category) && ($filter_category !== TRUE)) {
  125. if (!array_key_exists($filter_category, $command_categories)) {
  126. return drush_set_error('DRUSH_NO_CATEGORY', dt("The specified command category !filter does not exist.", array('!filter' => $filter_category)));
  127. }
  128. $command_categories = array($filter_category => $command_categories[$filter_category]);
  129. }
  130. // Make a fake command section to hold the global options, then print it.
  131. $global_options_help = drush_global_options_command(TRUE);
  132. if (!drush_get_option('filter')) {
  133. drush_print_help($global_options_help);
  134. }
  135. drush_help_listing_print($command_categories);
  136. drush_backend_set_result($command_categories);
  137. return;
  138. }
  139. }
  140. // Uncategorize the list of commands. Hiddens have been removed and
  141. // filtering performed.
  142. function drush_help_visible($command_categories) {
  143. $all = array();
  144. foreach ($command_categories as $category => $info) {
  145. $all = array_merge($all, $info['commands']);
  146. }
  147. return $all;
  148. }
  149. /**
  150. * Print CLI table listing all commands.
  151. */
  152. function drush_help_listing_print($command_categories) {
  153. $all_commands = array();
  154. foreach ($command_categories as $key => $info) {
  155. // Get the commands in this category.
  156. $commands = $info['commands'];
  157. // Build rows for drush_print_table().
  158. $rows = array();
  159. foreach($commands as $cmd => $command) {
  160. $name = $command['aliases'] ? $cmd . ' (' . implode(', ', $command['aliases']) . ')': $cmd;
  161. $rows[$cmd] = array('name' => $name, 'description' => $command['description']);
  162. }
  163. drush_print($info['title'] . ": (" . $key . ")");
  164. drush_print_table($rows, FALSE, array('name' => 20));
  165. }
  166. }
  167. /**
  168. * Build a fake command for the purposes of showing examples and options.
  169. */
  170. function drush_global_options_command($brief = FALSE) {
  171. $global_options_help = array(
  172. 'description' => 'Execute a drush command. Run `drush help [command]` to view command-specific help. Run `drush topic` to read even more documentation.',
  173. 'sections' => array(
  174. 'options' => 'Global options (see `drush topic core-global-options` for the full list)',
  175. ),
  176. 'options' => drush_get_global_options($brief),
  177. 'examples' => array(
  178. 'drush dl cck zen' => 'Download CCK module and Zen theme.',
  179. 'drush --uri=http://example.com status' => 'Show status command for the example.com multi-site.',
  180. ),
  181. '#brief' => TRUE,
  182. );
  183. $global_options_help += drush_command_defaults('global-options', 'global_options', __FILE__);
  184. drush_command_invoke_all_ref('drush_help_alter', $global_options_help);
  185. ksort($global_options_help['options']);
  186. return $global_options_help;
  187. }