# Completion Commands

Command | Description
--- | ---
none | No completion, but specifies that an argument is required
integer | Complete an integer
float | Complete a floating point number
combine | Combine multiple completion commands
file | Complete a file
directory | Complete a directory
choices | Complete from a set of values
value_list | Complete a list
exec | Complete by the output of a command or function
exec_fast | Complete by the output of a command or function (fast and unsafe)
exec_internal | Complete by a function that uses the shell’s internal completion mechanisms
range | Complete a range of integers
signal | Complete a signal
hostname | Complete a hostname
process | Complete a process
pid | Complete a PID
command | Complete a command
user | Complete a user
group | Complete a group
service | Complete a SystemD service
variable | Complete a shell variable
environment | Complete an environment variable

## none

Disables autocompletion for this option but still marks it as requiring an argument.

Without specifying `complete`, the option would not take an argument.

    prog: "example"
    options:
      - option_strings: ["--none"]
        complete: ["none"]

## integer

Complete an integer.

NOTE: This completion currently serves as documentation and does not provide actual functionality.

If you want to complete a range of integers, see range.

    prog: "example"
    options:
      - option_strings: ["--integer"]
        complete: ["integer"]

## float

Complete a floating point number.

NOTE: This completion currently serves as documentation and does not provide actual functionality.

    prog: "example"
    options:
      - option_strings: ["--float"]
        complete: ["float"]

## combine

Combine two or more completion commands.

    prog: "example"
    options:
      - option_strings: ["--combine"]
        complete: ["combine", [["user"], ["pid"]]]

## file

Complete a file.

You can restrict completion to a specific directory by adding `{"directory": ...}`.

    prog: "example"
    options:
      - option_strings: ["--file"]
        complete: ["file"]
      - option_strings: ["--file-tmp"]
        complete: ["file", {"directory": "/tmp"}]

Example:

    $ example --file=<TAB>
    dir1/  dir2/  file1  file2

## directory

Complete a directory.

You can restrict completion to a specific directory by adding `{"directory": ...}`.

    prog: "example"
    options:
      - option_strings: ["--directory"]
        complete: ["directory"]
      - option_strings: ["--directory-tmp"]
        complete: ["directory", {"directory": "/tmp"}]

Example:

    $ example --directory=<TAB>
    dir1/  dir2/

## choices

Complete a list of items.

Items can be a list or a dictionary.

If a dictionary is supplied, the keys are used as items and the values are used as description.

    prog: "example"
    options:
      - option_strings: ["--choices-1"]
        complete: ["choices", ["Item 1", "Item 2"]]
      - option_strings: ["--choices-2"]
        complete: ["choices", {"Item 1": "Description 1", "Item 2": "Description 2"}]

Example:

    $ example --choices-2=<TAB>
    Item 1  (Description 1)  Item 2  (Description 2)

## value_list

Complete one or more items from a list of items. Similar to `mount -o`.

Arguments with assignable values (`mount -o uid=1000`) aren’t supported.

Arguments are supplied by adding `{"values": ...}`.

A separator can be supplied by adding `{"separator": ...}` (the default is “,”).

    prog: "example"
    options:
      - option_strings: ["--value-list-1"]
        complete: ["value_list", {"values": ["exec", "noexec"]}]
      - option_strings: ["--value-list-2"]
        complete: ["value_list", {"values": {"one": "Description 1", "two": "Description 2"}}]

Example:

    $ example --value-list-1=<TAB>
    exec    noexec
    $ example --value-list-1=exec,<TAB>
    exec    noexec
    $ example --value-list-2=<TAB>
    one  -- Description 1
    two  -- Description 2

## exec

Execute a command and parse the output.

The output must be in form of:

    <item_1>\t<description_1>\n
    <item_2>\t<description_2>\n
    [...]

An item and its description are delimited by a tabulator.

