refactor: update examples and add readme

docs/command-runner.md

@@ -2,7 +2,7 @@
 
 Argc is a also command runner built for those who love the efficiency and flexibility of Bash scripting.
 
-This document explains how to effectively use `argc` as a command runner.
+This guide provides instructions on how to effectively use `argc` for this purpose.
 
 ## Create an Argcfile.sh 
 

examples/README.md

@@ -0,0 +1,20 @@
+# Argc Examples
+
+Each of these examples demonstrates one aspect or feature of argc.
+
+- [demo.sh](./demo.sh) - A simple demo script.
+- [multiline.sh](./multiline.sh) - how to use multiline help text.
+- [nested-commands](./nested-commands.sh) - how to use nested commands.
+- [hooks.sh](./hooks.sh) - how to use argc hooks.
+- [parallel.sh](./parallel.sh) - how to use `--argc-parallel`.
+
+- [args.sh](./args.sh) - all kinds of `@arg`.
+- [options.sh](./options.sh) - all kinds of `@option` and `@flag`.
+- [bind-env](./bind-envs.sh) - how to bind env to param.
+- [envs.sh](./envs.sh) - all kind of `@env`.
+
+- [default-subcommand](./default-subcommand.sh) - how to use `@meta default-subcommand`.
+- [require-tools](./require-tools.sh) - how to use `@meta require-tools`.
+- [inherit-flag-options](./inherit-flag-options.sh) - how to use `@meta inherit-flag-options`.
+- [combine-short](./combine-shorts.sh) - how to use `@meta combine-shorts`.
+- [symbol](./symbol.sh): how to use `@meta symbol`.

examples/bind-envs.sh

@@ -1,4 +1,4 @@
-# @cmd Demonstrates how to bind environment variables to parameters
+# @cmd How to bind env to param
 
 # @flag --fa1 $$
 # @flag --fa2 $$

examples/combine-shorts.sh

@@ -0,0 +1,19 @@
+# @describe How to use `@meta combine-shorts`
+#
+# Mock rm cli
+# Examples:
+#   prog -rf dir1 dir2
+# 
+# @meta combine-shorts
+# @flag -r --recursive remove directories and their contents recursively
+# @flag -f --force ignore nonexistent files and arguments, never prompt
+# @arg path* the path to remove
+
+eval "$(argc --argc-eval "$0" "$@")"
+
+_debug() {
+    ( set -o posix ; set ) | grep ^argc_
+    echo "$argc__fn" "$@"
+}
+
+_debug

examples/command-default.sh → examples/default-subcommand.sh

@@ -1,4 +1,4 @@
-# describe Sample CLI that uses the default command option
+# describe How to use `@meta default-subcommand`
 
 # @cmd Upload a file
 # @meta default-subcommand

examples/hooks.sh

@@ -1,11 +1,12 @@
 #/usr/bin/env node
+set -e
 
+# @describe How to use argc hooks
+#
 # Argc supports two hooks:
 #   _argc_before: call before running the command function (after initialized variables)
 #   _argc_after: call after running the command function
 
-set -e
-
 _argc_before() {
   echo before
 }

examples/inherit-flag-options.sh

@@ -0,0 +1,26 @@
+# @describe How to use `@meta inherit-flag-options`
+#
+# Mock systemctl cli
+# Examples:
+#   prog --user start my-service
+#   prog --user stop my-service
+# 
+# @meta inherit-flag-options
+# @flag --user Connect to user service manager
+# @flag --no-pager Do not pipe output into a pager
+# @option -t --type List units of a particular type
+# @option --state List units with particular LOAD or SUB or ACTIVE state
+
+# @cmd Start (activate) one or more units
+# @arg UNIT... The unit files to start
+start() {
+    :;
+}
+
+# @cmd Stop (deactivate) one or more units
+# @arg UNIT... The unit files to stop
+stop() {
+    :;
+}
+
+eval "$(argc --argc-eval "$0" "$@")"

examples/details.sh → examples/multiline.sh

@@ -1,8 +1,10 @@
-# @describe Multi-line auto-wrapped help text
+# @describe How to use multiline help text
 #
-# Extra lines after the @cmd or @describe, which don't start with an @, are 
-# treated as the long description. A line which is not a comment ends
-# the block.
+# Extra lines after the comment tag accepts description, which don't start with an `@`,
+# are treated as the long description. A line which is not a comment ends the block.
+
+# @meta version 1.0.0
+# @meta author  nobody <[email protected]>
 
 # @option --foo[=default|full|auto] Sunshine gleams over hills afar, bringing warmth and hope to every soul, yet challenges await as we journey forth, striving for dreams and joy in abundance. Peaceful rivers whisper secrets gently heard.
 #  * default: enables recommended style components.
