4 * Implementation of hook_drush_help().
6 * This function is called whenever a drush user calls
7 * 'drush help <name-of-your-command>'
10 * A string with the help section (prepend with 'drush:')
13 * A string with the help text for your command.
15 function help_drush_help($section) {
18 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.");
23 * Implementation of hook_drush_command().
25 * In this hook, you specify which commands your
26 * drush module makes available, what it does and
29 * Notice how this structure closely resembles how
30 * you define menu hooks.
33 * An associative array describing your command(s).
35 function help_drush_command() {
38 $items['help'] = array(
39 'description' => 'Print this help message. See `drush help help` for more options.',
40 'bootstrap' => DRUSH_BOOTSTRAP_NONE,
41 'allow-additional-options' => array('helpsingle'),
43 'sort' => 'Sort commands in alphabetical order. Drush waits for full bootstrap before printing any commands when this option is used.',
45 'description' => 'Restrict command list to those commands defined in the specified file. Omit value to choose from a list of names.',
46 'example-value' => 'category',
47 'value' => 'optional',
51 'command' => 'A command name, or command alias.',
54 'drush' => 'List all commands.',
55 'drush --filter=devel_generate' => 'Show only commands defined in devel_generate.drush.inc',
56 'drush help pm-download' => 'Show help for one command.',
57 'drush help dl' => 'Show help for one command using an alias.',
58 'drush help --format=html' => 'Show an HTML page detailing all available commands.',
59 'drush help --format=json' => 'All available comamnds, in a machine parseable format.',
61 // Use output format system for all formats except the default presentation.
62 'outputformat' => array(
64 'field-labels' => array('name' => 'Name', 'description' => 'Description'),
65 'output-data-type' => 'format-table',
67 'topics' => array('docs-readme'),
74 * Command argument complete callback.
76 * For now, this can't move to helpsingle since help command is the entry point for both.
79 * Array of available command names.
81 function core_help_complete() {
82 return array('values' => array_keys(drush_get_commands()));
86 * Command callback for help command. This is the default command, when none
87 * other has been specified.
89 function drush_core_help($name = '') {
90 $format = drush_get_option('format', 'table');
92 // helpsingle command builds output when a command is specified.
93 $options = drush_redispatch_get_options();
94 if ($name != 'help') {
95 unset($options['help']);
97 $return = drush_invoke_process('@self' ,'helpsingle', func_get_args(), $options);
98 drush_backend_set_result($return['object']);
102 // For speed, only bootstrap up to DRUSH_BOOTSTRAP_DRUPAL_CONFIGURATION.
103 drush_bootstrap_max();
104 drush_get_commands(true);
105 $implemented = drush_get_commands();
107 $command_categories = drush_commands_categorize($implemented);
108 if ($format != 'table') {
109 return $command_categories;
112 $visible = drush_help_visible($command_categories);
114 // If the user specified --filter w/out a value, then
115 // present a choice list of help categories.
116 if (drush_get_option('filter', FALSE) === TRUE) {
117 $help_categories = array();
118 foreach ($command_categories as $key => $info) {
119 $description = $info['title'];
120 if (array_key_exists('summary', $info)) {
121 $description .= ": " . $info['summary'];
123 $help_categories[$key] = $description;
125 $result = drush_choice($help_categories, 'Select a help category:');
127 return drush_user_abort();
129 drush_set_option('filter', $result);
131 // Filter out categories that the user does not want to see
132 $filter_category = drush_get_option('filter');
133 if (!empty($filter_category) && ($filter_category !== TRUE)) {
134 if (!array_key_exists($filter_category, $command_categories)) {
135 return drush_set_error('DRUSH_NO_CATEGORY', dt("The specified command category !filter does not exist.", array('!filter' => $filter_category)));
137 $command_categories = array($filter_category => $command_categories[$filter_category]);
140 // Make a fake command section to hold the global options, then print it.
141 $global_options_help = drush_global_options_command(TRUE);
142 if (!drush_get_option('filter')) {
143 drush_print_help($global_options_help);
145 drush_help_listing_print($command_categories);
146 drush_backend_set_result($command_categories);
151 // Uncategorize the list of commands. Hiddens have been removed and
152 // filtering performed.
153 function drush_help_visible($command_categories) {
155 foreach ($command_categories as $category => $info) {
156 $all = array_merge($all, $info['commands']);
162 * Print CLI table listing all commands.
164 function drush_help_listing_print($command_categories) {
165 $all_commands = array();
166 foreach ($command_categories as $key => $info) {
167 // Get the commands in this category.
168 $commands = $info['commands'];
170 // Build rows for drush_print_table().
172 foreach($commands as $cmd => $command) {
173 $name = $command['aliases'] ? $cmd . ' (' . implode(', ', $command['aliases']) . ')': $cmd;
174 $rows[$cmd] = array('name' => $name, 'description' => $command['description']);
176 drush_print($info['title'] . ": (" . $key . ")");
177 drush_print_table($rows, FALSE, array('name' => 20));
182 * Build a fake command for the purposes of showing examples and options.
184 function drush_global_options_command($brief = FALSE) {
185 $global_options_help = array(
186 'description' => 'Execute a drush command. Run `drush help [command]` to view command-specific help. Run `drush topic` to read even more documentation.',
188 'options' => 'Global options (see `drush topic core-global-options` for the full list)',
190 'options' => drush_get_global_options($brief),
192 'drush dl cck zen' => 'Download CCK module and Zen theme.',
193 'drush --uri=http://example.com status' => 'Show status command for the example.com multi-site.',
197 $global_options_help += drush_command_defaults('global-options', 'global_options', __FILE__);
198 drush_command_invoke_all_ref('drush_help_alter', $global_options_help);
199 ksort($global_options_help['options']);
201 return $global_options_help;