Back to dev
[project/drush.git] / examples / sandwich.drush.inc
1 <?php
2
3 /**
4 * @file
5 * Example drush command.
6 *
7 * To run this *fun* command, execute `sudo drush --include=./examples mmas`
8 * from within your drush directory.
9 *
10 * See `drush topic docs-commands` for more information about command authoring.
11 *
12 * You can copy this file to any of the following
13 * 1. A .drush folder in your HOME folder.
14 * 2. Anywhere in a folder tree below an active module on your site.
15 * 3. /usr/share/drush/commands (configurable)
16 * 4. In an arbitrary folder specified with the --include option.
17 * 5. Drupal's /drush or /sites/all/drush folders.
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 * See `drush topic docs-commands` for a list of recognized keys.
31 *
32 * @return
33 * An associative array describing your command(s).
34 */
35 function sandwich_drush_command() {
36 $items = array();
37
38 // The 'make-me-a-sandwich' command
39 $items['make-me-a-sandwich'] = array(
40 'description' => "Makes a delicious sandwich.",
41 'arguments' => array(
42 'filling' => 'The type of the sandwich (turkey, cheese, etc.). Defaults to ascii.',
43 ),
44 'options' => array(
45 'spreads' => array(
46 'description' => 'Comma delimited list of spreads.',
47 'example-value' => 'mayonnaise,mustard',
48 ),
49 ),
50 'examples' => array(
51 'drush mmas turkey --spreads=ketchup,mustard' => 'Make a terrible-tasting sandwich that is lacking in pickles.',
52 ),
53 'aliases' => array('mmas'),
54 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH, // No bootstrap at all.
55 );
56
57 // The 'sandwiches-served' command. Informs how many 'mmas' commands completed.
58 $items['sandwiches-served'] = array(
59 'description' => "Report how many sandwiches we have made.",
60 'examples' => array(
61 'drush sandwiches-served' => 'Show how many sandwiches we have served.',
62 ),
63 'aliases' => array('sws'),
64 // Example output engine data: command returns a single keyed
65 // data item (e.g. array("served" => 1)) that can either be
66 // printed with a label (e.g. "served: 1"), or output raw with
67 // --pipe (e.g. "1").
68 'engines' => array(
69 'outputformat' => array(
70 'default' => 'key-value',
71 'pipe-format' => 'string',
72 'label' => 'Sandwiches Served',
73 'require-engine-capability' => array('format-single'),
74 ),
75 ),
76 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH, // No bootstrap at all.
77 );
78
79 // The 'spreads-status' command. Prints a table about available spreads.
80 $items['spreads-status'] = array(
81 'description' => "Show a table of information about available spreads.",
82 'examples' => array(
83 'drush spreads-status' => 'Show a table of spreads.',
84 ),
85 'aliases' => array('sps'),
86 // Example output engine data: command returns a deep array
87 // that can either be printed in table format or as a json array.
88 'engines' => array(
89 'outputformat' => array(
90 'default' => 'table',
91 'pipe-format' => 'json',
92 // Commands that return deep arrays will usually use
93 // machine-ids for the column data. A 'field-labels'
94 // item maps from the machine-id to a human-readable label.
95 'field-labels' => array(
96 'name' => 'Name',
97 'description' => 'Description',
98 'available' => 'Num',
99 'taste' => 'Taste',
100 ),
101 // In table format, the 'column-widths' item is consulted
102 // to determine the default weights for any named column.
103 'column-widths' => array(
104 'name' => 10,
105 'available' => 3,
106 ),
107 'require-engine-capability' => array('format-table'),
108 ),
109 ),
110 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH, // No bootstrap at all.
111 );
112
113 // Commandfiles may also add topics. These will appear in
114 // the list of topics when `drush topic` is executed.
115 // To view this topic, run `drush --include=/full/path/to/examples topic`
116 $items['sandwich-exposition'] = array(
117 'description' => 'Ruminations on the true meaning and philosophy of sandwiches.',
118 'hidden' => TRUE,
119 'topic' => TRUE,
120 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
121 'callback' => 'drush_print_file',
122 'callback arguments' => array(dirname(__FILE__) . '/sandwich-topic.txt'),
123 );
124
125 return $items;
126 }
127
128
129
130 /**
131 * Implementation of hook_drush_help().
132 *
133 * This function is called whenever a drush user calls
134 * 'drush help <name-of-your-command>'. This hook is optional. If a command
135 * does not implement this hook, the command's description is used instead.
136 *
137 * This hook is also used to look up help metadata, such as help
138 * category title and summary. See the comments below for a description.
139 *
140 * @param
141 * A string with the help section (prepend with 'drush:')
142 *
143 * @return
144 * A string with the help text for your command.
145 */
146 function sandwich_drush_help($section) {
147 switch ($section) {
148 case 'drush:make-me-a-sandwich':
149 return dt("This command will make you a delicious sandwich, just how you like it.");
150 // The 'title' meta item is used to name a group of
151 // commands in `drush help`. If a title is not defined,
152 // the default is "All commands in ___", with the
153 // specific name of the commandfile (e.g. sandwich).
154 // Command files with less than four commands will
155 // be placed in the "Other commands" section, _unless_
156 // they define a title. It is therefore preferable
157 // to not define a title unless the file defines a lot
158 // of commands.
159 case 'meta:sandwich:title':
160 return dt("Sandwich commands");
161 // The 'summary' meta item is displayed in `drush help --filter`,
162 // and is used to give a general idea what the commands in this
163 // command file do, and what they have in common.
164 case 'meta:sandwich:summary':
165 return dt("Automates your sandwich-making business workflows.");
166 }
167 }
168
169 /**
170 * Implementation of drush_hook_COMMAND_validate().
171 *
172 * The validate command should exit with
173 * `return drush_set_error(...)` to stop execution of
174 * the command. In practice, calling drush_set_error
175 * OR returning FALSE is sufficient. See drush.api.php
176 * for more details.
177 */
178 function drush_sandwich_make_me_a_sandwich_validate() {
179 if (drush_is_windows()) {
180 // $name = drush_get_username();
181 // TODO: implement check for elevated process using w32api
182 // as sudo is not available for Windows
183 // http://php.net/manual/en/book.w32api.php
184 // http://social.msdn.microsoft.com/Forums/en/clr/thread/0957c58c-b30b-4972-a319-015df11b427d
185 }
186 else {
187 $name = posix_getpwuid(posix_geteuid());
188 if ($name['name'] !== 'root') {
189 return drush_set_error('MAKE_IT_YOUSELF', dt('What? Make your own sandwich.'));
190 }
191 }
192 }
193
194 /**
195 * Example drush command callback. This is where the action takes place.
196 *
197 * The function name should be same as command name but with dashes turned to
198 * underscores and 'drush_commandfile_' prepended, where 'commandfile' is
199 * taken from the file 'commandfile.drush.inc', which in this case is 'sandwich'.
200 * Note also that a simplification step is also done in instances where
201 * the commandfile name is the same as the beginning of the command name,
202 * "drush_example_example_foo" is simplified to just "drush_example_foo".
203 * To also implement a hook that is called before your command, implement
204 * "drush_hook_pre_example_foo". For a list of all available hooks for a
205 * given command, run drush in --debug mode.
206 *
207 * If for some reason you do not want your hook function to be named
208 * after your command, you may define a 'callback' item in your command
209 * object that specifies the exact name of the function that should be
210 * called.
211 *
212 * In this function, all of Drupal's API is (usually) available, including
213 * any functions you have added in your own modules/themes.
214 *
215 * @see drush_invoke()
216 * @see drush.api.php
217 */
218 function drush_sandwich_make_me_a_sandwich($filling = 'ascii') {
219 $str_spreads = '';
220 // Read options with drush_get_option. Note that the options _must_
221 // be documented in the $items structure for this command in the 'command' hook.
222 // See `drush topic docs-commands` for more information.
223 if ($spreads = drush_get_option('spreads')) {
224 $list = implode(' and ', explode(',', $spreads));
225 $str_spreads = ' with just a dash of ' . $list;
226 }
227 $msg = dt('Okay. Enjoy this !filling sandwich!str_spreads.',
228 array('!filling' => $filling, '!str_spreads' => $str_spreads)
229 );
230 drush_print("\n" . $msg . "\n");
231
232 if (drush_get_context('DRUSH_NOCOLOR')) {
233 $filename = dirname(__FILE__) . '/sandwich-nocolor.txt';
234 }
235 else {
236 $filename = dirname(__FILE__) . '/sandwich.txt';
237 }
238 drush_print(file_get_contents($filename));
239 // Find out how many sandwiches have been served, and set
240 // the cached value to one greater.
241 $served = drush_sandwich_sandwiches_served();
242 drush_cache_set(drush_get_cid('sandwiches-served'), $served + 1);
243 }
244
245 /**
246 * Implementation of hook_drush_command() for sandwiches-served command.
247 *
248 * Demonstrates how to return a simple value that is transformed by
249 * the selected formatter to display either with a label (using the
250 * key-value formatter) or as the raw value itself (using the string formatter).
251 */
252 function drush_sandwich_sandwiches_served() {
253 $served = 0;
254 $served_object = drush_cache_get(drush_get_cid('sandwiches-served'));
255 if ($served_object) {
256 $served = $served_object->data;
257 }
258 // In the default format, key-value, this return value
259 // will print " Sandwiches Served : 1". In the default pipe
260 // format, only the array value ("1") is returned.
261 return $served;
262 }
263
264 /**
265 * Implementation of hook_drush_command() for spreads-status command.
266 *
267 * This ficticious command shows how a deep array can be constructed
268 * and used as a command return value that can be output by different
269 * output formatters.
270 */
271 function drush_sandwich_spreads_status() {
272 return array(
273 'ketchup' => array(
274 'name' => 'Ketchup',
275 'description' => 'Some say its a vegetable, but we know its a sweet spread.',
276 'available' => '7',
277 'taste' => 'sweet',
278 ),
279 'mayonnaise' => array(
280 'name' => 'Mayonnaise',
281 'description' => 'A nice dairy-free spead.',
282 'available' => '12',
283 'taste' => 'creamy',
284 ),
285 'mustard' => array(
286 'name' => 'Mustard',
287 'description' => 'Pardon me, but could you please pass that plastic yellow bottle?',
288 'available' => '8',
289 'taste' => 'tangy',
290 ),
291 'pickles' => array(
292 'name' => 'Pickles',
293 'description' => 'A necessary part of any sandwich that does not taste terrible.',
294 'available' => '63',
295 'taste' => 'tasty',
296 ),
297 );
298 }
299
300 /**
301 * Command argument complete callback. Provides argument
302 * values for shell completion.
303 *
304 * @return
305 * Array of popular fillings.
306 */
307 function sandwich_make_me_a_sandwich_complete() {
308 return array('values' => array('turkey', 'cheese', 'jelly', 'butter'));
309 }