Add --filter to many commands

composer.json

@@ -36,7 +36,8 @@
     "composer/semver": "^1.4",
     "consolidation/annotated-command": "^2.9.1",
     "consolidation/config": "^1.1.0",
-    "consolidation/output-formatters": "^3.1.12",
+    "consolidation/filter-via-dot-access-data": "^0.4",
+    "consolidation/output-formatters": "^3.3.1",
     "consolidation/robo": "^1.1.5",
     "consolidation/site-alias": "^1.1.5",
     "grasmash/yaml-expander": "^1.1.1",

docs/output-formats-filters.md

@@ -0,0 +1,153 @@
+Output Formats, Fields and Filters
+==================================
+
+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.
+
+* 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.
+* Output fields may be used to select and order the data columns.
+* Output filters may be used to limit which data rows are printed based on logical expressions.
+
+Output Formats
+==============
+
+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:
+```
+$ drush9 version
+ Drush version : 9.5.0
+$ drush9 version --format=json
+{
+    "drush-version": "9.5.0"
+}
+```
+The available output formats are shown in the `help` for each command:
+```
+$ drush help version
+Show drush version.
+
+Options:
+ --format=<json>    Select output format. Available: json, string, var_export, yaml. Default is key-value.
+```
+
+Output Fields
+=============
+
+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:
+```
+$ drush9 views:list --fields=machine-name,status
++-------------------+----------+
+| Machine name      | Status   |
++-------------------+----------+
+| block_content     | Enabled  |
+| comment           | Enabled  |
+| comments_recent   | Enabled  |
+| content           | Enabled  |
+| content_recent    | Enabled  |
+| files             | Enabled  |
+| frontpage         | Enabled  |
+| taxonomy_term     | Enabled  |
+| user_admin_people | Enabled  |
+| watchdog          | Enabled  |
+| who_s_new         | Enabled  |
+| who_s_online      | Enabled  |
+| archive           | Disabled |
+| glossary          | Disabled |
++-------------------+----------+
+```
+The available field names are shown in the `help` text:
+```
+$ drush9 help views:list
+Get a list of all views in the system.
+
+Options:
+  --fields=FIELDS   Available fields: Machine name (machine-name),     
+                    Name (label), Description (description), Status    
+                    (status), Tag (tag) [default:                      
+                    "machine-name,label,description,status"]           
+```
+Fields may be named either using their human-readable name, or via their machine name.
+
+Note also that some commands do not display all of their available data columns by default. To show all available fields, use `--fields=*`
+
+There is also a singluar form `--field` available. If this form is used, it will also force the output format to `string`.
+```
+$ drush9 views:list --field=machine-name 
+block_content
+comment
+comments_recent
+content
+content_recent
+files
+frontpage
+taxonomy_term
+user_admin_people
+watchdog
+who_s_new
+who_s_online
+archive
+glossary
+```
+
+Output Filters
+==============
+
+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.
+
+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:
+```
+$ drush role:list --filter='post comments'
+authenticated:
+  label: 'Authenticated user'
+  perms:
+    - 'access comments'
+    - 'access content'
+    - 'access shortcuts'
+    - 'access site-wide contact form'
+    - 'access user contact forms'
+    - 'post comments'
+    - 'search content'
+    - 'skip comment approval'
+    - 'use text format basic_html'
+```
+Note that not all commands have a default filter field.
+
+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:
+```
+$ drush pm:list --filter='status=enabled'
+```
+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":
+```
+drush views:list --filter='machine-name*=content'
+```
+To use a regular expression to find any core requirement notice whose title contains either "php" or "gd"
+```
+drush core:requirements --filter='title~=#(php|gd)#i'
+```
+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:
+```
+drush core:requirements --filter='title~=#(php|gd)#i&&severity=warning'
+```
+
+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.
+
+Comparison of Filters with Grep
+-------------------------------
+
+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.
+
+Show only results where the severity is "warning":
+
+`drush core:requirements --filter='severity=warning'`
+
+Show only lines that contain the string "warning" (either in the severity field, or somewhere else on the line):
+
+`drush core:requirements | grep -i warning`
+
+The table below compares and contrasts the two ways of searching.
+
+| Feature                 | --filter            | grep                       |
+| ----------------------- | ------------------- | -------------------------- |
+| Regular expressions     | Yes, with `~=`      | Yes                        |
+| Word-wrapped field data | Searched correctly  | Might cause false negative |
+| Search just one field   | Yes                 | Might get false positives  |
+| Search multiple fields  | Yes, with `||`/`&&` | Yes (line-based searching) |
+| Searching hides header  | No                  | Yes (unless it matches)    |

examples/Commands/ArtCommands.php

@@ -65,6 +65,7 @@ public function art($art = '')
      *   path: Path
      * @default-fields name,description
      *
