Add a --filter option to `docker search`

The filtering is made server-side, and the following filters are
supported:

* is-official (boolean)
* is-automated (boolean)
* has-stars (integer)

Signed-off-by: Fabrizio Soppelsa <fsoppelsa@mirantis.com>
Signed-off-by: Vincent Demeester <vincent@sbr.pm>

contrib/completion/bash/docker

@@ -1907,15 +1907,29 @@ _docker_save() {
 }
 
 _docker_search() {
+	local key=$(__docker_map_key_of_current_option '--filter|-f')
+	case "$key" in
+		is-automated)
+			COMPREPLY=( $( compgen -W "false true" -- "${cur##*=}" ) )
+			return
+			;;
+		is-official)
+			COMPREPLY=( $( compgen -W "false true" -- "${cur##*=}" ) )
+			return
+			;;
+	esac
+
 	case "$prev" in
-		--stars|-s)
+		--filter|-f)
+			COMPREPLY=( $( compgen -S = -W "is-automated is-official stars" -- "$cur" ) )
+			__docker_nospace
 			return
 			;;
 	esac
 
 	case "$cur" in
 		-*)
-			COMPREPLY=( $( compgen -W "--automated --help --no-trunc --stars -s" -- "$cur" ) )
+			COMPREPLY=( $( compgen -W "--filter --help --no-trunc" -- "$cur" ) )
 			;;
 	esac
 }

contrib/completion/zsh/_docker

@@ -311,6 +311,30 @@ __docker_complete_ps_filters() {
     return ret
 }
 
