Repository files navigation

Creating a bash completion script in a declarative way.

English |中文

• Declarative programming. You only need to know the most basic bash syntax.
• Onlybash andsed are needed on at compile time. Onlybash is needed on at runtime. No other dependencies.
• Support for command format looks like<cmd> [options] [arguments].
• Support for sub-commands, which looks like<cmd> [cmd-options] <subcmd> [subcmd-options] [arguments].
• Support for-o,--option,--option <value>,--option=,+o,+option format.
• Support for completing file or directory paths.
• Support for completing word lists.
• Support for custom completion functions.
• Friendly config typo checking and suggestions.

• For building script.
  • Bash v4.3+
  • cat, sed (GNU or BSD compatible)
• For runtime. Bash v4.0+

Readtags for versions.The versions follow the rules ofSemantic Versioning 2.0.0.

You can install it bycurl orgit.

VERSION=v0.2.0# To download bash-completorcurl -LO"https://github.com/adoyle-h/bash-completor/releases/download/$VERSION/bash-completor{,.md5}"# Check files integritymd5sum -c ./*.md5# Make it executablechmod +x ./bash-completor# Create symbol link or copy it to somewhere in your local $PATHsudo ln -s"$PWD/bash-completor" /usr/local/bin/bash-completor

There is a completion script of bash-completor. You can install it if you need.

# To download the completion script of bash-completorcurl -LO"https://github.com/adoyle-h/bash-completor/releases/download/$VERSION/bash-completor.completion.bash{,.md5}"# Check files integritymd5sum -c ./*.md5# Load the completion script of bash-completor in current shell.$PWD/bash-completor.completion.bash# Autoload it on startupecho".$PWD/bash-completor.completion.bash">>~/.bashrc

VERSION=v0.2.0# Clone this repogit clone --depth 1 --branch"$VERSION" https://github.com/adoyle-h/bash-completor.git# To build bash-completormake build# Create symbol link or copy it to somewhere in your local $PATHsudo ln -s"$PWD/dist/bash-completor" /usr/local/bin/bash-completor# Load the completion script of bash-completor in current shell.$PWD/dist/bash-completor.completion.bash# Autoload the completion script of bash-completor if you need.echo".$PWD/dist/bash-completor.completion.bash">>~/.bashrc

Enterbash-completor for help.

1. Write a config filecompletor.bash.
2. Runbash-completor -c ./completor.bash to generate completion script.

• ./completor.bash It's a simple example. Runmake build to build the completion script of bash-completor.
• zig.completor.bash
• nvim-shell-completions/nvim.completor.bash
• Other examples in./example/

The generated completion script follows below code style. No worry about naming conflict.And it's easy to debug at runtime.

• The main command completion function must be_${cmd}_completions
• All subcmd completion functions must be named with prefix_${cmd}_completions_${subcmd}.
• All other variables and functions must be named with prefix_${cmd}_comp_.
• The variable of main command options must be_${cmd}_comp_cmd_opts.
• The variable of subcmd options must be named with prefix_${cmd}_comp_subcmd_opts_${subcmd}.
• All reply functions must be named with prefix_${cmd}_comp_reply_.
• All customized reply functions must be named with prefix_${cmd}_comp_reply_custom_.

Before opening new Issue/Discussion/PR and posting any comments, please readContributing Guidelines.

Runmake test in shell.

Copyright 2023-2024 ADoyle (adoyle.h@gmail.com). Some Rights Reserved.The project is licensed under theApache License Version 2.0.

See theLICENSE file for the specific language governing permissions and limitations under the License.

See theNOTICE file distributed with this work for additional information regarding copyright ownership.

• lobash: A modern, safe, powerful utility/library for Bash script development.
• one.bash: An elegant framework to manage commands, completions, dotfiles for bash players.
• Other shell projects created by me.