Skip to content
/ argc Public
forked from sigoden/argc

A handy way to handle sh/bash cli parameters.

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

veyh/argc

 
 

Repository files navigation

Argc

CI Crates

Easily parse command line arguments in bash.

demo

Install

With cargo

cargo install argc

Binaries on macOS, Linux, Windows

Download from Github Releases, unzip and add argc to your $PATH.

GitHub Actions

extractions/setup-crate can be used to install just in a GitHub Actions workflow.

- uses: extractions/setup-crate@v1
  with:
    owner: sigoden
    name: argc

Usage

To write a command-line program with argc, we only need to do two things:

  1. Describe options, flags, positional parameters and subcommands in comments.
  2. Insert eval $(argc "$0" "$@") into script to let argc to parse command line arguments.

Write example.sh

# @flag   --foo   A flag
# @option --bar   A option
# @option --baz*  A option with multiple values 

eval $(argc "$0" "$@")
echo foo: $argc_foo
echo bar: $argc_bar
echo baz: ${argc_baz[@]}

Run ./example.sh --foo --bar=value --baz a b c, you can see argc successfully parses arguments and generate variables with argc_ prefix.

foo: 1
bar: value
baz: a b c

Run example.sh -h, argc wll print help information for you.

USAGE: example.sh [OPTIONS]

OPTIONS:
      --foo             A flag
      --bar <BAR>       A option
      --baz [<BAZ>...]  A option with multiple values
  -h, --help            Print help information

Comment Tags

argc parses cli definition from comment tags.

@cmd

@cmd [string]

Define a subcommand

# @cmd Upload a file
upload() {
  echo Run upload
}

# @cmd Download a file
download() {
  echo Run download
}
USAGE: test.sh <COMMAND>

COMMANDS:
  upload    Upload a file
  download  Download a file

@arg

@arg <name>[modifier] [help string]

Define a positional argument.

# @arg arg1            A positional argument
# @arg arg2!           A required positional argument
# @arg arg3*           A positional argument support multiple values
# @arg arg4+           A required positional argument support multiple values
# @arg arg5=a          A positional argument with default value
# @arg arg6[a|b]       A positional argument with choices
# @arg arg7[=a|b]      A positional argument with choices and default value
# @arg arg8![a|b]      A required positional argument with choices

@option

@option [short] <long>[modifier] [notation] [help string]

Define a option.

# @option    --opt1                 A option
# @option -a --opt2                 A option with short alias
# @option    --opt3 <PATH>          A option with notation
# @option    --opt4!                A required option
# @option    --opt5*                A option with multiple values
# @option    --opt6+                A required option with multiple values
# @option    --opt7=a               A option with default value
# @option    --opt8[a|b]            A option with choices
# @option    --opt9[=a|b]           A option with choices and default value
# @option    --opt10![a|b]          A required option with choices
# @option -b --opt11 <PATH>         A option with short alias and notation

@flag

@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).

# @flag     --flag1       A flag
# @flag  -f --flag2       A flag with short alias

@alias

@alias <name...>

Add aliases for subcommand.

# @cmd Run tests
# @alias t,tst
test() {
  echo Run test
}
USAGE: test.sh <COMMAND>

COMMANDS:
  test  Run tests [aliases: t, tst]

@help

@help string

Enable help subcommand.

# @help Show help

# @cmd Run test
test() {
  echo Run test
}
USAGE: test.sh <COMMAND>

COMMANDS:
  help  Show help
  foo   Run test

Meta

  • @describe: Sets the cli’s description.
  • @version: Sets cli's version.
  • @author: Sets cli's author.
# @describe A demo cli
# @version 2.17.1 
# @author nobody <[email protected]>

# @cmd Run test
test() {
  echo Run test
}
test.sh 2.17.1
nobody <[email protected]>
A demo cli

USAGE: test.sh <COMMAND>

COMMANDS:
  test  Run test

Shell Completion

completion scripts are available for bash/zsh/powershell.

All argc scripts share the same completion function. To add completion to a argc script, simply add the script name to $ARGC_SCRIPTS.

License

Copyright (c) 2022 argc-developers.

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.

About

A handy way to handle sh/bash cli parameters.

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Rust 92.6%
  • Shell 5.5%
  • PowerShell 1.9%