+__docker_complete_search_filters() {
+    [[ $PREFIX = -* ]] && return 1
+    integer ret=1
+    declare -a boolean_opts opts
+
+    boolean_opts=('true' 'false')
+    opts=('is-automated' 'is-official' 'stars')
+
+    if compset -P '*='; then
+        case "${${words[-1]%=*}#*=}" in
+            (is-automated|is-official)
+                _describe -t boolean-filter-opts "filter options" boolean_opts && ret=0
+                ;;
+            *)
+                _message 'value' && ret=0
+                ;;
+        esac
+    else
+        _describe -t filter-opts "filter options" opts -qS "=" && ret=0
+    fi
+
+    return ret
+}
+
 __docker_network_complete_ls_filters() {
     [[ $PREFIX = -* ]] && return 1
     integer ret=1
@@ -1126,10 +1150,15 @@ __docker_subcommand() {
         (search)
             _arguments $(__docker_arguments) \
                 $opts_help \
-                "($help)--automated[Only show automated builds]" \
+                "($help)*"{-f=,--filter=}"[Filter values]:filter:->filter-options" \
                 "($help)--no-trunc[Do not truncate output]" \
-                "($help -s --stars)"{-s=,--stars=}"[Only display with at least X stars]:stars:(0 10 100 1000)" \
                 "($help -):term: " && ret=0
+
+            case $state in
+                (filter-options)
+                    __docker_complete_search_filters && ret=0
+                    ;;
+            esac
             ;;
         (start)
             _arguments $(__docker_arguments) \

docs/deprecated.md

@@ -58,6 +58,15 @@ defining it at container creation (`POST /containers/create`).
 The `docker ps --before` and `docker ps --since` options are deprecated.
 Use `docker ps --filter=before=...` and `docker ps --filter=since=...` instead.
 
+### Docker search 'automated' and 'stars' options
+
+**Deprecated in Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
+
+**Removed In Release: v1.14**
+
+The `docker search --automated` and `docker search --stars` options are deprecated.
+Use `docker search --filter=is-automated=...` and `docker search --filter=stars=...` instead.
+
 ### Command line short variant options
 **Deprecated In Release: v1.9**
 

docs/reference/commandline/search.md

@@ -14,10 +14,12 @@ parent = "smn_cli"
 
     Search the Docker Hub for images
 
-      --automated          Only show automated builds
+      --filter=[]          Filter output based on these conditions:
+                           - is-automated=(true|false)
+                           - is-official=(true|false)
+                           - stars=<number> - image has at least 'number' stars
       --help               Print usage
       --no-trunc           Don't truncate output
-      -s, --stars=0        Only displays with at least x stars
 
 Search [Docker Hub](https://hub.docker.com) for images
 
@@ -61,29 +63,6 @@ This example displays images with a name containing 'busybox':
     scottabernethy/busybox                                                           0                    [OK]
     marclop/busybox-solr
 
-### Search images by name and number of stars (-s, --stars)
-
-This example displays images with a name containing 'busybox' and at
-least 3 stars:
-
-    $ docker search --stars=3 busybox
-    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-    busybox              Busybox base image.                             325       [OK]       
-    progrium/busybox                                                     50                   [OK]
-    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
-
-
-### Search automated images (--automated)
-
-This example displays images with a name containing 'busybox', at
-least 3 stars and are automated builds:
-
-    $ docker search --stars=3 --automated busybox
-    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-    progrium/busybox                                                     50                   [OK]
-    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
-
-
 ### Display non-truncated description (--no-trunc)
 
 This example displays images with a name containing 'busybox',
@@ -95,3 +74,48 @@ at least 3 stars and the description isn't truncated in the output:
     progrium/busybox                                                                                               50                   [OK]
     radial/busyboxplus   Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors.   8                    [OK]
 
+## Filtering
+
+The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
+than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`)
+
+The currently supported filters are:
+
+* stars (int - number of stars the image has)
+* is-automated (true|false) - is the image automated or not
+* is-official (true|false) - is the image official or not
+
+
+### stars
+
+This example displays images with a name containing 'busybox' and at
+least 3 stars:
+
+    $ docker search --filter stars=3 busybox
+    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+    busybox              Busybox base image.                             325       [OK]       
+    progrium/busybox                                                     50                   [OK]
+    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+
+
+### is-automated
+
+This example displays images with a name containing 'busybox'
+and are automated builds:
+
+    $ docker search --filter is-automated busybox
+    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+    progrium/busybox                                                     50                   [OK]
+    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+
+### is-official
+
+This example displays images with a name containing 'busybox', at least
+3 stars and are official builds:
+
+    $ docker search --filter "is-automated=true" --filter "stars=3" busybox
+    NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
+    progrium/busybox                                                     50                   [OK]
+    radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+
+

man/docker-search.1.md

@@ -6,10 +6,9 @@ docker-search - Search the Docker Hub for images
 
 # SYNOPSIS
 **docker search**
-[**--automated**]
+[**-f**|**--filter**[=*[]*]]
 [**--help**]
 [**--no-trunc**]
-[**-s**|**--stars**[=*0*]]
 TERM
 
 # DESCRIPTION
@@ -21,8 +20,12 @@ of stars awarded, whether the image is official, and whether it is automated.
 *Note* - Search queries will only return up to 25 results
 
 # OPTIONS
-**--automated**=*true*|*false*
+
-   Only show automated builds. The default is *false*.
+**-f**, **--filter**=[]
+   Filter output based on these conditions:
+   - stars=<numberOfStar>
+   - is-automated=(true|false)
+   - is-official=(true|false)
 
 **--help**
   Print usage statement
@@ -30,9 +33,6 @@ of stars awarded, whether the image is official, and whether it is automated.
 **--no-trunc**=*true*|*false*
    Don't truncate output. The default is *false*.
 
-**-s**, **--stars**=*X*
-   Only displays with at least X stars. The default is zero.
-
 # EXAMPLES
 
 ## Search Docker Hub for ranked images
@@ -40,7 +40,7 @@ of stars awarded, whether the image is official, and whether it is automated.
 Search a registry for the term 'fedora' and only display those images
 ranked 3 or higher:
 
-    $ docker search -s 3 fedora
+    $ docker search --filter=stars=3 fedora
     NAME                  DESCRIPTION                                    STARS OFFICIAL  AUTOMATED
     mattdm/fedora         A basic Fedora image corresponding roughly...  50
     fedora                (Semi) Official Fedora base image.             38
@@ -52,7 +52,7 @@ ranked 3 or higher:
 Search Docker Hub for the term 'fedora' and only display automated images
 ranked 1 or higher:
 
-    $ docker search --automated -s 1 fedora
+    $ docker search --filter=is-automated=true --filter=stars=1 fedora
     NAME               DESCRIPTION                                     STARS OFFICIAL  AUTOMATED
     goldmann/wildfly   A WildFly application server running on a ...   3               [OK]
     tutum/fedora-20    Fedora 20 image with SSH access. For the r...   1               [OK]
@@ -62,4 +62,5 @@ April 2014, Originally compiled by William Henry (whenry at redhat dot com)
 based on docker.com source material and internal work.
 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
 April 2015, updated by Mary Anthony for v2 <mary@docker.com>
+April 2016, updated by Vincent Demeester <vincent@sbr.pm>