=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.46.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 Name

complete-shell - Modern Tab Completion Everywhere

=head1 Synopsis

# Install the complete-shell software:
git clone https://github.com/complete-shell/complete-shell
source /path/to/complete-shell/.rc

# Turn on the cool modern features (off by default):
complete-shell config modern_settings true

# Try tab completion:
complete-shell <tab><tab>

# Search for existing complete-shell packages:
complete-shell search

# Install the packages you like:
complete-shell install this-cmd
complete-shell install another-cmd

this-cmd <TAB><TAB> # Completion should work!

# Write your own compdef files. (See below)
# Add your compdef files:
complete-shell add ./src/foo.comp

# Learn the other complete-shell commands:
complete-shell -h # Quick reference
complete-shell help # Complete documentation

=head1 Status

WARNING: THIS FRAMEWORK IS VERY NEW.

=over

=item * Only works on Bash so far

=item * Only tested on Mac and Ubuntu Linux so far

=back

Pull Requests welcome!

=head1 Description

CompleteShell adds command completion for everything, everywhere. It provides
a framework to define command completion in a simple, single file format.

CompleteShell works in:

=over

=item * Bash

=item * zsh (coming soon)

=item * Fish (coming soon)

=back

People can easily write complete-shell files for commands that don't yet have
completion and share them with the world. They can also write their own custom
files, or fine tune existing ones to their liking.

CompleteShell also does Bash completion like you've never seen it. It can show
you completion descriptions, show command usage, show hints to help you along,
and turn on the more modern Bash completion options (like pressing TAB once
instead of twice). These things are configurable by you.

=head1 Installation

Run these commands:

# clone the Git repo:
git clone https://github.com/complete-shell/complete-shell

# `source` the `.rc` file in your shell startup configuration file:
source /path/to/complete-shell/.rc

That's it!

You should also really try turning on the cool modern settings:

complete-shell config modern_settings true

=head2 Prerequisites

=over

=item Bash 3.2+

Even if you don't use Bash as your shell, C<complete-shell> needs it because
it is written in Bash. Fortunately most computers have Bash 3.2+ installed.

=item Git

Git is used for getting compdef repos to install and also is used for its
(totally awesome) command line options parsing facility.

=item Completion Subsystem

CompleteShell attempts to fit into your Shell's existing Completion system.

For Bash, there is system that almost everyone uses. It can usually be found
in C</usr/share/bash-completion/> or C</etc/bash_completion*> (older systems
and Mac). CompleteShell will check to make sure this subsystem is in place.

For Zsh and Fish, completion facilities are first class parts of the shell.
CompleteShell will compile to code that fits right in.

=back

=head1 The C<complete-shell> CLI

=over

=item C<complete-shell help>

Display the complete-shell manpage. Same as C<man complete-shell>.

The C<-h> option will display a quick reference help guide.

=item C<< complete-shell config [<key> [<value>]] >>

With no arguments, show all settings. With 1 argument, print the value for a
key. With 2 arguments, set a key to a value.

Config values are stored in C<< $COMPLETE_SHELL_BASE/config/<shell> >>
(usually C<~/.complete-shell/config/bash>).

See "Configuration Options" below.

=item C<< complete-shell search [<search string>] >>

Find registered completion packages that are available online.

=item C<complete-shell list>

List all your installed completion packages.

=item C<< complete-shell show <compdef-name> >>

Show information about a completion definition.

=item C<< complete-shell install <package> >>

Installs compdef files from git repos online. You can find these repos using
the C<search> command or use other ones that you know about. C<compdef-target>
can be a simple name (found in search) or a git repo URL.

=item C<< complete-shell add <compdef-filepath> >>

Adds a local compdef file path to your installed completions. It will be
enabled by default.

=item C<< complete-shell delete <compdef-name> >>

Delete a compdef file from your configuration.

=item C<< complete-shell disable <compdef-name> >>