These pairs are delimited by a newline.

    prog: "example"
    options:
      - option_strings: ["--exec"]
        complete: ["exec", "printf '%s\\t%s\\n' 'Item 1' 'Description 1' 'Item 2' 'Description 2'"]

Example:

    $ example --exec=<TAB>
    Item 1  (Description 1)  Item 2  (Description 2)

## exec_fast

Faster version of exec for handling large amounts of data.

This implementation requires that the items of the parsed output do not include special shell characters or whitespace.

    prog: "example"
    options:
      - option_strings: ["--exec-fast"]
        complete: ["exec_fast", "printf '%s\\t%s\\n' 1 one 2 two"]

## exec_internal

Execute a function that internally modifies the completion state.

This is useful if a more advanced completion is needed.

    prog: "example"
    options:
      - option_strings: ["--exec-internal"]
        complete: ["exec_internal", "my_completion_func"]

Examples:

Bash:

    my_completion_func() {
        COMPREPLY=( $(compgen -W "foo bar baz") )
    }

Zsh:

    my_completion_func() {
        local items=( foo bar baz )
        _describe '' items
    }

Fish:

    function my_completion_func
        printf '%s\n' foo bar baz
    end

## range

Complete a range of integers.

    prog: "example"
    options:
      - option_strings: ["--range-1"]
        complete: ["range", 1, 9]
      - option_strings: ["--range-2"]
        complete: ["range", 1, 9, 2]

Example:

    $ example --range-1=<TAB>
    1  2  3  4  5  6  7  8  9
    $ example --range-2=<TAB>
    1  3  5  7  9

## signal

Complete signal names (INT, KILL, TERM, etc.).

    prog: "example"
    options:
      - option_strings: ["--signal"]
        complete: ["signal"]

Example:

    $ example --signal=<TAB>
    ABRT    -- Process abort signal
    ALRM    -- Alarm clock
    BUS     -- Access to an undefined portion of a memory object
    [...]

## hostname

Complete a hostname.

    prog: "example"
    options:
      - option_strings: ["--hostname"]
        complete: ["hostname"]

Example:

    $ example --hostname=<TAB>
    localhost

## process

Complete a process name.

    prog: "example"
    options:
      - option_strings: ["--process"]
        complete: ["process"]

Example:

    $ example --process=s<TAB>
    scsi_eh_0   scsi_eh_1  sudo  systemd  [...]

## pid

Complete a PID.

    prog: "example"
    options:
      - option_strings: ["--pid"]
        complete: ["pid"]

Example:

    $ example --pid=<TAB>
    1  13  166  19  [...]

## command

Complete a command.

    prog: "example"
    options:
      - option_strings: ["--command"]
        complete: ["command"]

Example:

    $ example --command=bas<TAB>
    base32  base64  basename  basenc  bash  bashbug

## user

Complete a username.

    prog: "example"
    options:
      - option_strings: ["--user"]
        complete: ["user"]

Example:

    $ example --user=<TAB>
    avahi  bin  braph  [...]

## group

Complete a group.

    prog: "example"
    options:
      - option_strings: ["--group"]
        complete: ["group"]

Example:

    $ example --group=<TAB>
    adm  audio  avahi  [...]

## service

Complete a SystemD service.

    prog: "example"
    options:
      - option_strings: ["--service"]
        complete: ["service"]

Example:

    $ example --service=<TAB>
    TODO

## variable

Complete a shell variable name.

To complete an environment variable, use environment.

    prog: "example"
    options:
      - option_strings: ["--variable"]
        complete: ["variable"]

Example:

    $ example --variable=HO<TAB>
    HOME  HOSTNAME  HOSTTYPE

## environment

Complete a shell environment variable name.

    prog: "example"
    options:
      - option_strings: ["--environment"]
        complete: ["environment"]

Example:

    $ example --environment=X<TAB>
    XDG_RUNTIME_DIR  XDG_SESSION_TYPE  [...]