Crazy-Complete Documentation
============================

This documentation provides an overview of how to define shell completion for commands using crazy-complete.

- [Generating a Defintion File from Help](#generating-a-definition-file-from-help)
- [Defining a Command](#defining-a-command)
- [Defining an Option](#defining-an-option)
- [Defining a Positional Argument](#defining-a-positional-argument)
- [Using Aliases](#using-aliases)
- [Completion Commands](#completion-commands)
  - [Meta Commands](#meta-commands)
  - [Built-in Commands](#built-in-commands)
  - [User-Defined Commands](#user-defined-commands)
  - [Bonus Commands](#bonus-commands)
- [Options](#options)
- [When Conditionals](#when-conditionals)
- [Capturing Options](#capturing-options)
- [Tips and Tricks](#tips-and-tricks)

## Generating a Definition File from Help

It is possible to generate a definition file from a commands help output:

```
grep --help > help_file
crazy-complete --input-type=help yaml help_file

# or

grep --help | crazy-complete --input-type=help yaml /dev/stdin
```

## Defining a Command

To define a completion for a command, use the following structure:

```yaml
prog: "<PROGRAM NAME>"
aliases: ["<ALIAS>", ...]
help: "<PROGRAM DESCRIPTION>"
wraps: "<PROGRAM>"
options:
  <OPTION ...>
positionals:
  <POSITIONAL ...>
```

- *prog*: The name of the program for which you want to create completion
- *aliases* (optional): Specify alternative program names for which this completion should also apply
- *help* (optional): A short description of the program
- *wraps* (optional): Inherit completion behaviour of another command
- *options* (optional): A list of [options](#defining-an-option) the program accepts
- *positionals* (optional): A list of [positional arguments](#defining-a-positional-argument) the program uses

## Defining an Option

To define an option, use this format:

```yaml
[...]
options:
  - option_strings: ["<OPTION STRING>", ...]
    metavar: "<METAVAR>"
    help: "<OPTION DESCRIPTION>"
    optional_arg: <BOOL>
    complete: <COMPLETE ACTION>
    nosort: <BOOL>
    repeatable: <BOOL>
    final: <BOOL>
    hidden: <BOOL>
    groups: ["<GROUP>", ...]
    when: "<CONDITION>"
    capture: "<VARIABLE>"
    long_opt_arg_sep: "equals|space|both"
[...]
```

- *option\_strings*: A list of option strings (e.g., ["-h", "--help"])
- *metavar* (optional): The placeholder used for the argument (e.g., "FILE")
- *help* (optional): A description of the option
- *optional\_arg* (optional): Indicates if the option's argument is optional (default: false)
- *complete* (optional): Defines the method used to provide possible completions for this option. If not set, the option does not take an argument. Use `["none"]` if the option accepts an argument but no specific completion method applies. See [Completion Commands](#completion-commands)
- *nosort* (optional): Do not sort completion suggestions alphabetically. Keep them in the order generated by the completer. (true or false, default: false)
- *repeatable* (optional): Indicates whether an option can be suggested multiple times (true or false, default: false)
- *final* (optional): The final parameter indicates that no further options are shown after this one if it is passed on command line. Mostly used for --help and --version (default: false)
- *hidden* (optional): Specifies whether an option should be excluded from the auto-completion suggestions, though it remains usable when typed manually. (default: false)
- *groups* (optional): Add this option into the specified groups. Multiple flags from the same group cannot be completed at once. Useful for mutually exclusive flags
- *when* (optional): Only enable this option if [CONDITION](#when-conditionals) evaluates to true
- *capture* (optional): Specify the [variable](#capturing-options) where values of this option should be captured
- *long_opt_arg_sep* (optional): Specifies which separators are used for delimiting a long option from its argument

## Defining a Positional Argument

Positional arguments are defined as follows:

```yaml
[...]
positionals:
  - number: <NUMBER>
    metavar: "<METAVAR>"
    help: "<POSITIONAL DESCRIPTION>"
    repeatable: <BOOL>
    complete: <COMPLETE ACTION>
    nosort: <BOOL>
    when: "<CONDITION>"
[...]
```

- *number*: The order of the positional argument (e.g., 1 for the first argument)
- *metavar* (optional): A placeholder for the positional argument in the help text
- *help* (optional): A description of the positional argument
- *repeatable* (optional): Indicates if this positional argument can be repeated (true or false, default: false)
- *complete* (optional): The method used to generate possible completions for this positional argument. Default `["none"]`. See [Completion Commands](#completion-commands).
- *nosort* (optional): Do not sort completion suggestions alphabetically. Keep them in the order generated by the completer. (true or false, default: false)
- *when* (optional): Only enable this positional if [CONDITION](#when-conditionals) evaluates to true

### Using Aliases

Aliases / defines can be handy if completers are reused or to keep the defintion file clean.

**NOTE:** Every defined string is replaced throughout the YAML document, regardless of its context.

```yaml
prog: '%defines%'
complete_bool: ['choices', ['true', 'false']]
---
prog: "example"
options:
  - option_strings: ['--option-1']
    complete: 'complete_bool'

  - option_strings: ['--option-2']
    complete: 'complete_bool'
```

## Defining Subcommands

To define subcommands, append the subcommand name directly to the program name:

```yaml
prog: "<PROGRAM NAME> <SUBCOMMAND> ..."
aliases: ["<ALIAS>", ...]
help: "<SUBCOMMAND DESCRIPTION>"
[...]
```

- *prog*: The name of the program, followed by the subcommand(s)
- *aliases* (optional): A list of alternative names for the subcommand. Aliases must not include the program name
- *help* (optional): A description of the subcommand

## Completion Commands

### Meta commands

| Command                             | Description                                               |
| ----------------------------------- | --------------------------------------------------------- |
| [combine](#combine)                 | Combine multiple completers                               |
| [key\_value\_list](#key_value_list) | Complete a comma-separated list of key=value pairs        |
| [list](#list)                       | Complete a comma-separated list of any completer          |
| [none](#none)                       | No completion, but specifies that an argument is required |
| [prefix](#prefix)                   | Prefix completion by a string                             |

---

### Built-in commands

| Command                                    | Description                                    |
| ------------------------------------------ | ---------------------------------------------- |
| [choices](#choices)                        | Complete from a set of words                   |
| [command](#command)                        | Complete a command                             |
| [command\_arg](#command_arg)               | Complete arguments of a command                |
| [commandline\_string](#commandline_string) | Complete a command line as a string            |
| [date](#date)                              | Complete a date string                         |
| [date\_format](#date_format)               | Complete a date format string                  |
| [directory](#directory)                    | Complete a directory                           |
| [directory\_list](#directory_list)         | Complete a comma-separated list of directories |
| [environment](#environment)                | Complete a shell environment variable name     |
| [file](#file)                              | Complete a file                                |
| [file\_list](#file_list)                   | Complete a comma-separated list of files       |
| [filesystem\_type](#filesystem_type)       | Complete a filesystem type                     |
| [float](#float)                            | Complete a floating point number               |
| [gid](#gid)                                | Complete a group id                            |
| [group](#group)                            | Complete a group                               |
| [history](#history)                        | Complete based on a shell's history            |
| [hostname](#hostname)                      | Complete a hostname                            |
| [integer](#integer)                        | Complete an integer                            |
| [ip\_address](#ip_address)                 | Complete a bound ip address                    |
| [mime\_file](#mime_file)                   | Complete a file based on it's MIME-type        |
| [pid](#pid)                                | Complete a PID                                 |
| [process](#process)                        | Complete a process name                        |
| [range](#range)                            | Complete a range of integers                   |
| [service](#service)                        | Complete a SystemD service                     |
| [signal](#signal)                          | Complete signal names                          |
| [uid](#uid)                                | Complete a user id                             |
| [user](#user)                              | Complete a username                            |
| [value\_list](#value_list)                 | Complete a comma-separated list of values      |
| [variable](#variable)                      | Complete a shell variable name                 |

---

### User-defined commands

| Command                          | Description                                                                 |
| -------------------------------- | --------------------------------------------------------------------------- |
| [exec](#exec)                    | Complete by the output of a command or function                             |
| [exec\_fast](#exec_fast)         | Complete by the output of a command or function (fast and unsafe)           |
| [exec\_internal](#exec_internal) | Complete by a function that uses the shell's internal completion mechanisms |

---

### Bonus commands

| Command                          | Description                  |
| -------------------------------- | ---------------------------- |
| [alsa\_card](#alsa_card)         | Complete an ALSA card        |
| [alsa\_device](#alsa_device)     | Complete an ALSA device      |
| [charset](#charset)              | Complete a charset           |
| [locale](#locale)                | Complete a locale            |
| [login\_shell](#login_shell)     | Complete a login shell       |
| [mountpoint](#mountpoint)        | Complete a mountpoint        |
| [net\_interface](#net_interface) | Complete a network interface |
| [timezone](#timezone)            | Complete a timezone          |

---

### alsa\_card

> Complete an ALSA card

```yaml
prog: "example"
options:
  - option_strings: ["--alsa-card"]
    complete: ["alsa_card"]
```

```
~ > example --alsa-card=<TAB>
0  1
```

**SEE ALSO**

- [alsa\_device](#alsa_device): For completing an ALSA device

---

### alsa\_device

> Complete an ALSA device

```yaml
prog: "example"
options:
  - option_strings: ["--alsa-device"]
    complete: ["alsa_device"]
```

```
~ > example --alsa-device=<TAB>
hw:0  hw:1
```

**SEE ALSO**

- [alsa\_card](#alsa_card): For completing an ALSA card

---

### charset

> Complete a charset

```yaml
prog: "example"
options:
  - option_strings: ["--charset"]
    complete: ["charset"]
```

```
~ > example --charset=A<TAB>
ANSI_X3.110-1983  ANSI_X3.4-1968    ARMSCII-8         ASMO_449
```

---

### locale

> Complete a locale

```yaml
prog: "example"
options:
  - option_strings: ["--locale"]
    complete: ["locale"]
```

```
~ > example --locale=<TAB>
C  C.UTF-8  de_DE  de_DE@euro  de_DE.iso88591  de_DE.iso885915@euro
de_DE.UTF-8  deutsch  en_US  en_US.iso88591  en_US.UTF-8  german  POSIX
```

---

### login\_shell

> Complete a login shell

```yaml
prog: "example"
options:
  - option_strings: ["--login-shell"]
    complete: ["login_shell"]
```

```
~ > example --login-shell=<TAB>
/bin/bash   /bin/sh         /usr/bin/fish       /usr/bin/sh
[...]
```

---

### mountpoint

> Complete a mountpoint

```yaml
prog: "example"
options:
  - option_strings: ["--mountpoint"]
    complete: ["mountpoint"]
```

```
~ > example --mountpoint=<TAB>
/  /boot  /home  /proc  /run  /sys  /tmp
[...]
```

---

### net\_interface

> Complete a network interface

```yaml
prog: "example"
options:
  - option_strings: ["--net-interface"]
    complete: ["net_interface"]
```

```
~ > example --net-interface=<TAB>
eno1  enp1s0  lo  wlo1  wlp2s0
[...]
```

**SEE ALSO**

- [ip\_address](#ip_address): For completing an ip address

---

### timezone

> Complete a timezone

```yaml
prog: "example"
options:
  - option_strings: ["--timezone"]
    complete: ["timezone"]
```

```
~ > example --timezone=Europe/B<TAB>
Belfast     Belgrade    Berlin      Bratislava
Brussels    Bucharest   Budapest    Busingen
```

---

### choices

> Complete from a set of words

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.


**NOTES**

- If the completion suggestions should appear in their original order, set `nosort` to `true`

```yaml
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"}]

  - option_strings: ["--choices-keep-order"]
    complete: ["choices", ["zebra", "cat", "monkey"]]
    nosort: true
```

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

---

### command

> Complete a command

This completer provides completion suggestions for executable commands available in the system's `$PATH`.
 
`$PATH` can be modified using these options:
 
`{"path": "<directory>:..."}`: Overrides the default `$PATH` entirely.
 
`{"path_append": "<directory>:..."}`: Appends to the default `$PATH`.
 
`{"path_prepend": "<directory>:..."}`: Prepends to the default `$PATH`.


**NOTES**

- `path_append` and `path_prepend` can be used together, but both are mutually exclusive with `path`.

```yaml
prog: "example"
options:
  - option_strings: ["--command"]
    complete: ["command"]
  - option_strings: ["--command-sbin"]
    complete: ["command", {"path_append": "/sbin:/usr/sbin"}]
```

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

**SEE ALSO**

- [command\_arg](#command_arg): For completing arguments of a command

- [commandline\_string](#commandline_string): For completing a command line as a string

---

### command\_arg

> Complete arguments of a command

**NOTES**

- This completer can only be used in combination with a previously defined `command` completer.

- This completer requires `repeatable: true`.

```yaml
prog: "example"
positionals:
  - number: 1
    complete: ["command"]

  - number: 2
    complete: ["command_arg"]
    repeatable: true
```

```
~ > example sudo bas<TAB>
base32    base64    basename  basenc    bash      bashbug
```

**SEE ALSO**

- [command](#command): For completing a command

- [commandline\_string](#commandline_string): For completing a command line as a string

---

### commandline\_string

> Complete a command line as a string

```yaml
prog: "example"
options:
  - option_strings: ["--commandline"]
    complete: ["commandline_string"]
```

```
~ > example --commandline='sudo ba<TAB>
base32    base64    basename  basenc    bash      bashbug
```

---

### date

> Complete a date string

The argument is the date format as described in `strftime(3)`.


**NOTES**

- This completer is currently only implemented in **Zsh**.

```yaml
prog: "example"
options:
  - option_strings: ["--date"]
    complete: ["date", '%Y-%m-%d']
```

```
~ > example --date=<TAB>

         November                        
Mo  Tu  We  Th  Fr  Sa  Su     
     1   2   3   4   5   6    
 7   8   9  10  11  12  13
14  15  16  17  18  19  20
21  22  23  24  25  26  27
28  29  30
```

**SEE ALSO**

- [date\_format](#date_format): For completing a date format string

---

### date\_format

> Complete a date format string

**NOTES**

- This completer is currently only implemented in **Fish** and **Zsh**.

```yaml
prog: "example"
options:
  - option_strings: ["--date-format"]
    complete: ["date_format"]
```

```
~ > example --date-format '%<TAB>
a     -- abbreviated day name
A     -- full day name
B     -- full month name
c     -- preferred locale date and time
C     -- 2-digit century
d     -- day of month (01-31)
D     -- American format month/day/year (%m/%d/%y)
e     -- day of month ( 1-31)
[...]
```

**SEE ALSO**

- [date](#date): For completing a date

---

### directory

> Complete a directory

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


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

```
~ > example --directory=<TAB>
dir1/  dir2/
```

**SEE ALSO**

- [directory\_list](#directory_list): For completing a comma-separated list of directories

---

### directory\_list

> Complete a comma-separated list of directories

This is an alias for `['list', ['directory']]`.

You can restrict completion to a specific directory by adding `{"directory": ...}`.
 
The separator can be changed by adding `{"separator": ...}`
 
By default, duplicate values are not offered for completion. This can be changed by adding `{"duplicates": true}`.


```yaml
prog: "example"
options:
  - option_strings: ["--directory-list"]
    complete: ["directory_list"]
```

```
~ > example --directory-list=directory1,directory2,<TAB>
directory3  directory4
```

**SEE ALSO**

- [list](#list): For completion a comma-separated list of any completer

- [directory](#directory): For completing a directory

- [file\_list](#file_list): For completing a comma-separated list of files

---

### environment

> Complete a shell environment variable name

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

```
~ > example --environment=X<TAB>
XDG_RUNTIME_DIR  XDG_SEAT  XDG_SESSION_CLASS  XDG_SESSION_ID
XDG_SESSION_TYPE XDG_VTNR
```

---

### file

> Complete a file

You can restrict completion to a specific directory by adding `{"directory": ...}`.
 
You can restrict completion to specific extensions by adding `{"extensions": [...]}`.
 
You can make matching extensions *fuzzy* by adding `{"fuzzy": true}`.
Fuzzy means that the files do not have to end with the exact extension. For example `foo.txt.1`.

You can ignore files by adding a list of Bash globs using `{"ignore_globs": [...]}`

**NOTE:** Restricting completion to specific file extensions only makes sense if the program being completed actually expects files of those types.
On Unix-like systems, file extensions generally have no inherent meaning -- they are purely conventional and not required for determining file types.


```yaml
prog: "example"
options:
  - option_strings: ["--file"]
    complete: ["file"]

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

  - option_strings: ["--file-ext"]
    complete: ["file", {"extensions": ["c", "cpp"]}]

  - option_strings: ["--file-ignore"]
    complete: ["file", {"ignore_globs": ["*.[tT][xX][tT]", "*.c++"]}]
```

```
~ > example --file=<TAB>
dir1/  dir2/  file1  file2
~ > example --file-ext=<TAB>
dir1/  dir2/  file.c  file.cpp
```

**SEE ALSO**

- [file\_list](#file_list): For completing a comma-separated list of files

- [mime\_file](#mime_file): For completing a file based on it's MIME-type

---

### file\_list

> Complete a comma-separated list of files

This is an alias for `['list', ['file']]`.

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

You can restrict completion to specific extensions by adding `{"extensions": [...]}`.

You can make matching extensions *fuzzy* by adding `{"fuzzy": true}`.
Fuzzy means that the files do not have to end with the exact extension. For example `foo.txt.1`.

You can ignore files by adding a list of Bash globs using `{"ignore_globs": [...]}`

By default, duplicate values are not offered for completion. This can be changed by adding `{"duplicates": true}`.

The separator can be changed by adding `{"separator": ...}`


```yaml
prog: "example"
options:
  - option_strings: ["--file-list"]
    complete: ["file_list"]
```

```
~ > example --file-list=file1,file2,<TAB>
file3  file4
```

**SEE ALSO**

- [list](#list): For completing a comma-separted list using any completer

- [file](#file): For completing a file

- [directory\_list](#directory_list): For completing a comma-separated list of directories

---

### filesystem\_type

> Complete a filesystem type

```yaml
prog: "example"
options:
  - option_strings: ["--filesystem-type"]
    complete: ["filesystem_type"]
```

```
~ > example --filesystem-type=<TAB>
adfs     autofs   bdev      bfs     binder     binfmt_misc  bpf
cgroup   cgroup2  configfs  cramfs  debugfs    devpts       devtmpfs
[...]
```

---

### float

> Complete a floating point number

A min value can be specified by using `{"min": <VALUE>}`.

A max value can be specified by using `{"max": <VALUE>}`.

A list of suffixes can be specified by using `{"suffixes": {"<SUFFIX>": "<DESCRIPTION", ...}}`

A help text can be set by using `{"help": "<TEXT>"}`. If not supplied, the `help` attribute of the option is used.


```yaml
prog: "example"
options:
  - option_strings: ["--time"]
    complete: ["float", {"suffixes": {"s": "seconds", "m": "minutes", "h": "hours"}}]
```

```
~ > example --time=3.0<TAB>
s -- seconds  m -- minutes  h -- hours
```

**SEE ALSO**

- [integer](#integer): For completing an integer

---

### gid

> Complete a group id

```yaml
prog: "example"
options:
  - option_strings: ["--gid"]
    complete: ["gid"]
```

```
~ > example --gid=<TAB>
0      -- root
1000   -- braph
102    -- polkitd
108    -- vboxusers
11     -- ftp
12     -- mail
133    -- rtkit
19     -- log
[...]
```

**SEE ALSO**

- [group](#group): For completing a group name

---

### group

> Complete a group

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

```
~ > example --group=<TAB>
adm                     audio                   avahi
bin                     braph                   colord
daemon                  dbus                    dhcpcd
disk                    floppy                  ftp
games                   git                     groups
[...]
```

**SEE ALSO**

- [gid](#gid): For completing a group id

---

### history

> Complete based on a shell's history

The argument is an extended regular expression passed to `grep -E`.


```yaml
prog: "example"
options:
  - option_strings: ["--history"]
    complete: ["history", '[a-zA-Z0-9]+@[a-zA-Z0-9]+']
```

```
~ > example --history=<TAB>
foo@bar mymail@myprovider
```

---

### hostname

> Complete a hostname

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

```
~ > example --hostname=<TAB>
localhost
```

---

### integer

> Complete an integer

A min value can be specified by using `{"min": <VALUE>}`.

A max value can be specified by using `{"max": <VALUE>}`.

A list of suffixes can be specified by using `{"suffixes": {"<SUFFIX>": "<DESCRIPTION", ...}}`

A help text can be set by using `{"help": "<TEXT>"}`. If not supplied, the `help` attribute of the option is used.


```yaml
prog: "example"
options:
  - option_strings: ["--time"]
    complete: ["integer", {"suffixes": {"s": "seconds", "m": "minutes", "h": "hours"}}]
```

```
~ > example --integer=3<TAB>
s -- seconds  m -- minutes  h -- hours
```

**SEE ALSO**

- [float](#float): For completing a floating point number

- [range](#range): For completing a range of integers

---

### ip\_address

> Complete a bound ip address

By default, both IPv4 and IPv6 addresses are completed.

To complete only IPv4 addresses, pass "ipv4" as argument.

To complete only IPv6 addresses, pass "ipv6" as argument.


```yaml
prog: "example"
options:
  - option_strings: ["--ip-address"]
    complete: ["ip_address"]
  - option_strings: ["--ip-address-v4"]
    complete: ["ip_address", "ipv4"]
  - option_strings: ["--ip-address-v6"]
    complete: ["ip_address", "ipv6"]
```

```
~ > example --ip-address=<TAB>
::1    10.0.0.71   127.0.0.1   fe80::f567:7a1a:3c98:808d

~ > example --ip-address-v4=<TAB>
10.0.0.71   127.0.0.1

~ > example --ip-address-v6=<TAB>
::1   fe80::f567:7a1a:3c98:808d
```

**SEE ALSO**

- [net\_interface](#net_interface): For completing a network interface

---

### mime\_file

> Complete a file based on it's MIME-type

This completer takes an extended regex passed to `grep -E` to filter the results.


```yaml
prog: "example"
options:
  - option_strings: ["--image"]
    complete: ["mime_file", 'image/']
```

```
~ > example --image=<TAB>
dir1/  dir2/  img.png  img.jpg
```

---

### pid

> Complete a PID

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

```
~ > example --pid=<TAB>
1       13      166     19      254     31      45
1006    133315  166441  19042   26      32      46
10150   1392    166442  195962  27      33      4609
```

**SEE ALSO**

- [process](#process): For completing a process name

---

### process

> Complete a process name

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

```
~ > example --process=s<TAB>
scsi_eh_0         scsi_eh_1       scsi_eh_2      scsi_eh_3  scsi_eh_4
scsi_eh_5         sh              sudo           syndaemon  systemd
systemd-journald  systemd-logind  systemd-udevd
```

**SEE ALSO**

- [pid](#pid): For completing a PID

---

### range

> Complete a range of integers

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

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

---

### service

> Complete a SystemD service

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

```
~ > example --service=<TAB>
TODO
[...]
```

---

### signal

> Complete signal names

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

```
~ > example --signal=<TAB>
ABRT    -- Process abort signal
ALRM    -- Alarm clock
BUS     -- Access to an undefined portion of a memory object
CHLD    -- Child process terminated, stopped, or continued
CONT    -- Continue executing, if stopped
FPE     -- Erroneous arithmetic operation
HUP     -- Hangup
ILL     -- Illegal instruction
INT     -- Terminal interrupt signal
[...]
```

---

### uid

> Complete a user id

```yaml
prog: "example"
options:
  - option_strings: ["--uid"]
    complete: ["uid"]
```

```
~ > example --uid=<TAB>
0      -- root
1000   -- braph
102    -- polkitd
133    -- rtkit
14     -- ftp
1      -- bin
2      -- daemon
33     -- http
65534  -- nobody
[...]
```

**SEE ALSO**

- [user](#user): For completing a user name

---

### user

> Complete a username

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

```
~ > example --user=<TAB>
avahi                   bin                     braph
colord                  daemon                  dbus
dhcpcd                  ftp                     git
[...]
```

**SEE ALSO**

- [uid](#uid): For completing a user id

---

### value\_list

> Complete a comma-separated list of values

Complete one or more items from a list of items. Similar to `mount -o`.
 
Arguments are supplied by adding `{"values": ...}`.
 
A separator can be supplied by adding `{"separator": ...}` (the default is `","`).
 
By default, duplicate values are not offered for completion. This can be changed by adding `{"duplicates": true}`.


```yaml
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 --value-list-1=<TAB>
exec    noexec
~ > example --value-list-1=exec,<TAB>
noexec
~ > example --value-list-2=<TAB>
one  -- Description 1
two  -- Description 2
```

**SEE ALSO**

- [list](#list): For completing a comma-separated list of any completer

- [key\_value\_list](#key_value_list): For completing a comma-separated list of key=value pairs

---

### variable

> Complete a shell variable name

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

```
~ > example --variable=HO<TAB>
HOME      HOSTNAME  HOSTTYPE
```

**SEE ALSO**

- [environment](#environment): For completing an environment variable

---

### combine

> Combine multiple completers

With `combine` multiple completers can be combined into one.

It takes a list of completers as its argument.


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

```
~ > example --user-list=avahi,daemon,<TAB>
1439404  3488332  3571716           3607235                 4134206
alpm     avahi    bin               braph                   daemon
root     rtkit    systemd-coredump  systemd-journal-remote  systemd-network
[...]
```

---

### key\_value\_list

> Complete a comma-separated list of key=value pairs

The first argument is the separator used for delimiting the key-value pairs.

The second argument is the separator used for delimiting the value from the key.

The third argument is a list of key-description-completer definitions, like:

  `[ [<key>, <description>, <completer>], ... ]`

If a key does not take an argument, use `null` as completer.

If a key does take an argument but cannot be completed, use `['none']` as completer.


```yaml
prog: "example"
options:
  - option_strings: ["--key-value-list"]
    complete: ["key_value_list", ",", "=", [
      ['flag',   'An option flag', null],
      ['nodesc', null, null],
      ['nocomp', 'An option with arg but without completer', ['none']],
      ['user',   'Takes a username',  ['user']],
      ['check',  'Specify file name conversions', ['choices', {
        'relaxed': "convert to lowercase before lookup",
        'strict': "no conversion"
      }]]
    ]]
```

```
~ > example --key-value-list flag,user=<TAB>
bin                     braph
colord                  dbus
dhcpcd                  git
```

**SEE ALSO**

- [list](#list): For completing a comma-separated list of any completer

- [value\_list](#value_list): For completing a comma-separated list of values

---

### list

> Complete a comma-separated list of any completer

The separator can be changed by adding `{"separator": ...}`.

By default, duplicate values are not offered for completion. This can be changed by adding `{"duplicates": true}`.


```yaml
prog: "example"
options:
  - option_strings: ["--user-list"]
    complete: ["list", ["user"]]
  - option_strings: ["--option-list"]
    complete: ["list", ["choices", ["setuid", "async", "block"]], {"separator": ":"}]
```

```
~ > example --user-list=avahi,daemon,<TAB>
bin                     braph
colord                  dbus
dhcpcd                  git
```

**SEE ALSO**

- [value\_list](#value_list): For completing a comma-separated list of values

- [file\_list](#file_list): For completing a comma-separated list of files

- [directory\_list](#directory_list): For completing a comma-separated list of directories

- [key\_value\_list](#key_value_list): For completing a comma-separated list of key=value pairs

---

### none

> No completion, but specifies that an argument is required

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

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


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

```
~ > example --none=<TAB>
<NO OUTPUT>
```

---

### prefix

> Prefix completion by a string

The first argument is the prefix that should be used.

The second argument is a completer.


```yaml
prog: "example"
options:
  - option_strings: ["--prefix"]
    complete: ["prefix", "input:", ['file']]
```

```
~ > example --prefix=<TAB>
~ > example --prefix=input:

~ > example --prefix=input:<TAB>
~ > example --prefix=input:file1.txt
```

---

### exec

> Complete by the output of a command or function

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.


**NOTES**

- Functions can be put inside a file and included with `--include-file`

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

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

**SEE ALSO**

- [exec\_fast](#exec_fast): Faster implementation of exec

---

### exec\_fast

> Complete by the output of a command or function (fast and unsafe)

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.


**NOTES**

- Functions can be put inside a file and included with `--include-file`

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

```
~ > example --exec-internal=<TAB>
1  -- one
2  -- one
```

---

### exec\_internal

> Complete by a function that uses the shell's internal completion mechanisms

Execute a function that internally modifies the completion state.

This is useful if a more advanced completion is needed.

For **Bash**, it might look like:

```sh
my_completion_func() {
    COMPREPLY=( $(compgen -W "read write append" -- "$cur") )
}
```

For **Zsh**, it might look like:

```sh
my_completion_func() {
    local items=(
        read:'Read data from a file'
        write:'Write data from a file'
        append:'Append data to a file'
    )

    _describe 'my items' items
}
```

For **Fish**, it might look like:

```sh
function my_completion_func
    printf '%s\t%s\n' \
        read 'Read data from a file'  \
        write 'Write data from a file' \
        append 'Append data to a file'
end
```


**NOTES**

- Functions can be put inside a file and included with `--include-file`

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

```
~ > example --exec-internal=<TAB>
append  -- Append data to a file
read    -- Read data from a file
write   -- Write data from a file
```

### Options

**--version**

> Show program version

---

**--help**

> Show program help

---

**--manual=[TOPIC]**

> Show a manual for a help topic

---

**--input-type=TYPE** *(yaml, json, python, help, auto)*

> Specify input file type. If "auto", input type is determined by the file extension

For security reasons, reading python files must be explicitly enabled.

This option defaults to `auto`.

---

**--abbreviate-commands=BOOL** *(True, False)*

> Sets whether sub commands can be abbreviated

This option defaults to `False`.

---

**--abbreviate-options=BOOL** *(True, False)*

> Sets whether options can be abbreviated

Currently only supported in Bash.

This option defaults to `False`.

---

**--repeatable-options=BOOL** *(True, False)*

> Sets whether options are suggested multiple times during completion

This only overrides the `repeatable` parameter of options that don't have
it explicitly set to `True` or `False`.

If you wish to make all options repeatable regardless of how they are
defined in the definition file, use `--disable=repeatable`.

This option defaults to `False`.

---

**--inherit-options=BOOL** *(True, False)*

> Sets whether parent options are visible to subcommands

This option defaults to `False`.

---

**--option-stacking=BOOL** *(True, False)*

> Sets whether short option stacking is allowed

Enables or disables short option stacking, where multiple short options are
combined in a single argument (e.g. `-fo` instead of `-f -o`).

This option defaults to `True`.

---

**--long-option-argument-separator=SEPARATOR** *(space, equals, both)*

> Sets which separators are used for delimiting a long option from its argument

If `space`, only the form `--option argument` is allowed.
If `equals`, only the form `--option=argument` is allowed.
If `both`, both forms are allowed.

Currently only supported in Bash and Zsh.

This option defaults to `both`.

---

**--disable=FEATURES** *(hidden, final, groups, repeatable, when)*

> Disable features

- hidden: Disable hidden options
- final: Disable final options
- groups: Disable option groups
- repeatable: Make all options repeatable
- when: Disable conditional options and positionals

---

**--vim-modeline=BOOL** *(True, False)*

> Sets whether a vim modeline comment shall be appended to the generated code

The modeline comment looks like this:

  `# vim: ft=zsh ts=2 sts=2 sw=2 et`

This option defaults to `True`.

---

**--bash-completions-version=VERSION**

> Generate code for a specific bash-completions version

Use a value greater or equal to `2.12` to generate code for the "new"
version of bash-completions.

This option defaults to `2.0`.

---

**--zsh-compdef=BOOL** *(True, False)*

> Sets whether #compdef is used in zsh scripts

Set this option to `False` if the generated script should be sourcable.

This option defaults to `True`.

---

**--fish-fast=BOOL** *(True, False)*

> Use faster commandline parsing for fish at the cost of correctness

This option defaults to `False`.

---

**--fish-inline-conditions=BOOL** *(True, False)*

> Don't store conditions in a variable

This option defaults to `False`.

---

**--parser-variable=VARIABLE**

> Specify the variable name of the ArgumentParser object (for --input-type=python)

---

**--include-file=FILE**

> Include file in output

---

**--comment=COMMENT**

> Add a comment to output

---

**--keep-comments=BOOL** *(True, False)*

> Keep comments of helper functions used in the generated code

This option defaults to `False`.

---

**--function-prefix=PREFIX**

> Set the prefix for generated functions

The placeholder `$PROG` will be replaced by the program name.

This option defaults to `_$PROG`.

---

**--debug**

> Enable debug mode

Keep comments, generate shell code for debugging and print a full stack
trace in case of an error.

---

**-o|--output=FILE**

> Write output to destination file [default: stdout]

---

**-i|--install-system-wide**

> Write output to the system-wide completions dir of shell

---

**-u|--uninstall-system-wide**

> Uninstall the system-wide completion file for program

## When Conditionals

Options and Positional Arguments can include a `when` attribute that defines
a condition under which the option (or positional argument) should be
activated.

### has\_option

> Checks if one or more specified options have been provided on the command line.

> **NOTE**: The options used inside the condition have also to be defined as options!

**Examples:**

```yaml
# This activates --conditional if --foo, --bar or --baz are present on the command line

[...]
options:
  - option_strings: ["--conditional"]
    when: "has_option --foo --bar --baz"

  - option_strings: ["--foo", "--bar", "--baz"]
[...]
```

### option\_is

> Checks if one ore more specified options have been set to a specific value.

> **NOTE**: The options used inside the condition have also to be defined as options!

**Example:**

```yaml
# This activates --conditional if --foo, --bar or --baz are set to value1, value2 or value3

[...]
options:
  - option_strings: ["--conditional"]
    when: "option_is --foo --bar --baz -- value1 value2 value3"

  - option_strings: ["--foo", "--bar", "--baz"]
    complete: ["none"]
[...]
```

### Multiple conditions

> Multiple conditions can be combined using the logical operators `&&` (**AND**) and `||` (**OR**).

> Expressions can be grouped using parentheses `(` and `)` to control evaluation order.

> The negation operator `!` is also supported for logical **NOT** expressions.

**Example:**

```yaml
# This activates --conditional if --foo is given but --bar is not given.

[...]
options:
  - option_strings: ["--conditional"]
    when: "has_option --foo && ! has_option --bar"

  - option_strings: ["--foo"]

  - option_strings: ["--bar"]
[...]
```

## Capturing Options

Options can include a `capture` field to store their values for later use.

The value of `capture` is the **name of a variable** that will receive all values passed to that option.

- The captured variable is always an **array**, containing one element for each occurence of the option on the command line.
- This makes it easy to implement **context-sensitive completions** that depend on previously supplied option values

> **NOTE:** There is currently **no automatic check for name clashes** between your capture variables and the parser's internal variables.
> To minimize the risk of conflicts, it is recommended to prefix variable names with `CAPTURE_` or `CAPTURED_`.

> **NOTE:** Captured variables are currently only available in **Bash** and **Zsh**.

**Example:**

```yaml
prog: my_db_tool
options:
  - option_strings: ["--database", "-d"]
    complete: ["choices", ["mysql", "postgres", "sqlite"]]
    capture: "CAPTURED_DB"

  - option_strings: ["--table", "-t"]
    complete: ["exec", "_my_db_tool_complete_table"]
```

For **Bash** and **Zsh**:

```bash
_my_db_tool_complete_table() {
  case "${CAPTURED_DB[-1]}" in
    mysql)    printf '%s\n' users orders products;;
    postgres) printf '%s\n' customers invoices transactions;;
    sqlite)   printf '%s\n' local_cache config sessions;;
  esac
}
```

## Tips and Tricks

It is always recommended to define your command line **as precisely as possible**.
This helps crazy-complete generate reliable completions. Key practices include:
- **Final options**: Use `final: true` for options like `--help` and `--version` that should
  prevent further options from being completed
- **Hidden options**: Use `hidden: true` for options that should be completable but not shown
  in the suggestion list
- **Mutually exclusive options**: Use `groups: [...]` to define sets of options that cannot appear
    together
- **Repeatable options**: Use `repeatable: true` for options that may be used more than once

### Trying out zsh autocompletion scripts

By default, crazy-complete generates scripts that should be installed under `/usr/share/zsh/site-functions`
and loaded from there. If you want to try the generated scripts directly, use `--zsh-compdef=False`.

### Optimizing Script Output

Especially for **Fish** scripts, performance can decrease if many options are defined.
Features like final options and non-repeatable options require extra conditional code to execute, which can make completions slower.

To improve performance these features can be completely disabled using:

```
crazy-complete fish --disable=final,repeatable DEFINITION_FILE
```

This turns off final and repeatable option handling, reducing script size and improving completion speed