Shell Completion

Generating Completion Scripts

Every command can automatically generate its shell completion script.

The supported shell environments are:

• bash
• zsh

To generate a script, use the generate_xxx_completion method of a command class.

class TicketToRide < Cli::Command
  class Options
    string "--by", any_of: %w(train plane taxi)
    arg "for", any_of: %w(kyoto kanazawa kamakura)
  end
end

puts TicketToRide.generate_bash_completion
# or
puts TicketToRide.generate_zsh_completion

See the gist for bash and the gist for zsh.

Zsh: Function vs Sourced Script

By default, generate_zsh_completion returns a script used as a zsh function. To generate a script that can be sourced, set the functional option to false.

TicketToRide.generate_zsh_completion(functional: false)

Setting Completion Methods

You can set a completion method to each command line option/argument.

The method types are:

• word-list
• action
• command

Word-List

An Array(String) value that replies word strings as completions.

class Horoscope < Cli::Command
  class Options
    string "--star", complete: %w(
      aries
      taurus
      gemini
      cancer
      leo
      virgo
      libra
      scorpio
      sagittarius
      capricorn
      aquarius
      pisces
    )
  end
end

An output example:

$ horoscope --star
aries        gemini       leo          libra        sagittarius  aquarius
taurus       cancer       virgo        scorpio      capricorn    pisces
$ horoscope --star a
aries  aquarius

Inclusion Validations

If an inclusion or element inclusion validation is specified, the expected values are implicitly used as a word-list. If both the complete and the any_of/any_item_of options are specified, the complete option is prioritized.

Action

A Symbol value that is set as an -A option of the Bash's compgen command.

The available types are:

• alias
• arrayvar
• binding
• builtin
• command
• directory
• disabled
• enabled
• export
• file
• function
• group
• helptopic
• hostname
• job
• keyword
• running
• service
• setopt
• shopt
• signal
• stopped
• user
• variable

class Myexec < Cli::Command
  class Options
    arg "command_name", complete: :command
  end
end

An output example:

$ myexec
Display all 2097 possibilities? (y or n)
$ myexec cr
crenv    cron     crontab  crystal

For more information about the compgen's -A option, see the Bash's manual.

Emulating the Action on Zsh (Experimental)

For Zsh, a generated script emulates the compgen command by the environment-dependent code.

Command

A String value that specfies a custom command execution.

class CompileCrystal < Cli::Command
  class Options
    arg "file", complete: "find src -regex '.*\\.cr$'"
  end
end

An output example:

$ compile-crystal
src/cli/command.cr
src/cli/command_base.cr
src/cli/command_class.cr
src/cli/exceptions.cr
src/cli/help.cr
src/cli/help_class.cr
src/cli/helps/command.cr
src/cli/helps/supercommand.cr
src/cli/macros/__any_item_of.cr
src/cli/macros/__any_of.cr
src/cli/option_metadata.cr
src/cli/option_model/dsl.cr
src/cli/option_model.cr
src/cli/option_model_definition_mixins/base.cr
src/cli/option_model_definitions/subcommand.cr
src/cli/option_value_metadata.cr
src/cli/supercommand.cr
src/cli/util/var.cr
src/cli/version.cr
src/cli.cr
$ compile-crystal src/cli/o
src/cli/option_metadata.cr
src/cli/option_model/dsl.cr
src/cli/option_model.cr
src/cli/option_model_definition_mixins/base.cr
src/cli/option_model_definitions/subcommand.cr
src/cli/option_value_metadata.cr