argc

You can group related recipes together for better organization and readability in the help output. Use a colon, dot, or at-sign to define group boundaries. Valid formats include foo:bar, foo.bar, and foo@bar.

# @cmd
test() { :; }
# @cmd
test-unit() { :; }
# @cmd
test-bin() { :; }

When writing completion logic, it is important to understand the difference between how the last word is captured:

• ARGC_CWORD: Isolates the final word, regardless of preceding flags.
  • Example: In git --git-dir=git, ARGC_CWORD is git.
• ARGC_LAST_ARG: Captures the entire last argument, including attached flags/options.
  • Example: In git --git-dir=git, ARGC_LAST_ARG is --git-dir=git.

When an external subcommand is dispatched, argc exports the ARGC_PARENT_ARGS environment variable. This variable contains the parent command and its flags (the arguments provided before the subcommand name).

This is useful for preserving global options when the external script needs to re-invoke the parent command. You can implement this by defining a helper function that evaluates the exported variable.

# Inside an external subcommand script

_parent_cmd() {
  eval "$ARGC_PARENT_ARGS" "$@"
}

# Usage: calls the parent command with the original global flags preserved
_parent_cmd log --oneline

When you define parameters using Argc directives, they are mapped to shell variables as follows:

• @option --name: Becomes $argc_name.
• @option --name* (Multi-occurs): Becomes an array ${argc_name[@]}.
• @flag --name: Becomes $argc_name (typically 1 if present, 0 or empty if not).
• @arg name: Becomes $argc_name.
• @arg name*: Becomes an array ${argc_name[@]}.

# Example mapping
# @option --oa
# @option --ob*
# @flag   --fa
# @arg va
# @arg vb*

# Running: ./script.sh --oa a --ob=b1 --ob=b2 --fa foo bar baz
# Results:
# $argc_oa     -> a
# ${argc_ob[@]} -> b1 b2
# $argc_fa     -> 1
# $argc_va     -> foo
# ${argc_vb[@]} -> bar baz

Argc includes Argcscript, a Bash-based command runner similar to make. It uses an Argcfile.sh to define "recipes" (commands).

Key benefits include:

• Leveraging existing Bash skills and GNU tools (awk, sed, grep, etc.).
• Effortless environment variable management (loading, documenting, and validating .env files).
• Built-in shell autocompletion for recipes.
• Cross-platform compatibility.

To make a shell function available as a command in Argc, place the # @cmd tag immediately above the function definition. This allows the function to be invoked via argc <function_name>.

# @cmd
build() {
    echo TODO build
}

Argc automatically cds into the directory containing the Argcfile.sh found in the parent hierarchy. This ensures recipes run relative to the project root.

When running a command from a subdirectory:

• $PWD: Points to the project root (where Argcfile.sh resides).
• $ARGC_PWD: Points to the actual current working directory from which you invoked the command.

# @cmd
build() {
    echo $PWD      # Project root
    echo $ARGC_PWD # Current directory
}

Since recipes are shell functions, you can manage dependencies by calling one recipe from within another. This allows for sequential execution of setup or teardown tasks.

# @cmd
current() {
  before
  echo current
  after
}

# @cmd
before() {
  echo before
}

# @cmd
after() {
  echo after
}

By default, running argc without arguments displays a list of available recipes. You can override this behavior to run a specific recipe automatically using one of two methods:

1. Define a main() function in your Argcfile.sh.
2. Use the # @meta default-subcommand tag above a recipe.

# Method 1: Using main()
# @cmd
build() { :; }

main() {
  build
}

# Method 2: Using @meta
# @meta default-subcommand
# @cmd
build() { :; }

Argc automatically creates shell variables for every @option, @flag, and @arg directive defined in your script. To populate these variables, you must initialize them by evaluating the output of the argc --argc-eval command with your script name and the passed arguments.

Variables follow the naming convention argc_<name>, where <name> is the name of the option, flag, or argument (stripping leading dashes).

# @option --oa
# @option --ob*
# @flag   --fa
# @arg va
# @arg vb*

eval "$(argc --argc-eval "$0" "$@")"  # Initializes Argc variables

echo '--oa:' $argc_oa
echo '--ob:' ${argc_ob[@]}  # Accessing multiple values as an array
echo '--fa:' $argc_fa
echo '  va:' $argc_va
echo '  vb:' ${argc_vb[@]}

Argc uses a file named Argcfile.sh to store commands, which are referred to as recipes. A recipe is a standard shell function preceded by a # @cmd comment tag. You can quickly scaffold a new Argcfile.sh with sample recipes using the --argc-create flag.

argc --argc-create build test