@@ -13,9 +15,8 @@
 # Use '-' for standard input.
 # @cmd Eager dogs jump quickly over lazy foxes, creating wonderful chaos amid peaceful fields, but few noticed their swift escape beyond tall fences. Swift breezes sway gently through green.
 #
-# Extra lines after the @cmd or @describe, which don't start with an @, are 
-# treated as the long description. A line which is not a comment ends
-# the block.
+# Extra lines after the comment tag accepts description, which don't start with an `@`,
+# are treated as the long description. A line which is not a comment ends the block.
 cmd() { :; }
 
 eval "$(TERM_WIDTH=`tput cols` argc --argc-eval "$0" "$@")"

examples/command-nested.sh → examples/nested-commands.sh

@@ -1,4 +1,6 @@
-# @describe Docker CLI mocking
+# @describe How to use nested subcommands
+# 
+# Mock docker cli
 
 # @cmd
 builder() { :; }

examples/parallel.sh

@@ -1,7 +1,8 @@
 #/usr/bin/env bash
 set -e
 
-# @describe Demonstrates how to use argc-parallel
+# @describe How to use `--argc-parallel`
+#
 # Compared with GNU parallel, the biggest advantage of argc-parallel is that it preserves `argc_*` variables.
 
 # @cmd

examples/require-tools.sh

@@ -1,16 +1,16 @@
-# @describe Demonstrate how to use require-tools meta
+# @describe how to use `@meta require-tools`
 
-# @meta require-tools curl,sed
+# @meta require-tools awk,sed
 
 # @cmd
 # @meta require-tools git