Disable a compdef (but don't delete it). Use this to turn off a specific
command completion temporarily. Use the C<enable> command to turn it back on.

=item C<< complete-shell enable <compdef-name> >>

Enable a compdef. Usually only after you have disabled it.

=item C<< complete-shell update <compdef-name> >>

Update specific compdef to their latest version.

=item C<complete-shell upgrade>

Upgrade your C<complete-shell> installation to the latest version.

=item C<< complete-shell compile <compdef-name-or-path> >>

Compdef files are themselves valid shell files. (A common subset of Bash, Zsh
and Fish!). They get compiled into leaner shell-specific files that are tuned
for the tab completion facilities of the particular shell.

=item `complete-shell alias <compdef-name> <alias-name>

This command will create an alias completion for an existing alias of a
command. command completion. Try making the alias C<cs> for the command
C<complete-shell>:

alias cs=complete-shell
complete-shell alias complete-shell cs

=back

=head1 Configuration Options

These options all default to C<false>. To turn on an option:

complete-shell config <option> true

=over

=item C<disabled>

Disable CompleteShell tab completion altogether.

=item C<modern_settings>

An umbrella option to always use the most modern CompleteShell settings.
Effectively set these to true: C<single_tab>, C<no_prompt>,
C<show_descriptions>, C<show_usage>, C<show_hints>.

=item C<single_tab>

Only require a single TAB press to trigger completion. By default, Bash
requires you to press TAB twice.

=item C<no_prompt>

Disable prompt for more than 100 completions. When text is too big for the
screen it will start a pager.

=item C<show_descriptions>

CompleteShell completions can have short descriptions. Set this option if you
want to see them.

=item C<show_usage>

Some commands have a defined usage, which is helpful to have when writing the
command. Turn this on to see them.

=item C<show_hints>

CompleteShell can give you hints about certain things when it thinks they'll
be useful. Use this to enable them.

=item C<no_horizontal>

Recent Bash versions allow for completions to be sorted horizontally, which is
usually better. We turn that on for you if available. Use this to keep the
Bash default.

=back

=head1 Environment Variables

CompleteShell has environment variables that you can use to customize various
things. Usually you don't need to worry about these at all.

=over

=item C<COMPLETE_SHELL_ROOT>

The location of the complete-shell software being used.

This variable is required and set automatically for you at shell startup.

If you use C<source /path/to/complete-shell/.rc> to enable complete-shell, it
is set to C</path/to/complete-shell>.

=item C<COMPLETE_SHELL_BASE>

The directory where your completions are installed and your
configuration lives.

Defaults to the last directory in C<COMPLETE_SHELL_PATH>.

=item C<COMPLETE_SHELL_PATH>

A colon separated path variable for finding installed completions.

Defaults to C<$HOME/.complete-shell>

=item C<COMPLETE_SHELL_CONFIG>

Your config file, managed by C<complete-shell config ...>.

Defaults to C<$COMPLETE_SHELL_BASE/config/$COMPLETE_SHELL_SHELL>.

=item C<COMPLETE_SHELL_COMP>

Directory where installed completions go.

Defaults to C<$COMPLETE_SHELL_BASE/comp>.

=item C<COMPLETE_SHELL_SRC>

Directory where completion source repositories are installed (cloned) into.

Defaults to C<$COMPLETE_SHELL_BASE/src>.

=item C<COMPLETE_SHELL_BASH_DIR>

Directory where completions are compiled into (for Bash).

Defaults to C<$COMPLETE_SHELL_BASE/bash-completion/completions>.

=item C<COMPLETE_SHELL_SHELL>

Your shell. ('bash', 'zsh', 'fish').

=back

=head1 The C<compdef> File

A complete-shell "command completion definition" ("compdef" for short) file is
a minimal DSL that allows people to specify how command completion should work
for a given command:

Here is a simple example. Define a file called C<foo.comp>:

# Required header declaring the API version:
CompleteShell v0.2

# Command name:
N foo 0.0.1 ..The mighty foo CLI

# Command options:
O --aaa ..The aaa option
O --bbb =file \
..The bbb option

# Sub-commands:
C bar +str ..Do the bar
C baz +num +dir ..Do the baz

Then run:

complete-shell add foo.comp

Now you have command completion for the C<foo> command!

The C<complete-shell> command itself comes with a compdef file that you can
find in C</path/to/complete-shell/share/complete-shell.comp>.

=head2 compdef File Guidelines

=over

=item * compdef files are named C<< <name>.comp >>

=item * The name should be either:

=over

=item * The name of the CLI command for which it adds support

=item * The name of a project that has multiple commands

=back

=item * Shell specific functions go in C<< <name>.<shell> >>

=over

=item * Bash uses C<< <name>.bash >> or C<< <name>.sh >>

=item * Zsh uses C<< <name>.zsh >> or C<< <name>.sh >>

=item * Fish uses C<< <name>.fish >>

=item * A C<< <name>.sh >> is POSIX shell code that works in Bash or Zsh

=back

=item * A compdef file can define completions for one or more commands

=item * A compdef Git repo contains one or more compdef files

=over

=item * A set of compdef files is called a package

=back

=item * A compdef file uses the syntax described in the next section

=back

=head2 The C<compdef> Language

The compdef files are written in a simple DSL. The DSL has a set of simple
commands that are usually a single capital letter. Blank lines and C<#>
comments are supported.

The DSL happens to a common subset of the Bash, Zsh and Fish shell languages,
but compdef files should not contain any statements that are not documented
by the DSL.

The DSL is versioned and can change over time. It is designed to be forward
and backward compatible. ie People can use compdef files of any DSL
version, and authors can not worry about their compdefs breaking with
future C<complete-shell> releases. Users B<will> need to upgrade C<complete-
shell> to at least the version of the most modern compdef file's API
version that they want to use.

=head2 The C<compdef> v0.2 Syntax

A compdef files consists of comments, blank lines and single-line command
statements.

Note: the single-line commands can actually span multiple lines by using C<\>
continuation.

This is a list of the compdef statement commands:

=over

=item C<CompleteShell v0.2>

The first statement in every compdef file must be C<CompleteShell> and must
have a version argument as shown above. The version is used to invoke the
appropriate compiler and runtime for that file.

=item C<< N <name> [<version-number>] [..<description>] >>

The name of the statement for which completion is being defined. This is the
second statement in the file. All other statements apply to this C<name> until
the end of file or another C<N> command starts a new definition. Version
numbers must be of the form C<#.#.#>.

=item C<< O <--option> >>

This defines an option that applies to the CLI command. C<O> is also used to
define options that are specific to a sub-command (when they follow the sub-
command's C<C> command).

=item C<< A <+arg-type>... >>

This defines the arguments and their types. An arg type always starts with a
C<+> character. For example, C<+file-path> called a function named C<file-
path> to list the completions that can happen for that argument. C<A> can be
used for a normal command, or for sub-commands.

=item C<< C <subcommand name> >>

This defines a subcommand that applies to the CLI command.

=item C<< V @<var-name> = <set of command words> >>

For the purposes of reusing common definitions, C<V> lets you define
variables. The variables always begin with a C<@>.

=back

=head2 Sharing C<compdef> Files

Sharing compdef files is simple. Create a Git repo for your compdef files:

ReadMe # Describe your repo
foo.comp # compdef for the foo command
foo.sh # Helper shell functions for `foo` completion
bars.comp # compdef for the (several) bar commands

Then push it to a public Git host, like GitHub or BitBucket.

If you want it to be found in the C<complete-shell search> command, then
register it with complete-shell:

=over

=item * Fork/clone L<https://github.com/complete-shell/complete-shell>

=item * Add your repo to the C<share/search-index.txt> file

=item * Commit and push

=item * Create a GitHub Pull Request

=back

=head1 Copyright and License

Copyright 2019. Ingy döt Net <ingy@ingy.net>.

CompleteShell is released under the MIT license.

See the file LICENSE for more details.

=cut