DannyBen/bashly

# Bash Completions Example

Demonstrates how to build a script that supports bash completions.

This example was generated with:

```bash
$ bashly init
# ... now edit src/bashly.yml to match the example ...
$ bashly add completions
$ bashly generate
# ... now edit src/completions_command.sh ...
$ bashly generate
```

<!-- include: src/completions_command.sh -->

-----

## `bashly.yml`

````yaml
name: cli
help: Sample application with bash completions
version: 0.1.0

# All commands and flags will be automatically used in the completions script
commands:
- name: completions
  help: |-
    Generate bash completions
    Usage: eval "\$(cli completions)"

- name: download
  alias: d
  help: Download a file

  # Adding custom completions for a command. In this case, typing
  # `cli download <TAB>` will suggest files.
  completions:
  - <file>

  args:
  - name: source
    required: true
    help: URL to download from
  - name: target
    help: "Target filename (default: same as source)"

  flags:
  - long: --force
    short: -f
    help: Overwrite existing files
  - long: --handler
    arg: command

    # The allowed flag arg whitelist will be added automatically. In this case,
    # typing `cli download --handler <tab>` will suggest curl or wget
    allowed:
      - curl
      - wget

    default: curl

  examples:
  - cli download example.com
  - cli download example.com ./output -f

  environment_variables:
  - name: default_target_location
    help: Set the default location to download to

- name: upload
  alias: u
  help: Upload a file

  # Add directories and users to the suggested completions.
  completions:
    - <directory>
    - <user>

  args:
  - name: source
    required: true
    help: File to upload

    # The allowed argument whitelist will be added automatically. In this case
    # typing `cli upload <TAB>` will suggest these files.
    allowed:
      - README.md
      - CHANGELOG.md

  flags:
  - long: --user
    short: -u
    arg: user
    help: Username to use for logging in
    required: true

    # Adding completions to a flag with an argument will add it to the suggested
    # words list. In this case typing `cli upload --user <TAB>` will suggest
    # users.
    completions:
      - <user>

  - long: --password
    short: -p
    arg: password
    help: Password to use for logging in
````

## `src/completions_command.sh`

````bash
# Call the `send_completions` function which was added by running:
#
#   $ bashly add completions
#
# Users can now enable bash completion for this script by running:
#
#   $ eval "$(cli completions)"
#
send_completions

````


## Output

### `$ ./cli`

````shell
cli - Sample application with bash completions

Usage:
  cli COMMAND
  cli [COMMAND] --help | -h
  cli --version | -v

Commands:
  completions   Generate bash completions
  download      Download a file
  upload        Upload a file



````

### `$ ./cli -h`

````shell
cli - Sample application with bash completions

Usage:
  cli COMMAND
  cli [COMMAND] --help | -h
  cli --version | -v

Commands:
  completions   Generate bash completions
  download      Download a file
  upload        Upload a file

Options:
  --help, -h
    Show this help

  --version, -v
    Show version number



````

### `$ ./cli completions -h`

````shell
cli completions

  Generate bash completions
  Usage: eval "$(cli completions)"

Usage:
  cli completions
  cli completions --help | -h

Options:
  --help, -h
    Show this help



````

### `$ ./cli completions`

````shell
# cli completion                                           -*- shell-script -*-

# This bash completions script was generated by
# completely (https://github.com/dannyben/completely)
# Modifying it manually is not recommended

_cli_completions_filter() {
  local words="$1"
  local cur=${COMP_WORDS[COMP_CWORD]}
  local result=()

  if [[ "${cur:0:1}" == "-" ]]; then
    echo "$words"

  else
    for word in $words; do
      [[ "${word:0:1}" != "-" ]] && result+=("$word")
    done

    echo "${result[*]}"

  fi
}

_cli_completions() {
  local cur=${COMP_WORDS[COMP_CWORD]}
  local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")
  local compline="${compwords[*]}"

  case "$compline" in
    'download'*'--handler')
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "curl wget")" -- "$cur")
      ;;

    'upload'*'--user')
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A user -- "$cur")
      ;;

    'completions'*)
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--help -h")" -- "$cur")
      ;;

    'd'*'--handler')
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "curl wget")" -- "$cur")
      ;;

    'upload'*'-u')
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A user -- "$cur")
      ;;

    'download'*)
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A file -W "$(_cli_completions_filter "--force --handler --help -f -h")" -- "$cur")
      ;;

    'u'*'--user')
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A user -- "$cur")
      ;;

    'upload'*)
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A directory -A user -W "$(_cli_completions_filter "--help --password --user -h -p -u CHANGELOG.md README.md")" -- "$cur")
      ;;

    'u'*'-u')
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A user -- "$cur")
      ;;

    'd'*)
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A file -W "$(_cli_completions_filter "--force --handler --help -f -h")" -- "$cur")
      ;;

    'u'*)
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A directory -A user -W "$(_cli_completions_filter "--help --password --user -h -p -u CHANGELOG.md README.md")" -- "$cur")
      ;;

    *)
      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_cli_completions_filter "--help --version -h -v completions d download u upload")" -- "$cur")
      ;;

  esac
} &&
  complete -F _cli_completions cli

# ex: filetype=sh


````