Add --filter to many commands

composer.json

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

docs/output-filters.md

@@ -0,0 +1,36 @@
+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 simple 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 can 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.

examples/Commands/ArtCommands.php

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

src/Commands/core/CoreCommands.php

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

src/Commands/core/DocsCommands.php

@@ -77,6 +77,19 @@ public function configExport()
         self::printFile(DRUSH_BASE_PATH. '/docs/config-exporting.md');
     }
 
+    /**
+     * Explanation of how output filters work.
+     *
+     * @command docs:output-filters
+     * @aliases docs-output-filters
+     * @hidden
+     * @topic
+     */
+    public function outputFilters()
+    {
+        self::printFile(DRUSH_BASE_PATH. '/docs/output-filters.md');
+    }
+
     /**
      * Creating site aliases for running Drush on remote sites.
      *

src/Commands/core/UpdateDBCommands.php

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

src/Commands/pm/SecurityUpdateCommands.php

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

src/Drupal/Commands/config/ConfigCommands.php

@@ -222,6 +222,7 @@ public function delete($config_name, $key = null)
      * @default-fields name,state
      * @aliases cst,config-status
      * @filter-output
+     * @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

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

src/Drupal/Commands/core/LanguageCommands.php

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

src/Drupal/Commands/core/QueueCommands.php

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

src/Drupal/Commands/core/UserCommands.php

@@ -55,6 +55,7 @@ class UserCommands extends DrushCommands
      * @default-fields uid,name,mail,roles,user_status
      *
      * @filter-output
+     * @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

@@ -141,6 +141,7 @@ public function dev()
      * @validate-module-enabled views
      *
      * @filter-output
+     * @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

@@ -46,6 +46,7 @@ class WatchdogCommands extends DrushCommands
      *   username: Username
      * @default-fields wid,date,type,severity,message
      * @filter-output
+     * @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])

src/Drupal/Commands/pm/PmCommands.php

@@ -152,6 +152,7 @@ public function validateUninstall(CommandData $commandData)
      * @default-fields package,display_name,status,version
      * @aliases pml,pm-list
      * @filter-output
+     * @filter-default-field display_name
      * @return \Consolidation\OutputFormatters\StructuredData\RowsOfFields
      */
     public function pmList($options = ['format' => 'table', 'type' => 'module,theme', 'status' => 'enabled,disabled', 'package' => self::REQ, 'core' => false, 'no-core' => false])