www.aleph1.co.uk Git - yaffs-website/blob - vendor/drush/drush/commands/core/docs.drush.inc

   1 <?php
   2
   3 /**
   4  * @file
   5  *   Documentation commands providing various topics.
   6  */
   7
   8 /**
   9  * Implementation of hook_drush_help().
  10  */
  11 function docs_drush_help($section) {
  12   switch ($section) {
  13     case 'meta:docs:title':
  14       return dt('Documentation commands');
  15     case 'meta:docs:summary':
  16       return dt('Show information on various drush topics.');
  17   }
  18 }
  19
  20 /**
  21  * Implementation of hook_drush_command().
  22  *
  23  * @return
  24  *   An associative array describing your command(s).
  25  */
  26 function docs_drush_command() {
  27   $docs_dir = drush_get_context('DOC_PREFIX', DRUSH_BASE_PATH);
  28
  29   //
  30   // Topic commands.
  31   // Any commandfile may add topics.
  32   // Set 'topic' => TRUE to indicate the command is a topic (REQUIRED)
  33   // Begin the topic name with the name of the commandfile (just like
  34   // any other command).
  35   //
  36   $items['docs-readme'] = array(
  37     'description' => 'README.md',
  38     'hidden' => TRUE,
  39     'topic' => TRUE,
  40     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  41     'callback' => 'drush_print_file',
  42     'callback arguments' => array($docs_dir . '/README.md'),
  43   );
  44   $items['docs-bisect'] = array(
  45     'description' => 'git bisect and Drush may be used together to find the commit an error was introduced in.',
  46     'hidden' => TRUE,
  47     'topic' => TRUE,
  48     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  49     'callback' => 'drush_print_file',
  50     'callback arguments' => array($docs_dir . '/examples/git-bisect.example.sh'),
  51   );
  52   $items['docs-bashrc'] = array(
  53     'description' => 'Bashrc customization examples for Drush.',
  54     'hidden' => TRUE,
  55     'topic' => TRUE,
  56     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  57     'callback' => 'drush_print_file',
  58     'callback arguments' => array($docs_dir . '/examples/example.bashrc'),
  59   );
  60   $items['docs-configuration'] = array(
  61     'description' => 'Configuration overview with examples from example.drushrc.php.',
  62     'hidden' => TRUE,
  63     'topic' => TRUE,
  64     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  65     'callback' => 'drush_print_file',
  66     'callback arguments' => array($docs_dir . '/examples/example.drushrc.php'),
  67   );
  68   $items['docs-config-filter'] = array(
  69     'description' => 'Drupal Configuration Filtering with custom storage filters.',
  70     'hidden' => TRUE,
  71     'topic' => TRUE,
  72     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  73     'callback' => 'drush_print_file',
  74     'callback arguments' => array($docs_dir . '/docs/config-filter.md'),
  75   );
  76   $items['docs-config-exporting'] = array(
  77     'description' => 'Drupal configuration export instructions, including customizing configuration by environment.',
  78     'hidden' => TRUE,
  79     'topic' => TRUE,
  80     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  81     'callback' => 'drush_print_file',
  82     'callback arguments' => array($docs_dir . '/docs/config-exporting.md'),
  83   );
  84   $items['docs-aliases'] = array(
  85     'description' => 'Site aliases overview on creating your own aliases for commonly used Drupal sites with examples from example.aliases.drushrc.php.',
  86     'hidden' => TRUE,
  87     'topic' => TRUE,
  88     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  89     'callback' => 'drush_print_file',
  90     'callback arguments' => array($docs_dir . '/examples/example.aliases.drushrc.php'),
  91   );
  92   $items['docs-ini-files'] = array(
  93     'description' => 'php.ini or drush.ini configuration to set PHP values for use with Drush.',
  94     'hidden' => TRUE,
  95     'topic' => TRUE,
  96     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
  97     'callback' => 'drush_print_file',
  98     'callback arguments' => array($docs_dir . '/examples/example.drush.ini'),
  99   );
 100   $items['docs-bastion'] = array(
 101     'description' => 'Bastion server configuration: remotely operate on a Drupal sites behind a firewall.',
 102     'hidden' => TRUE,
 103     'topic' => TRUE,
 104     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 105     'callback' => 'drush_print_file',
 106     'callback arguments' => array($docs_dir . '/docs/bastion.md'),
 107   );
 108   $items['docs-bootstrap'] = array(
 109     'description' => 'Bootstrap explanation: how Drush starts up and prepares the Drupal environment for use with the command.',
 110     'hidden' => TRUE,
 111     'topic' => TRUE,
 112     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 113     'callback' => 'drush_print_file',
 114     'callback arguments' => array($docs_dir . '/docs/bootstrap.md'),
 115   );
 116   $items['docs-cron'] = array(
 117     'description' => 'Crontab instructions for running your Drupal cron tasks via `drush cron`.',
 118     'hidden' => TRUE,
 119     'topic' => TRUE,
 120     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 121     'callback' => 'drush_print_file',
 122     'callback arguments' => array($docs_dir . '/docs/cron.md'),
 123   );
 124   $items['docs-scripts'] = array(
 125     'description' => 'Shell script overview on writing simple sequences of Drush statements.',
 126     'hidden' => TRUE,
 127     'topic' => TRUE,
 128     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 129     'callback' => 'drush_print_file',
 130     'callback arguments' => array($docs_dir . '/docs/shellscripts.md'),
 131   );
 132   $items['docs-shell-aliases'] = array(
 133     'description' => 'Shell alias overview on creating your own aliases for commonly used Drush commands.',
 134     'hidden' => TRUE,
 135     'topic' => TRUE,
 136     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 137     'callback' => 'drush_print_file',
 138     'callback arguments' => array($docs_dir . '/docs/shellaliases.md'),
 139   );
 140   $items['docs-commands'] = array(
 141     'description' => 'Drush command instructions on creating your own Drush commands.',
 142     'hidden' => TRUE,
 143     'topic' => TRUE,
 144     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 145     'callback' => 'drush_print_file',
 146     'callback arguments' => array($docs_dir . '/docs/commands.md'),
 147   );
 148   $items['docs-errorcodes'] = array(
 149     'description' => 'Error code list containing all identifiers used with drush_set_error.',
 150     'hidden' => TRUE,
 151     'topic' => TRUE,
 152     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 153   );
 154   $items['docs-api'] = array(
 155     'description' => 'Drush API',
 156     'hidden' => TRUE,
 157     'topic' => TRUE,
 158     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 159     'callback' => 'drush_print_file',
 160     'callback arguments' => array($docs_dir . '/drush.api.php'),
 161   );
 162   $items['docs-context'] = array(
 163     'description' => 'Contexts overview explaining how Drush manages command line options and configuration file settings.',
 164     'hidden' => TRUE,
 165     'topic' => TRUE,
 166     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 167     'callback' => 'drush_print_file',
 168     'callback arguments' => array($docs_dir . '/docs/context.md'),
 169   );
 170   $items['docs-examplescript'] = array(
 171     'description' => 'Example Drush script.',
 172     'hidden' => TRUE,
 173     'topic' => TRUE,
 174     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 175     'callback' => 'drush_print_file',
 176     'callback arguments' => array($docs_dir . '/examples/helloworld.script'),
 177   );
 178   $items['docs-examplecommand'] = array(
 179     'description' => 'Example Drush command file.',
 180     'hidden' => TRUE,
 181     'topic' => TRUE,
 182     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 183     'callback' => 'drush_print_file',
 184     'callback arguments' => array($docs_dir . '/examples/sandwich.drush.inc'),
 185   );
 186   $items['docs-example-sync-extension'] = array(
 187     'description' => 'Example Drush commandfile that extends sql-sync to enable development modules in the post-sync hook.',
 188     'hidden' => TRUE,
 189     'topic' => TRUE,
 190     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 191     'callback' => 'drush_print_file',
 192     'callback arguments' => array($docs_dir . '/examples/sync_enable.drush.inc'),
 193   );
 194   $items['docs-example-sync-via-http'] = array(
 195     'description' => 'Example Drush commandfile that extends sql-sync to allow transfer of the sql dump file via http rather than ssh and rsync.',
 196     'hidden' => TRUE,
 197     'topic' => TRUE,
 198     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 199     'callback' => 'drush_print_file',
 200     'callback arguments' => array($docs_dir . '/examples/sync_via_http.drush.inc'),
 201   );
 202   $items['docs-policy'] = array(
 203     'description' => 'Example policy file.',
 204     'hidden' => TRUE,
 205     'topic' => TRUE,
 206     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 207     'callback' => 'drush_print_file',
 208     'callback arguments' => array($docs_dir . '/examples/policy.drush.inc'),
 209   );
 210   $items['docs-strict-options'] = array(
 211     'description' => 'Strict option handling, and how commands that use it differ from regular Drush commands.',
 212     'hidden' => TRUE,
 213     'topic' => TRUE,
 214     'bootstrap' => DRUSH_BOOTSTRAP_NONE,
 215     'callback' => 'drush_print_file',
 216     'callback arguments' => array($docs_dir . '/docs/strict-options.md'),
 217   );
 218   return $items;
 219 }
 220
 221 /**
 222  * docs-errorcodes command.  Print a list of all error codes
 223  * that can be found.
 224  */
 225 function drush_docs_errorcodes() {
 226   $header = <<<EOD
 227 ==== Drush Error Codes ====
 228
 229 Drush error codes are alphanumeric constants that represent an unrecoverable error condition that may arise during the execution of some command.  They are set by the following function:
 230
 231   return drush_set_error('DRUSH_ERROR_CODE', dt('Error message.'));
 232
 233 In general, any drush command that calls drush_set_error is expected to also return FALSE as its function result.  The drush_set_error function returns FALSE to make it easy to exit with an error code.  Error codes are returned as part of the drush backend invoke process, which is used by drush API functions such as drush_invoke_process.  An example of how to test for a specific error code is shown below:
 234
 235   \$result = drush_invoke_process('@self', 'some-command');
 236   if (array_key_exists('DRUSH_ERROR_CODE', \$result['error_log'])) {
 237     // handle ocurrances of DRUSH_ERROR_CODE here
 238   }
 239
 240 Some of the available drush error codes are listed in the table below.
 241
 242
 243 EOD;
 244
 245   // Find all of the files that we will search for error messages.
 246   // Start with all of the commandfiles.
 247   $commandfiles = drush_commandfile_list();
 248   $files = array_flip($commandfiles);
 249   // In addition to the commandfiles, we will also look for files
 250   // that drush will load when executing a command (e.g
 251   // updatecode.pm.inc)
 252   $commands = drush_get_commands();
 253   foreach ($commands as $command_name => $command) {
 254     $files = array_merge($files, drush_command_get_includes($command_name));
 255   }
 256   // We will also search through all of the .inc files in the
 257   // drush includes directory
 258   $drush_include_files = drush_scan_directory(DRUSH_BASE_PATH . '/includes', '/.*\.inc$/', array('.', '..', 'CVS'), 0, FALSE);
 259   foreach ($drush_include_files as $filename => $info) {
 260     $files[$filename] = 'include';
 261   }
 262
 263   // Extract error messages from all command files
 264   $error_list = array();
 265   foreach ($files as $file => $commandfile) {
 266     _drush_docs_find_set_error_calls($error_list, $file, $commandfile);
 267   }
 268   // Order error messages alphabetically by key
 269   ksort($error_list);
 270   // Convert to a table
 271   $data = array();
 272   foreach ($error_list as $error_code => $error_messages) {
 273     $data[] = array($error_code, '-', implode("\n", $error_messages));
 274   }
 275
 276   $tmpfile = drush_tempnam('drush-errorcodes.');
 277   file_put_contents($tmpfile, $header);
 278   $handle = fopen($tmpfile, 'a');
 279   drush_print_table($data, FALSE, array(0 => 35), $handle);
 280   fclose($handle);
 281   drush_print_file($tmpfile);
 282 }
 283
 284 /**
 285  * Search through a php source file looking for calls to
 286  * the function drush_set_error.  If found, and if the
 287  * first parameter is an uppercase alphanumeric identifier,
 288  * then record the error code and the error message in our table.
 289  */
 290 function _drush_docs_find_set_error_calls(&$error_list, $filename, $shortname) {
 291   $lines = file($filename);
 292   foreach ($lines as $line) {
 293     $matches = array();
 294     // Find the error code after the drush_set_error call.  The error code
 295     // should consist of uppercase letters and underscores only (numbers thrown in just in case)
 296     $match_result = preg_match("/.*drush_set_error[^'\"]['\"]([A-Z0-9_]*)['\"][^,]*,[^'\"]*(['\"])/", $line, $matches);
 297     if ($match_result) {
 298       $error_code = $matches[1];
 299       $quote_char = $matches[2];
 300       $error_message = "";
 301       $message_start = strlen($matches[0]) - 1;
 302
 303       // Regex adapted from http://stackoverflow.com/questions/1824325/regex-expression-for-escaped-quoted-string-wont-work-in-phps-preg-match-allif ($quote_char == '"') {
 304       if ($quote_char == '"') {
 305         $regex = '/"((?:[^\\\]*?(?:\\\")?)*?)"/';
 306       }
 307       else {
 308         $regex = "/'((?:[^\\\]*?(?:\\\')?)*?)'/";
 309       }
 310       $match_result = preg_match($regex, $line, $matches, 0, $message_start);
 311
 312       if ($match_result) {
 313         $error_message = $matches[1];
 314       }
 315       $error_list[$error_code] = array_key_exists($error_code, $error_list) ? array_merge($error_list[$error_code], array($error_message)) : array($error_message);
 316     }
 317   }
 318 }