A handy way to handle sh/bash cli parameters

Overview

Argc

CI Crates

A handy way to handle sh/bash cli parameters.

demo

How Argc works

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

  1. Describe the options, parameters, and subcommands in comments
  2. Call the following command to entrust Argc to process command line parameters for us
eval "$(argc -e $0 "$@")"

Argc will do the following for us:

  1. Extract parameter definitions from 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
  5. If there is a subcommand, call the subcommand function

We can easily access the corresponding option or parameter through the variable $argc_ .

Try examples/demo.sh your self.

Install

With cargo

cargo install argc

Binaries on macOS, Linux, Windows

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

Tag

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

@describe

@describe [string]

# @describe A demo cli

Define description

@version

@version [string]

# @version 2.17.1 

Define version

@author

@author [string]

# @author nobody 
   

Define author

@cmd

@cmd [string]

# @cmd Upload a file
upload() {
}

# @cmd Download a file
download() {
}

Define subcommand

@alias

@alias name(,name)+

# @cmd
# @alias t,tst
test() {
}

Define alias for a subcommand

@option

 @option [short] [long][modifer] [notation] [string]

 ## @option    --foo                A option
 ## @option -f --foo                A option with short alias
 ## @option    --foo 
   
             A option with notation
   
 ## @option    --foo!               A required option
 ## @option    --foo*               A option with multiple values
 ## @option    --foo+               A required option with multiple values
 ## @option    --foo=a              A option with default value
 ## @option    --foo[a|b]           A option with choices
 ## @option    --foo[=a|b]          A option with choices and default value
 ## @option    --foo![a|b]          A required option with choices
 ## @option -f --foo 
   
             A option with short alias and notation
   

Define value option

modifier

The symbol after the long option name is the modifier

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

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 , , ,

@flag

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

# @flag     --foo       A flag
# @flag  -f --foo       A flag with short alias

Define flag option

@arg

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

# @arg value            A positional argument
# @arg value!           A required positional argument
# @arg value*           A positional argument support multiple values
# @arg value+           A required positional argument support multiple values
# @arg value=a          A positional argument with default value
# @arg value[a|b]       A positional argument with choices
# @arg value[=a|b]      A positional argument with choices and default value
# @arg value![a|b]      A required positional argument with choices

Define positional argument

arg's modifier is same to option's modifier

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.

