Argc

A sh/bash cli framework. Generate cli inteface from comments

Get Started

Write the following demo.sh script

# @flag     -q --quit                   Do not print anything to stdout
# @option   --grep* <REGEX>             Limit the commits output
# @option   --color[auto|always|never]  Print colorful output 
# @arg      pathspec+                   Files to handle

Argc parses command arguments and prints variables

argc demo.sh --grep FOO --grep BAR BAZ -q README.md CHANGELOG.md

argc_quit=1
argc_grep=( "FOO" "BAR" "BAZ" )
argc_color="auto"
argc_pathspec=( "README.md" "CHANGELOG.md" )

Argc recognizes -h option and prints help text

argc demo.sh -h

demo 

USAGE:
    demo [OPTIONS] <PATHSPEC>...

ARGS:
    <PATHSPEC>...    Files to handle

OPTIONS:
        --color <COLOR>      Print colorful output [default: auto] [possible values: auto, always,
                             never]
        --grep <REGEX>...    Limit the commits output
    -h, --help               Print help information
    -q, --quit               Do not print anything to stdout

Argc identifies parameter errors and prints error text

argc demo.sh --color=none

error: "none" isn't a valid value for '--color <COLOR>'
        [possible values: auto, always, never]

USAGE:
    demo --color <COLOR> <PATHSPEC>...

For more information try --help

How Argc works:

1. Extract parameter definitions from script comments
2. Parse command line arguments
3. If the parameter is abnormal, output error text or help information
4. If everything is normal, output the parsed parameter variable

res=$(argc $0 "$@")
if [ $? -eq  1 ]; then
    echo -n $res # print help text or error messages
    exit 1
fi
eval "$res" # load generated variables

echo ${argc_pathspec[@]}

The above code is too redundant, and Argc provides the -e option to rescue

eval "(argc -e $0 "$@")"

echo ${argc_pathspec[@]}

Tag

Argc generates parsing rules and help documentation based on tags (fields marked with @ in comments).

# @describe   A fictional versioning CLI
# @version    2.17.1 
# @author     nobody <nobody@example.com>
# @flag       --no-pager          Do not pipe Git output into a pager
# @option     --git-dir=.git      Set the path to the repository

# @cmd        Shows the commit log.
# @arg        refspec*            Specify what destination ref
log() {
    echo git log ${argc_refspec[@]}
}

test2 2.17.1
nobody <nobody@example.com>
A fictional versioning CLI

USAGE:
    test2 [OPTIONS] <SUBCOMMAND>

OPTIONS:
        --git-dir <GIT-DIR>    Set the path to the repository [default: .git]
    -h, --help                 Print help information
        --no-pager             Do not pipe Git output into a pager
    -V, --version              Print version information

SUBCOMMANDS:
    help    Print this message or the help of the given subcommand(s)
    log     Shows the commit log.

@describe

# @describe [string]

# @describe A fictional versioning CLI

Define description

@version

# @version [string]
# @version 2.17.1 

Define version

@author

# @author [string]
# @author nobody <nobody@example.com>

Define author

@cmd

# @cmd [string]

# @cmd Shows the commit log.
log() {
}

Define subcommand

@option

# @cmd [short] [long][modifer] [notation] [string]

# @option -j, --threads <NUM>       Number of threads to use.
# @option --grep* <PATTERN>
# @option --dump-format[=json|yaml]
# @option --shell-arg=-cu 

Define value option

modifer

The symbol after the long option name is the modifier, such as * in --grep*

• *: occur multiple times, optional
• +: occur multiple times, required
• !: required
• =value: default value
• [a|b|c]: choices
• [=a|b|c]: choices, first is default.

notation

Used to indicate that the option is a value option, other than a flag option.

If not provided, the option name is used as a placeholder by default.

You can use placeholder hint option value types <NUM>, <PATH>, <PATTERN>, <DATE>

@flag

# @flag [short] [long] [help string]

## @flag  --no-pager
## @flag  -q, --quiet Do not print anything to stdout

Define flag option

@arg

# @arg <name>[modifer] [help string]

## @arg pathspec* Files to add content from.

Define positional arguement

modifer

• *: occur multiple times, optional
• +: occur multiple times, required
• !: required

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.