--- /dev/null
+<?php
+
+/**
+ * @file
+ * Core drush output formats.
+ */
+
+/**
+ * @return drush_outputformat The selected output format engine
+ */
+function drush_get_outputformat() {
+ return drush_get_engine('outputformat');
+}
+
+/**
+ * Dynamically switch to a new output format. Does NOT override
+ * user-selected output format.
+ */
+function drush_set_default_outputformat($format, $metadata = array()) {
+ $command = drush_get_command();
+ $command['engines']['outputformat']['default'] = $format;
+ $outputformat = drush_load_command_engine($command, 'outputformat', $metadata);
+}
+
+/**
+ * Given a command name or a command record, return the
+ * command formatter that is used to process that command's output.
+ */
+function drush_get_command_format_metadata($command, $metadata = array()) {
+ $commands = drush_get_commands();
+ if (!is_array($command) && array_key_exists($command, $commands)) {
+ $command = $commands[$command];
+ }
+ return drush_get_command_engine_config($command, 'outputformat', $metadata);
+}
+
+/**
+ * Implementation of hook_drush_engine_type_info().
+ */
+function outputformat_drush_engine_type_info() {
+ $info = array();
+ $info['outputformat'] = array(
+ 'description' => 'Output formatting options selection and use.',
+ 'topic' => 'docs-output-formats',
+ 'topic-file' => 'docs/output-formats.md',
+ 'combine-help' => TRUE,
+ 'option' => 'format',
+ 'options' => array(
+ 'format' => array(
+ 'description' => 'Select output format.',
+ 'example-value' => 'json',
+ ),
+ 'fields' => array(
+ 'description' => 'Fields to output.',
+ 'example-value' => 'field1,field2',
+ 'value' => 'required',
+ 'list' => TRUE,
+ ),
+ 'list-separator' => array(
+ 'description' => 'Specify how elements in a list should be separated. In lists of lists, this applies to the elements in the inner lists.',
+ 'hidden' => TRUE,
+ ),
+ 'line-separator' => array(
+ 'description' => 'In nested lists of lists, specify how the outer lists ("lines") should be separated.',
+ 'hidden' => TRUE,
+ ),
+ 'field-labels' => array(
+ 'description' => 'Add field labels before first line of data. Default is on; use --no-field-labels to disable.',
+ 'default' => '1',
+ 'key' => 'include-field-labels',
+ ),
+ ),
+ // Allow output formats to declare their
+ // "output data type" instead of their
+ // "required engine capability" for readability.
+ 'config-aliases' => array(
+ 'output-data-type' => 'require-engine-capability',
+ ),
+ );
+ return $info;
+}
+
+/**
+ * Implements hook_drush_engine_ENGINE_TYPE().
+ *
+ * The output format types supported are represented by
+ * the 'engine-capabilities' of the output format engine.
+ * The different capabilities include:
+ *
+ * format-single: A simple string.
+ *
+ * format-list: An associative array where the key
+ * is usually the row label, and the value
+ * is a simple string. Some list formatters
+ * render the label, and others (like
+ * "list" and "csv") throw it away.
+ *
+ * format-table: An associative array, where the key
+ * is the row id, and the value is the
+ * column data. The column data is also
+ * an associative array where the key
+ * is the column id and the value is the
+ * cell data. The cell data should usually
+ * be a simple string; however, some
+ * formatters can recursively format their
+ * cell contents before rendering (e.g. if
+ * a cell contains a list of items in an array).
+ *
+ * These definitions align with the declared 'output-data-type'
+ * declared in command records. @see drush_parse_command().
+ *
+ * Any output format that does not declare any engine capabilities
+ * is expected to be able to render any php data structure that is
+ * passed to it.
+ */
+function outputformat_drush_engine_outputformat() {
+ $common_topic_example = array(
+ "a" => array("b" => 2, "c" => 3),
+ "d" => array("e" => 5, "f" => 6)
+ );
+
+ $engines = array();
+ $engines['table'] = array(
+ 'description' => 'A formatted, word-wrapped table.',
+ 'engine-capabilities' => array('format-table'),
+ );
+ $engines['key-value'] = array(
+ 'description' => 'A formatted list of key-value pairs.',
+ 'engine-capabilities' => array('format-single', 'format-list', 'format-table'),
+ 'hidden' => TRUE,
+ );
+ $engines['key-value-list'] = array(
+ 'implemented-by' => 'list',
+ 'list-item-type' => 'key-value',
+ 'description' => 'A list of formatted lists of key-value pairs.',
+ 'list-field-selection-control' => 1,
+ 'engine-capabilities' => array('format-table'),
+ 'hidden' => TRUE,
+ );
+ $engines['json'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'Javascript Object Notation.',
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['string'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'A simple string.',
+ 'engine-capabilities' => array('format-single'),
+ );
+ $engines['message'] = array(
+ 'machine-parsable' => FALSE, // depends on the label....
+ 'hidden' => TRUE,
+ );
+ $engines['print-r'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'Output via php print_r function.',
+ 'verbose-only' => TRUE,
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['var_export'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'An array in executable php format.',
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['yaml'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'Yaml output format.',
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['php'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'A serialized php string.',
+ 'verbose-only' => TRUE,
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['config'] = array(
+ 'machine-parsable' => TRUE,
+ 'implemented-by' => 'list',
+ 'list-item-type' => 'var_export',
+ 'description' => "A configuration file in executable php format. The variable name is \"config\", and the variable keys are taken from the output data array's keys.",
+ 'metadata' => array(
+ 'variable-name' => 'config',
+ ),
+ 'list-field-selection-control' => -1,
+ 'engine-capabilities' => array('format-list','format-table'),
+ 'verbose-only' => TRUE,
+ );
+ $engines['list'] = array(
+ 'machine-parsable' => TRUE,
+ 'list-item-type' => 'string',
+ 'description' => 'A simple list of values.',
+ // When a table is printed as a list, only the array keys of the rows will print.
+ 'engine-capabilities' => array('format-list', 'format-table'),
+ 'topic-example' => array('a', 'b', 'c'),
+ );
+ $engines['nested-csv'] = array(
+ 'machine-parsable' => TRUE,
+ 'implemented-by' => 'list',
+ 'list-separator' => ',',
+ 'list-item-type' => 'csv-or-string',
+ 'hidden' => TRUE,
+ );
+ $engines['csv-or-string'] = array(
+ 'machine-parsable' => TRUE,
+ 'hidden' => TRUE,
+ );
+ $engines['csv'] = array(
+ 'machine-parsable' => TRUE,
+ 'implemented-by' => 'list',
+ 'list-item-type' => 'nested-csv',
+ 'labeled-list' => TRUE,
+ 'description' => 'A list of values, one per row, each of which is a comma-separated list of values.',
+ 'engine-capabilities' => array('format-table'),
+ 'topic-example' => array(array('a', 12, 'a@one.com'),array('b', 17, 'b@two.com')),
+ );
+ $engines['variables'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'A list of php variable assignments.',
+ 'engine-capabilities' => array('format-table'),
+ 'verbose-only' => TRUE,
+ 'list-field-selection-control' => -1,
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['labeled-export'] = array(
+ 'machine-parsable' => TRUE,
+ 'description' => 'A list of php exports, labeled with a name.',
+ 'engine-capabilities' => array('format-table'),
+ 'verbose-only' => TRUE,
+ 'implemented-by' => 'list',
+ 'list-item-type' => 'var_export',
+ 'metadata' => array(
+ 'label-template' => '!label: !value',
+ ),
+ 'list-field-selection-control' => -1,
+ 'topic-example' => $common_topic_example,
+ );
+ $engines['html'] = array(
+ 'machine-parsable' => FALSE,
+ 'description' => 'An HTML representation',
+ 'engine-capabilities' => array('format-table'),
+ );
+ return $engines;
+}
+
+/**
+ * Implements hook_drush_command_alter
+ */
+function outputformat_drush_command_alter(&$command) {
+ // In --pipe mode, change the default format to the default pipe format, or
+ // to json, if no default pipe format is given.
+ if (drush_get_context('DRUSH_PIPE') && (isset($command['engines']['outputformat']))) {
+ $default_format = isset($command['engines']['outputformat']['pipe-format']) ? $command['engines']['outputformat']['pipe-format'] : 'json';
+ $command['engines']['outputformat']['default'] = $default_format;
+ }
+}
+
+/**
+ * Implements hook_drush_help_alter().
+ */
+function outputformat_drush_help_alter(&$command) {
+ if (isset($command['engines']['outputformat'])) {
+ $outputformat = $command['engines']['outputformat'];
+ // If the command defines specific field labels,
+ // then modify the help for --fields to include
+ // specific information about the available fields.
+ if (isset($outputformat['field-labels'])) {
+ $all_fields = array();
+ $all_fields_description = array();
+ foreach ($outputformat['field-labels'] as $field => $human_readable) {
+ $all_fields[] = $field;
+ if ((strtolower($field) != strtolower($human_readable)) && !array_key_exists(strtolower($human_readable), $outputformat['field-labels'])) {
+ $all_fields_description[] = $field . dt(" (or '!other')", array('!other' => strtolower($human_readable)));
+ }
+ else {
+ $all_fields_description[] = $field;
+ }
+ }
+ $field_defaults = isset($outputformat['fields-default']) ? $outputformat['fields-default'] : $all_fields;
+ $command['options']['fields']['example-value'] = implode(', ', $field_defaults);
+ $command['options']['fields']['description'] .= ' '. dt('All available fields are: !fields.', array('!fields' => implode(', ', $all_fields_description)));
+ if (isset($outputformat['fields-default'])) {
+ $command['options']['full']['description'] = dt("Show the full output, with all fields included.");
+ }
+ }
+ else {
+ // If the command does not define specific field labels,
+ // then hide the help for --fields unless the command
+ // uses output format engines that format tables.
+ if (isset($outputformat['require-engine-capability']) && is_array($outputformat['require-engine-capability'])) {
+ if (!in_array('format-table', $outputformat['require-engine-capability'])) {
+ unset($command['options']['fields']);
+ unset($command['options']['field-labels']);
+ }
+ }
+ // If the command does define output formats, but does not
+ // define fields, then just hide the help for the --fields option.
+ else {
+ $command['options']['fields']['hidden'] = TRUE;
+ $command['options']['field-labels']['hidden'] = TRUE;
+ }
+ }
+
+ // If the command defines a default pipe format, then
+ // add '--pipe Equivalent to --format=<pipe-default>'.
+ if (isset($outputformat['pipe-format'])) {
+ if (isset($command['options']['pipe'])) {
+ $command['options']['pipe'] .= ' ';
+ }
+ else {
+ $command['options']['pipe'] = '';
+ }
+ if (isset($outputformat['pipe-metadata']['message-template'])) {
+ $command['options']['pipe'] .= dt('Displays output in the form "!message"', array('!message' => $outputformat['pipe-metadata']['message-template']));
+ }
+ else {
+ $command['options']['pipe'] .= dt("Equivalent to --format=!default.", array('!default' => $outputformat['pipe-format']));
+ }
+ }
+ }
+}
+
+/**
+ * Implements hook_drush_engine_topic_additional_text().
+ */
+function outputformat_drush_engine_topic_additional_text($engine, $instance, $config) {
+ $result = array();
+
+ // If the output format engine has a 'topic-example' in
+ // its configuration, then format the provided array using
+ // the output formatter, and insert the result of the
+ // transform into the topic text.
+ if ($engine == 'outputformat') {
+ if (array_key_exists('topic-example', $config)) {
+ $code = $config['topic-example'];
+ $formatted = drush_format($code, array(), $instance);
+ $result[] = dt("Code:\n\nreturn !code;\n\nOutput with --format=!instance:\n\n!formatted", array('!code' => var_export($code, TRUE), '!instance' => $instance, '!formatted' => $formatted));
+ }
+ }
+
+ return $result;
+}
+
+/**
+ * Interface for output format engines.
+ */
+class drush_outputformat {
+ function __construct($config) {
+ $config += array(
+ 'column-widths' => array(),
+ 'field-mappings' => array(),
+ 'engine-info' => array(),
+ );
+ $config['engine-info'] += array(
+ 'machine-parsable' => FALSE,
+ 'metadata' => array(),
+ );
+ $config += $config['engine-info']['metadata'];
+ $this->engine_config = $config;
+ }
+ function format_error($message) {
+ return drush_set_error('DRUSH_FORMAT_ERROR', dt("The output data could not be processed by the selected format '!type'. !message", array('!type' => $this->engine, '!message' => $message)));
+ }
+ function formatter_type() {
+ return $this->engine;
+ }
+ function is_list() {
+ return FALSE;
+ }
+ function formatter_is_simple_list() {
+ if (!isset($this->sub_engine)) {
+ return false;
+ }
+ return ($this->formatter_type() == 'list') && ($this->sub_engine->supports_single_only());
+ }
+ function data_type($metadata) {
+ if (isset($metadata['metameta']['require-engine-capability']) && is_array($metadata['metameta']['require-engine-capability'])) {
+ return $metadata['metameta']['require-engine-capability'][0];
+ }
+ if (isset($metadata['require-engine-capability']) && is_array($metadata['require-engine-capability'])) {
+ return $metadata['require-engine-capability'][0];
+ }
+ return 'unspecified';
+ }
+ function supported_data_types($metadata = NULL) {
+ if ($metadata == NULL) {
+ $metadata = $this->engine_config;
+ }
+ if (isset($metadata['metameta']['engine-info']['engine-capabilities'])) {
+ return $metadata['metameta']['engine-info']['engine-capabilities'];
+ }
+ if (isset($metadata['engine-info']['engine-capabilities'])) {
+ return $metadata['engine-info']['engine-capabilities'];
+ }
+ return array();
+ }
+ function supports_single_only($metadata = NULL) {
+ $supported = $this->supported_data_types($metadata);
+ return (count($supported) == 1) && ($supported[0] == 'format-single');
+ }
+ function get_info($key) {
+ if (array_key_exists($key, $this->engine_config)) {
+ return $this->engine_config[$key];
+ }
+ elseif (isset($this->sub_engine)) {
+ return $this->sub_engine->get_info($key);
+ }
+ return FALSE;
+ }
+ /**
+ * Perform pre-processing and then format() the $input.
+ */
+ function process($input, $metadata = array()) {
+ $metadata = array_merge_recursive($metadata, $this->engine_config);
+ if (isset($metadata['private-fields']) && is_array($input)) {
+ if (!drush_get_option('show-passwords', FALSE)) {
+ if (!is_array($metadata['private-fields'])) {
+ $metadata['private-fields'] = array($metadata['private-fields']);
+ }
+ foreach ($metadata['private-fields'] as $private) {
+ drush_unset_recursive($input, $private);
+ }
+ }
+ }
+ if (isset($metadata[$this->engine . '-metadata'])) {
+ $engine_specific_metadata = $metadata[$this->engine . '-metadata'];
+ unset($metadata[$this->engine . '-metadata']);
+ $metadata = array_merge($metadata, $engine_specific_metadata);
+ }
+ if ((drush_get_context('DRUSH_PIPE')) && (isset($metadata['pipe-metadata']))) {
+ $pipe_specific_metadata = $metadata['pipe-metadata'];
+ unset($metadata['pipe-metadata']);
+ $metadata = array_merge($metadata, $pipe_specific_metadata);
+ }
+ $machine_parsable = $this->engine_config['engine-info']['machine-parsable'];
+ $formatter_type = $machine_parsable ? 'parsable' : 'formatted';
+ if ((!$machine_parsable) && is_bool($input)) {
+ $input = $input ? 'TRUE' : 'FALSE';
+ }
+
+ // Run $input through any filters that are specified for this formatter.
+ if (isset($metadata[$formatter_type . '-filter'])) {
+ $filters = $metadata[$formatter_type . '-filter'];
+ if (!is_array($filters)) {
+ $filters = array($filters);
+ }
+ foreach ($filters as $filter) {
+ if (function_exists($filter)) {
+ $input = $filter($input, $metadata);
+ }
+ }
+ }
+ if (isset($metadata['field-labels'])) {
+ foreach (drush_hide_output_fields() as $hidden_field) {
+ unset($metadata['field-labels'][$hidden_field]);
+ }
+ }
+ return $this->format($input, $metadata);
+ }
+ function format($input, $metadata) {
+ return $input;
+ }
+}
+
+/**
+ * Specify that certain fields should not appear in the resulting output.
+ */
+function drush_hide_output_fields($fields_to_hide = array()) {
+ $already_hidden = drush_get_context('DRUSH_HIDDEN_OUTPUT_FIELDS');
+ if (!is_array($fields_to_hide)) {
+ $fields_to_hide = array($fields_to_hide);
+ }
+ $result = array_merge($already_hidden, $fields_to_hide);
+ drush_set_context('DRUSH_HIDDEN_OUTPUT_FIELDS', $result);
+ return $result;
+}