+     * @filter-default-field name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function listArt($options = ['format' => 'table'])

shippable.yml

@@ -18,7 +18,8 @@ build:
     - rm $HOME/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini
     # Install / update our tools
     - composer self-update
-    - composer install --no-interaction
+    - mkdir phpcs
+    - COMPOSER_BIN_DIR=$(pwd)/vendor/bin composer --working-dir=phpcs require "squizlabs/php_codesniffer:^2.7"
     # Run code style and linting tools
     - composer cs
     - composer lint

src/Application.php

@@ -316,6 +316,7 @@ public function configureAndRegisterCommands(InputInterface $input, OutputInterf
 
         $discovery = $this->commandDiscovery();
         $commandClasses = $discovery->discover($commandfileSearchpath, '\Drush');
+        $commandClasses[] = \Consolidation\Filter\Hooks\FilterHooks::class;
 
         $this->loadCommandClasses($commandClasses);
 

src/Command/DrushCommandInfoAlterer.php

@@ -0,0 +1,22 @@
+<?php
+namespace Drush\Command;
+
+use Consolidation\AnnotatedCommand\CommandInfoAltererInterface;
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+
+class DrushCommandInfoAlterer implements CommandInfoAltererInterface
+{
+    public function alterCommandInfo(CommandInfo $commandInfo, $commandFileInstance)
+    {
+        // If a command has a @filter-default-field annotation, that
+        // implies that it also has an implicit @filter-output annotation.
+        if ($commandInfo->hasAnnotation('filter-default-field') && !$commandInfo->hasAnnotation('filter-output')) {
+            $commandInfo->addAnnotation('filter-output', true);
+        }
+        // Automatically add the help topic for output formatters to
+        // any command that has any annotations related to output filters
+        if ($commandInfo->hasAnnotation('filter-output') || $commandInfo->hasAnnotation('field-labels')) {
+            $commandInfo->addAnnotation('topics', 'docs:output-formats-filters');
+        }
+    }
+}

src/Commands/core/CoreCommands.php

@@ -26,6 +26,7 @@ class CoreCommands extends DrushCommands implements SiteAliasManagerAwareInterfa
      * @default-fields name,description
      * @aliases core-global-options
      *
+     * @filter-default-field name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function globalOptions($options = ['format' => 'table'])

src/Commands/core/DocsCommands.php

@@ -77,6 +77,20 @@ public function configExport()
         self::printFile(DRUSH_BASE_PATH. '/docs/config-exporting.md');
     }
 
