rename autocompletion to shell_complete

new function takes additional param arg, must return a homogeneous list
of strings or CompletionItem, and must perform matching on results

5 files changed, 84 insertions, 60 deletions

diff --git a/examples/bashcompletion/README b/examples/bashcompletion/README
deleted file mode 100644
index f8a0d51..0000000
--- a/examples/bashcompletion/README
+++ /dev/null
@@ -1,12 +0,0 @@
-$ bashcompletion
-
-  bashcompletion is a simple example of an application that
-  tries to autocomplete commands, arguments and options.
-
-  This example requires Click 2.0 or higher.
-
-Usage:
-
-  $ pip install --editable .
-  $ eval "$(_BASHCOMPLETION_COMPLETE=source bashcompletion)"
-  $ bashcompletion --help
diff --git a/examples/bashcompletion/bashcompletion.py b/examples/bashcompletion/bashcompletion.py
deleted file mode 100644
index 3f8c9df..0000000
--- a/examples/bashcompletion/bashcompletion.py
+++ /dev/null
@@ -1,45 +0,0 @@
-import os
-
-import click
-
-
-@click.group()
-def cli():
-    pass
-
-
-def get_env_vars(ctx, args, incomplete):
-    # Completions returned as strings do not have a description displayed.
-    for key in os.environ.keys():
-        if incomplete in key:
-            yield key
-
-
-@cli.command(help="A command to print environment variables")
-@click.argument("envvar", type=click.STRING, autocompletion=get_env_vars)
-def cmd1(envvar):
-    click.echo(f"Environment variable: {envvar}")
-    click.echo(f"Value: {os.environ[envvar]}")
-
-
-@click.group(help="A group that holds a subcommand")
-def group():
-    pass
-
-
-def list_users(ctx, args, incomplete):
-    # You can generate completions with descriptions by returning
-    # tuples in the form (completion, description).
-    users = [("bob", "butcher"), ("alice", "baker"), ("jerry", "candlestick maker")]
-    # Ths will allow completion matches based on matches within the
-    # description string too!
-    return [user for user in users if incomplete in user[0] or incomplete in user[1]]
-
-
-@group.command(help="Choose a user")
-@click.argument("user", type=click.STRING, autocompletion=list_users)
-def subcmd(user):
-    click.echo(f"Chosen user is {user}")
-
-
-cli.add_command(group)
diff --git a/examples/completion/README b/examples/completion/README
new file mode 100644
index 0000000..f15654e
--- /dev/null
+++ b/examples/completion/README
@@ -0,0 +1,28 @@
+$ completion
+============
+
+Demonstrates Click's shell completion support.
+
+.. code-block:: bash
+
+    pip install --editable .
+
+For Bash:
+
+.. code-block:: bash
+
+    eval "$(_COMPLETION_COMPLETE=source_bash completion)"
+
+For Zsh:
+
+.. code-block:: zsh
+
+    eval "$(_COMPLETION_COMPLETE=source_zsh completion)"
+
+For Fish:
+
+.. code-block:: fish
+
+    eval (env _COMPLETION_COMPLETE=source_fish completion)
+
+Now press tab (maybe twice) after typing something to see completions.
diff --git a/examples/completion/completion.py b/examples/completion/completion.py
new file mode 100644
index 0000000..92dcc74
--- /dev/null
+++ b/examples/completion/completion.py
@@ -0,0 +1,53 @@
+import os
+
+import click
+from click.shell_completion import CompletionItem
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+@click.option("--dir", type=click.Path(file_okay=False))
+def ls(dir):
+    click.echo("\n".join(os.listdir(dir)))
+
+
+def get_env_vars(ctx, param, args, incomplete):
+    # Returning a list of values is a shortcut to returning a list of
+    # CompletionItem(value).
+    return [k for k in os.environ if incomplete in k]
+
+
+@cli.command(help="A command to print environment variables")
+@click.argument("envvar", shell_complete=get_env_vars)
+def show_env(envvar):
+    click.echo(f"Environment variable: {envvar}")
+    click.echo(f"Value: {os.environ[envvar]}")
+
+
+@cli.group(help="A group that holds a subcommand")
+def group():
+    pass
+
+
+def list_users(ctx, args, incomplete):
+    # You can generate completions with help strings by returning a list
+    # of CompletionItem. You can match on whatever you want, including
+    # the help.
+    items = [("bob", "butcher"), ("alice", "baker"), ("jerry", "candlestick maker")]
+
+    for value, help in items:
+        if incomplete in value or incomplete in help:
+            yield CompletionItem(value, help=help)
+
+
+@group.command(help="Choose a user")
+@click.argument("user", type=click.STRING, autocompletion=list_users)
+def select_user(user):
+    click.echo(f"Chosen user is {user}")
+
+
+cli.add_command(group)
diff --git a/examples/bashcompletion/setup.py b/examples/completion/setup.py
index f9a2c29..a78d140 100644
--- a/examples/bashcompletion/setup.py
+++ b/examples/completion/setup.py
@@ -1,13 +1,13 @@
 from setuptools import setup
 
 setup(
-    name="click-example-bashcompletion",
+    name="click-example-completion",
     version="1.0",
-    py_modules=["bashcompletion"],
+    py_modules=["completion"],
     include_package_data=True,
     install_requires=["click"],
     entry_points="""
         [console_scripts]
-        bashcompletion=bashcompletion:cli
+        completion=completion:cli
     """,
 )