An elegant command-line options, arguments and sub-commands parser for bash.
cargo install argc
Download from Github Releases, unzip and add argc to your $PATH.
extractions/setup-crate can be used to install just in a GitHub Actions workflow.
yaml
- uses: extractions/setup-crate@v1
with:
owner: sigoden
name: argc
To write a command-line program with argc, we only need to do two things:
eval "$(argc --argc-eval "$0" "$@")" into script to let argc to parse command line arguments.Write example.sh
```sh
eval "$(argc --argc-eval "$0" "$@")" echo foo: $argcfoo echo bar: $argcbar echo baz: ${argc_baz[@]} ```
Run ./example.sh --foo --bar=xyz a b c, you can see argc successfully parses arguments and generate variables with argc_ prefix.
foo: 1
bar: xyz
baz: a b c
Run ./example.sh -h, argc wll print help information for you.
``` USAGE: example.sh [OPTIONS] [BAZ]...
ARGS: [BAZ]... Positional values
OPTIONS:
--foo Flag value
--bar
argc parses cli definition from comment tags.
@cmd [string]
Define a subcommand
```sh
upload() { echo Run upload }
download() { echo Run download } ```
```
USAGE: test.sh
COMMANDS: upload Upload a file download Download a file ```
@arg <name>[modifier|default|modifer+choices] [zero-or-one value notation] [help-string]
Define a positional argument.
```sh
_default_fn default from fn_choice_fn] choice from fn_choice_fn] choice from fn + no validation_choice_fn] multiple + choice from fn```
@option [short] <long>[modifier|default|modifier+choices] [value-notation]... [help-string]
Define a option.
```sh
_default_fn default from fn_choice_fn] choice from fn_choice_fn] choice from fn + no validation_choice_fn] multiple + choice from fn```
@flag [short] <long>[*] [help string]
Define a flag. A flag is an option of boolean type, and is always false by default (e.g. --verbose, --quiet, --all, --long, etc).
```sh
```
@alias <name...>
Add aliases for subcommand.
```sh
test() { echo Run test } ```
```
USAGE: test.sh
COMMANDS: test Run tests [aliases: t, tst] ```
```sh
test() { echo Run test } ```
``` test.sh 2.17.1 nobody nobody@example.com A demo cli
USAGE: test.sh
COMMANDS: test Run test ```
Value notation is used to describe value type of options and positional parameters.
```
```
Here are some value notation that will affect the shell completion.
FILE/PATH: complete filesDIR: complete directoriesArgc provides shell completion for argc command and all the bash scripts powered by argc.
```
source <(argc --argc-completions bash mycmd1 mycmd2)
eval (argc --argc-completions elvish mycmd1 mycmd2 | slurp)
argc --argc-completions fish mycmd1 mycmd2 | source
argc --argc-completions nushell mycmd1 mycmd2 # update config.nu manually according to output
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete argc --argc-completions powershell mycmd1 mycmd2 | Out-String | Invoke-Expression
exec($(argc --argc-completions xonsh mycmd1 mycmd2))
source <(argc --argc-completions zsh mycmd1 mycmd2) ```
Replace mycmd1 mycmd2 with your argc scripts.
Argc can be used as multiple shell completion engine. see argc-completions
Argc will automatically find and run Argcfile.sh unless --argc-* options are used to change this behaviour.
Argcfile is to argc what Makefile is to make.
what is the benefit?
You can use argc --argc-create to quickly create boilerplate Argcscripts. For example:
argc --argc-create test build run
The above command will create an Argcfile.sh in the current directory containing the commands: test, build and run.
argc provides features for running commands/functions in parallel.
sh
argc --argc-parallel "$0" cmd1 arg1 arg2 ::: cmd2
The above command will run cmd1 arg1 arg2 and cmd2 in parellel. Functions running in parallel mode can still access the argc_* variable.
Argc requires bash to run scripts. git's built-in bash is good enough for argc.
If you want to use another bash, please specify it via ARGC_SHELL_PATH environment variable.
If you want to run the bash script directly, you can add the following configuration to Windows Registry.
```ps1
New-ItemProperty -LiteralPath 'HKLM:\SOFTWARE\Classes\shautofile\shell\open\command' ` -Name '(default)' -Value '"C:\Program Files\Git\bin\bash.exe" "%1" %*' -PropertyType String -Force ```
argc is made available under the terms of either the MIT License or the Apache License 2.0, at your option.
See the LICENSE-APACHE and LICENSE-MIT files for license details.