+    /**
+     * Output formatters and filters: how to control the output produced by Drush commands
+     *
+     * @command docs:output-formats-filters
+     * @aliases docs:output
+     * @aliases docs-output
+     * @hidden
+     * @topic
+     */
+    public function outputFormatsFilters()
+    {
+        self::printFile(DRUSH_BASE_PATH. '/docs/output-formats-filters.md');
+    }
+
     /**
      * Creating site aliases for running Drush on remote sites.
      *

src/Commands/core/SiteCommands.php

@@ -7,7 +7,7 @@
 use Consolidation\SiteAlias\SiteAliasFileDiscovery;
 use Consolidation\SiteAlias\SiteAliasManagerAwareInterface;
 use Consolidation\SiteAlias\SiteAliasManagerAwareTrait;
-use Consolidation\OutputFormatters\StructuredData\ListDataFromKeys;
+use Consolidation\OutputFormatters\StructuredData\UnstructuredListData;
 use Drush\Utils\StringUtils;
 use Symfony\Component\Console\Input\Input;
 use Symfony\Component\Console\Output\Output;
@@ -103,9 +103,10 @@ public function siteSet($site = '@none')
      * @param string $site Site alias or site specification.
      * @param array $options
      *
-     * @return \Consolidation\OutputFormatters\StructuredData\ListDataFromKeys
+     * @return \Consolidation\OutputFormatters\StructuredData\UnstructuredListData
      * @throws \Exception
      * @aliases sa
+     * @filter-default-field id
      * @usage drush site:alias
      *   List all alias records known to drush.
      * @usage drush site:alias @dev
@@ -119,13 +120,13 @@ public function siteAlias($site = null, $options = ['format' => 'yaml'])
         // multiple sites.
         $aliasList = $this->siteAliasManager()->getMultiple($site);
         if (is_array($aliasList) && !empty($aliasList)) {
-            return new ListDataFromKeys($this->siteAliasExportList($aliasList, $options));
+            return new UnstructuredListData($this->siteAliasExportList($aliasList, $options));
         }
 
         // Next check for a specific alias or a site specification.
         $aliasRecord = $this->siteAliasManager()->get($site);
         if ($aliasRecord !== false) {
-            return new ListDataFromKeys([$aliasRecord->name() => $aliasRecord->export()]);
+            return new UnstructuredListData([$aliasRecord->name() => $aliasRecord->export()]);
         }
 
         if ($site) {

src/Commands/core/UpdateDBCommands.php

@@ -116,6 +116,7 @@ public function entityUpdates($options = ['cache-clear' => true])
      *   description: Description
      *   type: Type
      * @default-fields module,update_id,type,description
+     * @filter-default-field type
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function updatedbStatus($options = ['format'=> 'table', 'entity-updates' => true, 'post-updates' => true])

src/Commands/generate/Generators/Drush/default-methods.twig

@@ -31,6 +31,7 @@
    * @command {{  machine_name }}:token
    * @aliases token
    *
+   * @filter-default-field name
    * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
    */
   public function token($options = ['format' => 'table']) {

src/Commands/pm/SecurityUpdateCommands.php

@@ -38,6 +38,7 @@ class SecurityUpdateCommands extends DrushCommands
      *   min-version: Suggested version
      * @default-fields name,version,min-version
      *
+     * @filter-default-field name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      *
      * @throws \Exception

src/Drupal/Commands/config/ConfigCommands.php

@@ -221,6 +221,7 @@ public function delete($config_name, $key = null)
      *   state: State
      * @default-fields name,state
      * @aliases cst,config-status
+     * @filter-default-field name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function status($options = ['state' => 'Only in DB,Only in sync dir,Different', 'prefix' => self::REQ, 'label' => self::REQ])

src/Drupal/Commands/core/DrupalCommands.php

@@ -84,6 +84,7 @@ public function cron()
      *   description: Description
      *   value: Summary
      * @default-fields title,severity,value
+     * @filter-default-field severity
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function requirements($options = ['format' => 'table', 'severity' => -1, 'ignore' => ''])

src/Drupal/Commands/core/LanguageCommands.php

@@ -102,6 +102,7 @@ public function add($langcode, $options = ['skip-translations' => false])
      *   default: Default
      *   locked: Locked
      * @default-fields language,direction,default
+     * @filter-default-field language
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function info()

src/Drupal/Commands/core/QueueCommands.php

@@ -98,6 +98,7 @@ public function run($name, $options = ['time-limit' => self::REQ])
      *   items: Items
      *   class: Class
      *
+     * @filter-default-field queue
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function qList($options = ['format' => 'table'])

src/Drupal/Commands/core/RoleCommands.php

@@ -106,8 +106,6 @@ public function roleRemovePerm($machine_name, $permissions)
      * then all of the roles that have been granted that permission will be listed.
      *
      * @command role:list
-     * @validate-permissions filter
-     * @option filter Limits the list of roles to only those that have been assigned the specified permission.
      * @usage drush role:list --filter='administer nodes'
      *   Display a list of roles that have the administer nodes permission assigned.
      * @aliases rls,role-list
@@ -116,16 +114,14 @@ public function roleRemovePerm($machine_name, $permissions)
      *   label: Role Label
      *   perms: Permissions
      *
+     * @filter-default-field perms
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
-    public function roleList($options = ['format' => 'yaml', 'filter' => self::REQ])
+    public function roleList($options = ['format' => 'yaml'])
     {
         $rows = [];
         $roles = Role::loadMultiple();
         foreach ($roles as $role) {
-            if ($options['filter'] && !$role->hasPermission($options['filter'])) {
-                continue;
-            }
             $rows[$role->id()] = [
             'label' => $role->label(),
             'perms' => $role->getPermissions(),

src/Drupal/Commands/core/TwigCommands.php

@@ -64,6 +64,7 @@ public function __construct(TwigEnvironment $twig, ModuleHandlerInterface $modul
      *   template: Template
      *   compiled: Compiled
      * @default-fields template,compiled
+     * @filter-output
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      *
      * @command twig:unused

src/Drupal/Commands/core/UserCommands.php

@@ -54,6 +54,7 @@ class UserCommands extends DrushCommands
      * @table-style default
      * @default-fields uid,name,mail,roles,user_status
      *
+     * @filter-default-field name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function information($names = '', $options = ['format' => 'table', 'uid' => self::REQ, 'mail' => self::REQ])

src/Drupal/Commands/core/ViewsCommands.php

@@ -140,6 +140,7 @@ public function dev()
      * @aliases vl,views-list
      * @validate-module-enabled views
      *
+     * @filter-default-field machine-name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function vlist($options = ['name' => self::REQ, 'tags' => self::REQ, 'status' => self::REQ, 'format' => 'table'])

src/Drupal/Commands/core/WatchdogCommands.php

@@ -45,6 +45,7 @@ class WatchdogCommands extends DrushCommands
      *   date: Date
      *   username: Username
      * @default-fields wid,date,type,severity,message
+     * @filter-default-field message
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function show($substring = '', $options = ['format' => 'table', 'count' => 10, 'severity' => self::REQ, 'type' => self::REQ, 'extended' => false])