docs.drush.inc

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

Documentation commands providing various topics.

Functions

Namesort descending Description
docs_drush_command Implementation of hook_drush_command().
docs_drush_help Implementation of hook_drush_help().
drush_docs_errorcodes docs-error-codes command. Print a list of all error codes that can be found.
_drush_docs_find_set_error_calls Search through a php source file looking for calls to the function drush_set_error. If found, and if the first parameter is an uppercase alphanumeric identifier, then record the error code and the error message in our table.

File

commands/core/docs.drush.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * Documentation commands providing various topics.
  5. */
  6. /**
  7. * Implementation of hook_drush_help().
  8. */
  9. function docs_drush_help($section) {
  10. switch ($section) {
  11. case 'meta:docs:title':
  12. return dt('Documentation commands');
  13. case 'meta:docs:summary':
  14. return dt('Show information on various drush topics.');
  15. }
  16. }
  17. /**
  18. * Implementation of hook_drush_command().
  19. *
  20. * @return
  21. * An associative array describing your command(s).
  22. */
  23. function docs_drush_command() {
  24. $docs_dir = drush_get_context('DOC_PREFIX', DRUSH_BASE_PATH);
  25. //
  26. // Topic commands.
  27. // Any commandfile may add topics.
  28. // Set 'topic' => TRUE to indicate the command is a topic (REQUIRED)
  29. // Begin the topic name with the name of the commandfile (just like
  30. // any other command).
  31. //
  32. $items['docs-readme'] = array(
  33. 'description' => 'README.txt',
  34. 'hidden' => TRUE,
  35. 'topic' => TRUE,
  36. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  37. 'callback' => 'drush_print_file',
  38. 'callback arguments' => array($docs_dir . '/README.txt'),
  39. );
  40. $items['docs-configuration'] = array(
  41. 'description' => 'Drush configuration overview with examples',
  42. 'hidden' => TRUE,
  43. 'topic' => TRUE,
  44. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  45. 'callback' => 'drush_print_file',
  46. 'callback arguments' => array($docs_dir . '/examples/example.drushrc.php'),
  47. );
  48. $items['docs-aliases'] = array(
  49. 'description' => 'Site aliases overview with examples',
  50. 'hidden' => TRUE,
  51. 'topic' => TRUE,
  52. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  53. 'callback' => 'drush_print_file',
  54. 'callback arguments' => array($docs_dir . '/examples/example.aliases.drushrc.php'),
  55. );
  56. $items['docs-ini-files'] = array(
  57. 'description' => 'Configuring php.ini or drush.ini for use with drush.',
  58. 'hidden' => TRUE,
  59. 'topic' => TRUE,
  60. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  61. 'callback' => 'drush_print_file',
  62. 'callback arguments' => array($docs_dir . '/examples/example.drush.ini'),
  63. );
  64. $items['docs-bastion'] = array(
  65. 'description' => 'How to use a bastion server to remotely operate on Drupal sites behind a firewall.',
  66. 'hidden' => TRUE,
  67. 'topic' => TRUE,
  68. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  69. 'callback' => 'drush_print_file',
  70. 'callback arguments' => array($docs_dir . '/docs/bastion.html'),
  71. );
  72. $items['docs-bootstrap'] = array(
  73. 'description' => 'Information about the drush bootstrap process.',
  74. 'hidden' => TRUE,
  75. 'topic' => TRUE,
  76. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  77. 'callback' => 'drush_print_file',
  78. 'callback arguments' => array($docs_dir . '/docs/bootstrap.html'),
  79. );
  80. $items['docs-scripts'] = array(
  81. 'description' => 'Overview on how to write drush shell scripts.',
  82. 'hidden' => TRUE,
  83. 'topic' => TRUE,
  84. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  85. 'callback' => 'drush_print_file',
  86. 'callback arguments' => array($docs_dir . '/docs/shellscripts.html'),
  87. );
  88. $items['docs-commands'] = array(
  89. 'description' => 'Overview on how to write drush commands.',
  90. 'hidden' => TRUE,
  91. 'topic' => TRUE,
  92. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  93. 'callback' => 'drush_print_file',
  94. 'callback arguments' => array($docs_dir . '/docs/commands.html'),
  95. );
  96. $items['docs-errorcodes'] = array(
  97. 'description' => 'Summary of drush error codes.',
  98. 'hidden' => TRUE,
  99. 'topic' => TRUE,
  100. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  101. );
  102. $items['docs-api'] = array(
  103. 'description' => 'Drush API',
  104. 'hidden' => TRUE,
  105. 'topic' => TRUE,
  106. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  107. 'callback' => 'drush_print_file',
  108. 'callback arguments' => array($docs_dir . '/docs/drush.api.php'),
  109. );
  110. $items['docs-context'] = array(
  111. 'description' => 'Drush contexts',
  112. 'hidden' => TRUE,
  113. 'topic' => TRUE,
  114. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  115. 'callback' => 'drush_print_file',
  116. 'callback arguments' => array($docs_dir . '/docs/context.html'),
  117. );
  118. $items['docs-examplescript'] = array(
  119. 'description' => 'Example drush script',
  120. 'hidden' => TRUE,
  121. 'topic' => TRUE,
  122. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  123. 'callback' => 'drush_print_file',
  124. 'callback arguments' => array($docs_dir . '/examples/helloworld.script'),
  125. );
  126. $items['docs-examplecommand'] = array(
  127. 'description' => 'Example drush command file.',
  128. 'hidden' => TRUE,
  129. 'topic' => TRUE,
  130. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  131. 'callback' => 'drush_print_file',
  132. 'callback arguments' => array($docs_dir . '/examples/sandwich.drush.inc'),
  133. );
  134. $items['docs-policy'] = array(
  135. 'description' => 'Example policy file.',
  136. 'hidden' => TRUE,
  137. 'topic' => TRUE,
  138. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  139. 'callback' => 'drush_print_file',
  140. 'callback arguments' => array($docs_dir . '/examples/policy.drush.inc'),
  141. );
  142. $items['docs-upgrading'] = array(
  143. 'description' => 'Upgrading Drupal using the drush site-upgrade command.',
  144. 'hidden' => TRUE,
  145. 'topic' => TRUE,
  146. 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
  147. 'callback' => 'drush_print_file',
  148. 'callback arguments' => array($docs_dir . '/docs/upgrade.html'),
  149. );
  150. return $items;
  151. }
  152. /**
  153. * docs-error-codes command. Print a list of all error codes
  154. * that can be found.
  155. */
  156. function drush_docs_errorcodes() {
  157. $header = <<<EOD
  158. ==== Drush Error Codes ====
  159. 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:
  160. return drush_set_error('DRUSH_ERROR_CODE', dt('Error message.'));
  161. 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:
  162. \$result = drush_invoke_process('some-command');
  163. if (array_key_exists('DRUSH_ERROR_CODE', \$result['error_log'])) {
  164. // handle ocurrances of DRUSH_ERROR_CODE here
  165. }
  166. Some of the available drush error codes are listed in the table below.
  167. EOD;
  168. // Find all of the files that we will search for error messages.
  169. // Start with all of the commandfiles.
  170. $commandfiles = drush_commandfile_list();
  171. $files = array_flip($commandfiles);
  172. // In addition to the commandfiles, we will also look for files
  173. // that drush will load when executing a command; examples include
  174. // updatecode.pm.inc and sync.sql.inc.
  175. $commands = drush_get_commands();
  176. foreach ($commands as $command_name => $command) {
  177. $files = array_merge($files, drush_command_get_includes($command_name));
  178. }
  179. // We will also search through all of the .inc files in the
  180. // drush includes directory
  181. $drush_include_files = drush_scan_directory(DRUSH_BASE_PATH . '/includes', '/.*\.inc$/', array('.', '..', 'CVS'), 0, FALSE);
  182. foreach ($drush_include_files as $filename => $info) {
  183. $files[$filename] = 'include';
  184. }
  185. // Extract error messages from all command files
  186. $error_list = array();
  187. foreach ($files as $file => $commandfile) {
  188. _drush_docs_find_set_error_calls($error_list, $file, $commandfile);
  189. }
  190. // Order error messages alphabetically by key
  191. ksort($error_list);
  192. // Convert to a table
  193. $data = array();
  194. foreach ($error_list as $error_code => $error_messages) {
  195. $data[] = array($error_code, '-', implode("\n", $error_messages));
  196. }
  197. $tmpfile = drush_tempnam('drush-errorcodes.');
  198. file_put_contents($tmpfile, $header);
  199. drush_print_table($data, FALSE, array(0 => 35), $tmpfile);
  200. drush_print_file($tmpfile);
  201. }
  202. /**
  203. * Search through a php source file looking for calls to
  204. * the function drush_set_error. If found, and if the
  205. * first parameter is an uppercase alphanumeric identifier,
  206. * then record the error code and the error message in our table.
  207. */
  208. function _drush_docs_find_set_error_calls(&$error_list, $filename, $shortname) {
  209. $lines = file($filename);
  210. foreach ($lines as $line) {
  211. $matches = array();
  212. // Find the error code after the drush_set_error call. The error code
  213. // should consist of uppercase letters and underscores only (numbers thrown in just in case)
  214. $match_result = preg_match("/.*drush_set_error[^'\"]['\"]([A-Z0-9_]*)['\"][^,]*,[^'\"]*(['\"])/", $line, $matches);
  215. if ($match_result) {
  216. $error_code = $matches[1];
  217. $quote_char = $matches[2];
  218. $error_message = "";
  219. $message_start = strlen($matches[0]) - 1;
  220. // Regex adapted from http://stackoverflow.com/questions/1824325/regex-expression-for-escaped-quoted-string-wont-work-in-phps-preg-match-allif ($quote_char == '"') {
  221. if ($quote_char == '"') {
  222. $regex = '/"((?:[^\\\]*?(?:\\\")?)*?)"/';
  223. }
  224. else {
  225. $regex = "/'((?:[^\\\]*?(?:\\\')?)*?)'/";
  226. }
  227. $match_result = preg_match($regex, $line, $matches, 0, $message_start);
  228. if ($match_result) {
  229. $error_message = $matches[1];
  230. }
  231. $error_list[$error_code] = array_key_exists($error_code, $error_list) ? array_merge($error_list[$error_code], array($error_message)) : array($error_message);
  232. }
  233. }
  234. }