Comments
  • Output escaping is broken

    Output escaping is broken

    At least variable values are not propperly escaped. e.g. running the demo.sh like this:

    export foo="this is broken" ; ./demo.sh download -t '$foo' bar

    should result in

    cmd:                      download
    flag:   --force           
    option: --tries           $foo
    arg:    source            bar
    arg:    target            
    

    but results in

    cmd:                      download
    flag:   --force           
    option: --tries           this is broken
    arg:    source            bar
    arg:    target 
    

    this is since calling argc -e demo.sh download -t '$foo' bar results in

    argc_tries="$foo"
    argc_source="bar"
    download
    ``` riight there is an unescaped `$foo`
    
    bug 
    opened by schorsch3000 8
  • [FR] Colored help

    [FR] Colored help

    Can we have colored helped, please? I haven't seen anything about color in README or issues.

    clap's default color choice is auto, i.e. when terminal supports it:

    https://docs.rs/clap/3.2.17/clap/enum.ColorChoice.html#variant.Auto

    opened by murlakatamenka 3
  • [gdb under argc] ctrl-c leads to terminate, not interrupt

    [gdb under argc] ctrl-c leads to terminate, not interrupt

    In gdb the default behavior of ctrl-c is to interrupt the process. For example:

      (gdb) c
      Continuing.
      ^C
      Thread 1 "main" received signal SIGINT, Interrupt.
      0x00002aaab428480d in nanosleep () from /lib64/libc.so.6
      (gdb)
    

    But if run gdb from argc, ctrl-c would terminate the gdb debug process.

    # @cmd debug
    debug () {
      gdb -p `pgrep main` \
         -ex 'c'
      #exec gdb -p `pgrep main` \
      #   -ex 'c'
    }
    
    argc debug
     # in gdb 
     # ctrl-c would terminate the debug process.
    

    Its exit code is 130 and the output is like:

      ^C
      
      Thread 1 "main" received signal SIGINT, Interrupt.
      [Switching to Thread 0x2aaaaab30640 (LWP 177491)]
      0x00002aaab5bfa80d in nanosleep () from /lib64/libc.so.6
      (130)
    

    Is there any solution or workaround to not terminate the gdb?

    opened by jminh 1
  • build(deps): bump clap from 3.2.7 to 3.2.8

    build(deps): bump clap from 3.2.7 to 3.2.8

    Bumps clap from 3.2.7 to 3.2.8.

    Release notes

    Sourced from clap's releases.

    v3.2.8

    [3.2.8] - 2022-06-30

    Features

    • Added Command::mut_subcommand to mirror Command::mut_arg
    Changelog

    Sourced from clap's changelog.

    [3.2.8] - 2022-06-30

    Features

    • Added Command::mut_subcommand to mirror Command::mut_arg
    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    opened by dependabot[bot] 1
  • feat: infer subcommand and args

    feat: infer subcommand and args

    For example, to match a subcommand named test, one could use t, te, tes, and test.

    NOTE: The match must not be ambiguous at all in order to succeed. i.e. to match te to test there could not also be a subcommand or alias temp because both start with te

    opened by sigoden 0
  • Add command to generate boilerplate argcfile.sh

    Add command to generate boilerplate argcfile.sh

    Use argc --argc-create <cmd...> to generate boilerplate file

    For example, run argc --argc-create build test run will create argcfile.sh in current directory with following content

    #!/usr/bin/env bash
    
    set -e
    
    # @cmd
    build() {
        echo "build to be implemented"
    }
    
    # @cmd
    test() {
        echo "test to be implemented"
    }
    
    # @cmd
    run() {
        echo "run to be implemented"
    }
    
    eval $(argc --argc-eval "$0" "$@")
    
    enhancement 
    opened by sigoden 0
  • feat: works as command runner

    feat: works as command runner

    argc will works as command runner.

    You create build script named argcfile

    #!/bin/bash 
    set -eo pipefail
    
    # @cmd Test all crates and modules
    # @alias t,test
    tst() {
        cargo test --all
    }
    
    # @cmd Format/clippy code
    fmt() {
        cargo clippy --all --all-targets
        cargo fmt --all
    }
    
    eval "$(argc --argc-eval $0 "$@")"
    

    run argc equals to bash argcfile, argc will search for argcfile then execute it. like make/makefile.

    argcfile 
    
    USAGE:
        argcfile <SUBCOMMAND>
    
    OPTIONS:
        -h, --help    Print help information
    
    SUBCOMMANDS:
        fmt     Format/clippy code
        help    Print this message or the help of the given subcommand(s)
        tst     Test all crates and modules [aliases: t, test]
    
    opened by sigoden 0
Releases(v0.12.0)
Owner
null
locdev is a handy CLI tool that simplifies the process of adding, removing, and listing entries in the hosts file.

locdev ??️ locdev is a handy CLI tool that simplifies the process of adding, removing, and listing entries in the hosts file. You no longer need to de

Nick Rempel 20 Jun 5, 2023
Bashly - Bash CLI Framework and Generator

Bashly - Bash CLI Framework and Generator Create feature-rich bash scripts using simple YAML configuration

Danny Ben Shitrit 1.4k Jan 4, 2023
GPT-3 powered CLI tool to help you remember bash commands.

Rusty: GPT-3 Powered CLI Tool Convert natural language into executable commands directly from the terminal! Open source CLI tool powered by OpenAI (br

Zahid Khawaja 287 Apr 19, 2023
Simple joke randomizer from bash.org.pl made as CLI Tool in Rust.

RBashOrg Simple joke randomizer from bash.org.pl made as CLI Tool in Rust. Description Main motivation of this project was to learn basic concepts abo

Krzysztof Szostak 3 Feb 20, 2024
Poisson intensity of limit order execution, calibration of parameters A and k using level 1 tick data

Poisson intensity of limit order execution, calibration of parameters A and k using level 1 tick data Description A limit order placed at a price St ±

0xCuteSocks 6 Apr 9, 2023
Use raw-window-handle 0.5 with crates that depend on 0.4.

OldHasRawWindowHandleWrapper Wrap any type that implements HasRawWindowHandle and HasRawDisplayHandle from raw-window-handle 0.5 in OldHasRawWindowHan

null 1 Nov 25, 2022
A lightweight and ergonomic rust crate to handle system-wide hotkeys on windows

Windows Hotkeys An opinionated, lightweight crate to handle system-wide hotkeys on windows The windows-hotkeys crate abstracts and handles all interac

null 5 Dec 15, 2022
Nvm - Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Node Version Manager Table of Contents Intro About Installing and Updating Install & Update Script Additional Notes Troubleshooting on Linux Troublesh

nvm.sh 63.8k Jan 7, 2023
Use Git installed in Bash on Windows/Windows Subsystem for Linux (WSL) from Windows and Visual Studio Code (VSCode)

WSLGit This project provides a small executable that forwards all arguments to git running inside Bash on Windows/Windows Subsystem for Linux (WSL). T

A. R. S. 1.1k Jan 3, 2023
An enhanced history(1) for bash

history This is a replacement for the history builtin in bash. It has a couple of additional features that relative to the one included with bash: Con

Robert T. McGibbon 4 Aug 25, 2022
Check if the process is running inside Windows Subsystem for Linux (Bash on Windows)

is-wsl Check if the process is running inside Windows Subsystem for Linux (Bash on Windows) Inspired by sindresorhus/is-wsl and made for Rust lang. Ca

Sean Larkin 6 Jan 31, 2023
A `nix` and `nix-shell` wrapper for shells other than `bash`

nix-your-shell A nix and nix-shell wrapper for shells other than bash. nix develop and nix-shell use bash as the default shell, so nix-your-shell prin

Mercury 15 Apr 10, 2023
Voila is a domain-specific language launched through CLI tool for operating with files and directories in massive amounts in a fast & reliable way.

Voila is a domain-specific language designed for doing complex operations to folders & files. It is based on a CLI tool, although you can write your V

Guillem Jara 86 Dec 12, 2022
The dead easy way to use config files in your rust project

Configr The dead easy way to use config files in your project This will load a config.toml file if it exists, otherwise it will create the needed fold

Carsten Kragelund Jørgensen 4 Jul 1, 2022
⚡️ A blazing fast way of maintaining powerful notes with connections between them.

Zettl ⚡️ A blazing fast way of maintaining powerful notes with connections between them. Installing Zettl To install Zettl, you will need the Rust too

Tirth Jain 26 Dec 2, 2022
Irx-config - The library provides convenient way to represent/parse configuration from different sources

The irx-config library provides convenient way to represent/parse configuration from different sources. The main goals is to be very easy to use and t

Andriy Bakay 2 Sep 14, 2022
Oxygen is a voice journal and audio analysis toolkit for people who want to change the way their voice comes across.

Oxygen Voice Journal Oxygen is a voice journal and audio analysis toolkit for people who want to change the way their voice comes across. Or rather, i

Jocelyn Stericker 32 Oct 20, 2022
The-way - A code snippets manager for your terminal.

The Way A code snippets manager for your terminal. Record and retrieve snippets you use every day, or once in a blue moon, without having to spin up a

OutOfCheeseError 254 Jan 7, 2023
Terminal UI for erhanbaris/smartcalc, a new way to do calculations on-the-fly

smartcalc-tui Terminal UI for erhanbaris/smartcalc, a new way to do calculations on-the-fly. From the README: Do your calculation on text based querie

Aaron Ross 12 Sep 14, 2022