|
| 1 | +Output Formats, Fields and Filters |
| 2 | +================================== |
| 3 | + |
| 4 | +Drush utilizes a powerful formatting and filtering system that provides the user with a lot of control over how output from various commands is rendered. |
| 5 | + |
| 6 | +* Output formats may be used to select the data type used to print the output. For example, many commands allow the user to select between a human-readable table, or various machine-parsable formats such as yaml and json. |
| 7 | +* Output fields may be used to select and order the data columns. |
| 8 | +* Output filters may be used to limit which data rows are printed based on logical expressions. |
| 9 | + |
| 10 | +Output Formats |
| 11 | +============== |
| 12 | + |
| 13 | +The `--format` option may be used to select the data format used to print the output of a command. Most commands that produce informative output about some object or system can transform their data into different formats. For example, the Drush `version` command may be printed in a human-readable table (the default), or in a json array: |
| 14 | +``` |
| 15 | +$ drush9 version |
| 16 | + Drush version : 9.5.0 |
| 17 | +$ drush9 version --format=json |
| 18 | +{ |
| 19 | + "drush-version": "9.5.0" |
| 20 | +} |
| 21 | +``` |
| 22 | +The available output formats are shown in the `help` for each command: |
| 23 | +``` |
| 24 | +$ drush help version |
| 25 | +Show drush version. |
| 26 | +
|
| 27 | +Options: |
| 28 | + --format=<json> Select output format. Available: json, string, var_export, yaml. Default is key-value. |
| 29 | +``` |
| 30 | + |
| 31 | +Output Fields |
| 32 | +============= |
| 33 | + |
| 34 | +If you wish to limit the number of columns produced by a command, use the `--fields` option. List the field names in the order they should be displayed: |
| 35 | +``` |
| 36 | +$ drush9 views:list --fields=machine-name,status |
| 37 | ++-------------------+----------+ |
| 38 | +| Machine name | Status | |
| 39 | ++-------------------+----------+ |
| 40 | +| block_content | Enabled | |
| 41 | +| comment | Enabled | |
| 42 | +| comments_recent | Enabled | |
| 43 | +| content | Enabled | |
| 44 | +| content_recent | Enabled | |
| 45 | +| files | Enabled | |
| 46 | +| frontpage | Enabled | |
| 47 | +| taxonomy_term | Enabled | |
| 48 | +| user_admin_people | Enabled | |
| 49 | +| watchdog | Enabled | |
| 50 | +| who_s_new | Enabled | |
| 51 | +| who_s_online | Enabled | |
| 52 | +| archive | Disabled | |
| 53 | +| glossary | Disabled | |
| 54 | ++-------------------+----------+ |
| 55 | +``` |
| 56 | +The available field names are shown in the `help` text: |
| 57 | +``` |
| 58 | +$ drush9 help views:list |
| 59 | +Get a list of all views in the system. |
| 60 | +
|
| 61 | +Options: |
| 62 | + --fields=FIELDS Available fields: Machine name (machine-name), |
| 63 | + Name (label), Description (description), Status |
| 64 | + (status), Tag (tag) [default: |
| 65 | + "machine-name,label,description,status"] |
| 66 | +``` |
| 67 | +Fields may be named either using their human-readable name, or via their machine name. |
| 68 | + |
| 69 | +Note also that some commands do not display all of their available data columns by default. To show all available fields, use `--fields=*` |
| 70 | + |
| 71 | +There is also a singluar form `--field` available. If this form is used, it will also force the output format to `string`. |
| 72 | +``` |
| 73 | +$ drush9 views:list --field=machine-name |
| 74 | +block_content |
| 75 | +comment |
| 76 | +comments_recent |
| 77 | +content |
| 78 | +content_recent |
| 79 | +files |
| 80 | +frontpage |
| 81 | +taxonomy_term |
| 82 | +user_admin_people |
| 83 | +watchdog |
| 84 | +who_s_new |
| 85 | +who_s_online |
| 86 | +archive |
| 87 | +glossary |
| 88 | +``` |
| 89 | + |
| 90 | +Output Filters |
| 91 | +============== |
| 92 | + |
| 93 | +A number of Drush commands that output tabular data support a `--filter` option that allows rows from the output to be selected with simple logic expressions. |
| 94 | + |
| 95 | +In its simplest form, the `--filter` option takes a string that indicates the value to filter by in the command's *default filter field*. For example, the `role:list` command's default filter field is `perms`; the output of the `role:list` command may be limited to only those roles that have a specified permission: |
| 96 | +``` |
| 97 | +$ drush role:list --filter='post comments' |
| 98 | +authenticated: |
| 99 | + label: 'Authenticated user' |
| 100 | + perms: |
| 101 | + - 'access comments' |
| 102 | + - 'access content' |
| 103 | + - 'access shortcuts' |
| 104 | + - 'access site-wide contact form' |
| 105 | + - 'access user contact forms' |
| 106 | + - 'post comments' |
| 107 | + - 'search content' |
| 108 | + - 'skip comment approval' |
| 109 | + - 'use text format basic_html' |
| 110 | +``` |
| 111 | +Note that not all commands have a default filter field. |
| 112 | + |
| 113 | +Other fields in the output may be searched by using a simple expression in the `--filter` term. For example, to list only the enabled extensions with the `pm:list` command, you could run: |
| 114 | +``` |
| 115 | +$ drush pm:list --filter='status=enabled' |
| 116 | +``` |
| 117 | +To search for fields that contain a string using the operator `*=`, or match a regular expression with the `~=` operator. For example, to find all views whose machine name contains the word "content": |
| 118 | +``` |
| 119 | +drush views:list --filter='machine-name*=content' |
| 120 | +``` |
| 121 | +To use a regular expression to find any core requirement notice whose title contains either "php" or "gd" |
| 122 | +``` |
| 123 | +drush core:requirements --filter='title~=#(php|gd)#i' |
| 124 | +``` |
| 125 | +Finally, filter expressions may also use logical-and (`&&`) or logical-or (`||`) operations to separate multiple terms. Parenthesis are not supported. For example, to search both the `title` and `severity` fields in the `core:requirements` command: |
| 126 | +``` |
| 127 | +drush core:requirements --filter='title~=#(php|gd)#i&&severity=warning' |
| 128 | +``` |
| 129 | + |
| 130 | +The `=` and `*=` operators always use case-insensitive comparisons. The `~=` operator is case-sensitive, unless the `i` [PCRE modifier](http://php.net/manual/en/reference.pcre.pattern.modifiers.php) is used, as shown in the previous example. |
| 131 | + |
| 132 | +Comparison of Filters with Grep |
| 133 | +------------------------------- |
| 134 | + |
| 135 | +Using the `--filter` feature is similar to using `grep`. The main difference is that the filter feature does a semantic search, which is to say that it explicitly compares against the data in specific fields. In comparison, the `grep` command does a line-based search. |
| 136 | + |
| 137 | +Show only results where the severity is "warning": |
| 138 | + |
| 139 | +`drush core:requirements --filter='severity=warning'` |
| 140 | + |
| 141 | +Show only lines that contain the string "warning" (either in the severity field, or somewhere else on the line): |
| 142 | + |
| 143 | +`drush core:requirements | grep -i warning` |
| 144 | + |
| 145 | +The table below compares and contrasts the two ways of searching. |
| 146 | + |
| 147 | +| Feature | --filter | grep | |
| 148 | +| ----------------------- | ------------------- | -------------------------- | |
| 149 | +| Regular expressions | Yes, with `~=` | Yes | |
| 150 | +| Word-wrapped field data | Searched correctly | Might cause false negative | |
| 151 | +| Search just one field | Yes | Might get false positives | |
| 152 | +| Search multiple fields | Yes, with `||`/`&&` | Yes (line-based searching) | |
| 153 | +| Searching hides header | No | Yes (unless it matches) | |
0 commit comments