-cmd1() {
+require-git() {
     :;
 }
 
 # @cmd
 # @meta require-tools not-found
-cmd2() {
+require-not-found() {
     :;
 }
 

examples/symbol.sh

@@ -0,0 +1,26 @@
+# @describe How to use `@meta symbol`
+#
+# Mock cargo cli
+# @meta symbol +toolchain[`_choice_toolchain`]
+
+# @cmd Compile the current package
+# @alias b 
+build () {
+    :;
+}
+
+# @cmd Analyze the current package and report errors, but don't build object files
+# @alias c
+check() {
+    :;
+}
+
+_choice_toolchain() {
+    cat <<-'EOF'
+stable
+beta
+nightly
+EOF
+}
+
+eval "$(argc --argc-eval "$0" "$@")"

tests/multiline.rs

@@ -0,0 +1,16 @@
+use super::SCRIPT_MULTILINE;
+
+#[test]
+fn wrap() {
+    snapshot!(SCRIPT_MULTILINE, &["prog", "-h"], None, Some(80));
+}
+
+#[test]
+fn wrap2() {
+    snapshot!(SCRIPT_MULTILINE, &["prog", "foo", "-h"], None, Some(80));
+}
+
+#[test]
+fn nowrap() {
+    snapshot!(SCRIPT_MULTILINE, &["prog", "-h"], None, None);
+}

tests/snapshots/integration__bind_env__bind_env_flags_help.snap

@@ -3,7 +3,7 @@ source: tests/bind_env.rs
 expression: "format!(r#\"\n# OUTPUT\n{output}\n\n# BUILD_OUTPUT\n{build_output}\n\"#)"
 ---
 # OUTPUT
-Demonstrates how to bind environment variables to parameters
+How to bind env to param
 
 USAGE: bind-envs flags [OPTIONS]
 
@@ -18,7 +18,7 @@ OPTIONS:
 
 
 # BUILD_OUTPUT
-Demonstrates how to bind environment variables to parameters
+How to bind env to param
 
 USAGE: prog flags [OPTIONS]
 

tests/snapshots/integration__details__nowrap.snap → tests/snapshots/integration__multiline__nowrap.snap

@@ -1,17 +1,18 @@
 ---
-source: tests/details.rs
+source: tests/multiline.rs
 expression: data
 ---
 RUN
 prog -h
 
 # OUTPUT
 command cat >&2 <<-'EOF' 
-Multi-line auto-wrapped help text
+prog 1.0.0
+nobody <nobody@example.com>
+How to use multiline help text
 
-Extra lines after the @cmd or @describe, which don't start with an @, are
-treated as the long description. A line which is not a comment ends
-the block.
+Extra lines after the comment tag accepts description, which don't start with an `@`,
+are treated as the long description. A line which is not a comment ends the block.
 
 USAGE: prog [OPTIONS] <COMMAND>
 
@@ -45,11 +46,12 @@ EOF
 exit 0
 
 # BUILD_OUTPUT
-Multi-line auto-wrapped help text
+prog 1.0.0
+nobody <[email protected]>
+How to use multiline help text
 
-Extra lines after the @cmd or @describe, which don't start with an @, are
-treated as the long description. A line which is not a comment ends
-the block.
+Extra lines after the comment tag accepts description, which don't start with an `@`,
+are treated as the long description. A line which is not a comment ends the block.
 
 USAGE: prog [OPTIONS] <COMMAND>
 
@@ -78,5 +80,3 @@ OPTIONS:
 
 COMMANDS:
   cmd  Eager dogs jump quickly over lazy foxes, creating wonderful chaos amid peaceful fields, but few noticed their swift escape beyond tall fences. Swift breezes sway gently through green.
-
-

tests/snapshots/integration__details__wrap.snap → tests/snapshots/integration__multiline__wrap.snap

@@ -1,17 +1,20 @@
 ---
-source: tests/details.rs
+source: tests/multiline.rs
 expression: data
 ---
 RUN
 prog -h
 
 # OUTPUT
 command cat >&2 <<-'EOF' 
-Multi-line auto-wrapped help text
+prog 1.0.0
+nobody <nobody@example.com>
+How to use multiline help text
 
-Extra lines after the @cmd or @describe, which don't start with an @, are
-treated as the long description. A line which is not a comment ends
-the block.
+Extra lines after the comment tag accepts description, which don't start with
+an `@`,
+are treated as the long description. A line which is not a comment ends the
+block.
 
 USAGE: prog [OPTIONS] <COMMAND>
 
@@ -53,11 +56,12 @@ EOF
 exit 0
 
 # BUILD_OUTPUT
-Multi-line auto-wrapped help text
+prog 1.0.0
+nobody <[email protected]>
+How to use multiline help text
 
-Extra lines after the @cmd or @describe, which don't start with an @, are
-treated as the long description. A line which is not a comment ends
-the block.
+Extra lines after the comment tag accepts description, which don't start with an `@`,
+are treated as the long description. A line which is not a comment ends the block.
 
 USAGE: prog [OPTIONS] <COMMAND>
 
@@ -86,5 +90,3 @@ OPTIONS:
 
 COMMANDS:
   cmd  Eager dogs jump quickly over lazy foxes, creating wonderful chaos amid peaceful fields, but few noticed their swift escape beyond tall fences. Swift breezes sway gently through green.
-
-

tests/snapshots/integration__details__wrap2.snap → tests/snapshots/integration__multiline__wrap2.snap

@@ -1,17 +1,20 @@
 ---
-source: tests/details.rs
+source: tests/multiline.rs
 expression: data
 ---
 RUN
 prog foo -h
 
 # OUTPUT
 command cat >&2 <<-'EOF' 
-Multi-line auto-wrapped help text
+prog 1.0.0
+nobody <nobody@example.com>
+How to use multiline help text
 
-Extra lines after the @cmd or @describe, which don't start with an @, are
-treated as the long description. A line which is not a comment ends
-the block.
+Extra lines after the comment tag accepts description, which don't start with
+an `@`,
+are treated as the long description. A line which is not a comment ends the
+block.
 
 USAGE: prog [OPTIONS] <COMMAND>
 
@@ -53,11 +56,12 @@ EOF
 exit 0
 
 # BUILD_OUTPUT
-Multi-line auto-wrapped help text
+prog 1.0.0
+nobody <[email protected]>
+How to use multiline help text
 
-Extra lines after the @cmd or @describe, which don't start with an @, are
-treated as the long description. A line which is not a comment ends
-the block.
+Extra lines after the comment tag accepts description, which don't start with an `@`,
+are treated as the long description. A line which is not a comment ends the block.
 
 USAGE: prog [OPTIONS] <COMMAND>
 
@@ -86,5 +90,3 @@ OPTIONS:
 
 COMMANDS:
   cmd  Eager dogs jump quickly over lazy foxes, creating wonderful chaos amid peaceful fields, but few noticed their swift escape beyond tall fences. Swift breezes sway gently through green.
-
-