function drush_choice
8.0.x drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value', $widths = array()) |
6.x drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value', $widths = array()) |
7.x drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value', |
3.x drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value') |
4.x drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value') |
5.x drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value', $widths = array()) |
master drush.inc | drush_choice($options, $prompt = 'Enter a number.', $label = '!value', $widths = array()) |
Ask the user to select an item from a list. From a provided associative array, drush_choice will display all of the questions, numbered from 1 to N, and return the item the user selected. "0" is always cancel; entering a blank line is also interpreted as cancelling.
Parameters
$options: A list of questions to display to the user. The KEYS of the array are the result codes to return to the caller; the VALUES are the messages to display on each line. Special keys of the form '-- something --' can be provided as separator between choices groups. Separator keys don't alter the numbering.
$prompt: The message to display to the user prompting for input.
$label: Controls the display of each line. Defaults to '!value', which displays the value of each item in the $options array to the user. Use '!key' to display the key instead. In some instances, it may be useful to display both the key and the value; for example, if the key is a user id and the value is the user name, use '!value (uid=!key)'.
Related topics
- drush_cache_command_clear in commands/
core/ cache.drush.inc - Command callback for drush cache-clear.
- drush_choice_multiple in includes/
drush.inc - Ask the user to select multiple items from a list. This is a wrapper around drush_choice, that repeats the selection process, allowing users to toggle a number of items in a list. The number of values that can be constrained by both min and max: the…
- drush_config_edit in commands/
core/ config.drush.inc - Edit command callback.
- drush_config_export in commands/
core/ config.drush.inc - Command callback: Export config to specified directory (usually sync).
- drush_config_import in commands/
core/ config.drush.inc - Command callback. Import from specified config directory (defaults to sync).
File
- includes/
drush.inc, line 448 - The drush API implementation and helpers.
Code
function drush_choice($options, $prompt = 'Enter a number.', $label = '!value', $widths = array()) {
drush_print(dt($prompt));
// Preflight so that all rows will be padded out to the same number of columns
$array_pad = 0;
foreach ($options as $key => $option) {
if (is_array($option) && (count($option) > $array_pad)) {
$array_pad = count($option);
}
}
$rows[] = array_pad(array('[0]', ':', 'Cancel'), $array_pad + 2, '');
$selection_number = 0;
foreach ($options as $key => $option) {
if ((substr($key, 0, 3) == '-- ') && (substr($key, -3) == ' --')) {
$rows[] = array_pad(array('', '', $option), $array_pad + 2, '');
}
else {
$selection_number++;
$row = array("[$selection_number]", ':');
if (is_array($option)) {
$row = array_merge($row, $option);
}
else {
$row[] = dt($label, array('!number' => $selection_number, '!key' => $key, '!value' => $option));
}
$rows[] = $row;
$selection_list[$selection_number] = $key;
}
}
drush_print_table($rows, FALSE, $widths);
drush_print_pipe(array_keys($options));
// If the user specified --choice, then make an
// automatic selection. Cancel if the choice is
// not an available option.
if (($choice = drush_get_option('choice', FALSE)) !== FALSE) {
// First check to see if $choice is one of the symbolic options
if (array_key_exists($choice, $options)) {
return $choice;
}
// Next handle numeric selections
elseif (array_key_exists($choice, $selection_list)) {
return $selection_list[$choice];
}
return FALSE;
}
// If the user specified --no, then cancel; also avoid
// getting hung up waiting for user input in --pipe and
// backend modes. If none of these apply, then wait,
// for user input and return the selected result.
if (!drush_get_context('DRUSH_NEGATIVE') && !drush_get_context('DRUSH_AFFIRMATIVE') && !drush_get_context('DRUSH_PIPE')) {
while ($line = trim(fgets(STDIN))) {
if (array_key_exists($line, $selection_list)) {
return $selection_list[$line];
}
}
}
// We will allow --yes to confirm input if there is only
// one choice; otherwise, --yes will cancel to avoid ambiguity
if (drush_get_context('DRUSH_AFFIRMATIVE') && (count($options) == 1)) {
return $selection_list[1];
}
return FALSE;
}