bash-args: functions to handle bash arguments

- flags
- options
- positional arguments
- variadic arguments

Author: mihai-stancu

.deps/help

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Copyright (c) 2025 Mihai Stancu (https://github.com/curatorium)
+
+source /usr/local/bin/import;
+
+DOCFILE="$(dirname ${BASH_SOURCE[0]})/../args";
+export DOCFILE;
+
+T=$'\t'
+
+cat <<-TXT
+	NAME
+		${T}args -- Argument parsing functions for bash scripts.
+
+	USAGE
+		${T}source /usr/local/bin/args
+
+	FUNCTIONS
+TXT
+
+for name in $(docs:list function); do
+	cat <<-TXT | awk 'NF{print; blank=0} !NF && !blank++{print ""}'
+		args:$name -- $(docs:tag "$name" desc)
+
+		$(docs:tag -i 1 "$name" usage)
+
+		$(docs:tag -i 1 "$name" flag,opt,arg)
+
+	TXT
+done | sed 's/^/\t/'

.deps/readme

@@ -0,0 +1,184 @@
+#!/bin/bash
+# Copyright (c) 2025 Mihai Stancu (https://github.com/curatorium)
+
+source /usr/local/bin/import;
+
+DOCFILE="$(dirname ${BASH_SOURCE[0]})/../args"
+
+BEGIN_CODE='```bash'
+END_CODE='```'
+
+# Generate README.md
+cat <<-MD
+	# bash-args
+
+	> Argument parsing for bash scripts.
+
+	## Installation
+
+	$BEGIN_CODE
+	curl -1fsSLR https://raw.githubusercontent.com/curatorium/bash-args/main/args -o .deps/args
+	$END_CODE
+
+	## Usage
+
+	$BEGIN_CODE
+	source ./args
+
+	# Initialize the ARGS array with script arguments
+	ARGS=("\$@")
+
+	# Parse flags, options, and positional arguments
+	args:flag verbose v # variable \$verbose will be set to true if flag present
+	args:opt name n     # variable \$name will be set to the value provided
+	args:arg file       # variable \$file will be set to $1 if present
+	args:varg files     # variable \$files will be set to the rest of values from \$ARGS
+	$END_CODE
+
+	All functions operate on the \`ARGS\` array, consuming matched tokens and leaving unmatched ones for subsequent parsing.
+
+	Ideally inside functions you will be using \`local\` variables to avoid polluting the global scope.
+
+	## FUNCTIONS
+MD
+
+for name in $(docs:list function); do
+	cat <<-MD
+
+		### \`args:$name\`
+
+		$(docs:tag "$name" desc)
+
+	MD
+
+	if [[ -n "$(docs:tag "$name" usage)" ]]; then
+		cat <<-MD
+			$BEGIN_CODE
+			$(docs:tag "$name" usage)
+			$END_CODE
+
+		MD
+	fi
+
+	if [[ -n "$(docs:tag -f md "$name" flag)" ]]; then
+		cat <<-MD
+			| Flag | Description |
+			|------|-------------|
+			$(docs:tag -f md "$name" flag)
+
+		MD
+	fi
+
+	if [[ -n "$(docs:tag -f md "$name" arg)" ]]; then
+		cat <<-MD
+			| Argument | Description |
+			|----------|-------------|
+			$(docs:tag -f md "$name" arg)
+
+		MD
+	fi
+
+	if [[ -n "$(docs:tag -f md "$name" opt)" ]]; then
+		cat <<-MD
+			| Option | Description |
+			|--------|-------------|
+			$(docs:tag -f md "$name" opt)
+
+		MD
+	fi
+
+	if [[ -n "$(docs:tag -f md "$name" return)" ]]; then
+		cat <<-MD
+			| Return | Description |
+			|--------|-------------|
+			$(docs:tag -f md "$name" return)
+
+		MD
+	fi
+done
+
+cat <<-MD
+
+	## Pattern Matching
+
+	Options and arguments support RegEx patterns for validation:
+
+	$BEGIN_CODE
+	# Numeric validation
+	args:opt port p '^\[0-9\]+\$'
+
+	# URL validation
+	args:arg url '^https?://'
+
+	# Capture groups extract specific parts
+	args:opt ord o '^:(\[0-9\]{3})\$'    # --ord :100 -> ord=100
+	$END_CODE
+
+	When a pattern contains a capture group, the captured value is assigned to the variable instead of the full match.
+
+	## Examples
+
+	### Basic CLI Tool
+
+	$BEGIN_CODE
+	#!/bin/bash
+	source /usr/local/bin/args
+
+	ARGS=("\$@")
+
+	args:flag verbose v
+	args:flag -r help h --err "Missing required --help flag"
+	args:opt output o
+	args:arg input
+	args:varg -o extra
+
+	echo "verbose: \$verbose"
+	echo "output: \$output"
+	echo "input: \$input"
+	echo "extra: \${extra[*]}"
+	$END_CODE
+
+	### Git-like Subcommands
+
+	$BEGIN_CODE
+	#!/bin/bash
+	source /usr/local/bin/args
+
+	ARGS=("\$@")
+
+	args:flag verbose v
+	args:arg command '^(clone|pull|push)\$' --err "Unknown command"
+	args:varg -o cmd_args
+
+	case "\$command" in
+	    clone) git_clone "\${cmd_args[@]}" ;;
+	    pull)  git_pull "\${cmd_args[@]}" ;;
+	    push)  git_push "\${cmd_args[@]}" ;;
+	esac
+	$END_CODE
+
+	### With Validation
+
+	$BEGIN_CODE
+	#!/bin/bash
+	source /usr/local/bin/args
+
+	ARGS=("\$@")
+
+	args:opt port p '^\[0-9\]+\$' --err "Port must be numeric" || exit 1
+	args:opt host h '^\[a-z0-9.-\]+\$' --err "Invalid hostname" || exit 1
+	args:arg url '^https?://' --err "URL must start with http(s)://" || exit 1
+
+	echo "Connecting to \$url via \$host:\$port"
+	$END_CODE
+
+	## Limitations
+
+	- **No \`--\` separator handling.** There is no built-in support for \`--\` to signal end-of-options. Arguments after \`--\` are not treated differently.
+	- **No attached quoting.** Values with spaces must be passed as separate shell words (e.g., \`--name "foo bar"\`). Attached forms like \`--name="foo bar"\` may not preserve quoting as expected.
+	- **\`--combined\` flag ordering.** Combined short flags (\`-vfs\`) must be parsed after all other \`args:flag\` and \`args:opt\` calls, but before \`args:arg\` calls. Otherwise, combined flags may consume characters intended as option values, or positional arguments starting with \`-\` may be misinterpreted.
+
+	## License
+
+	MIT
+MD

.githooks/pre-commit

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Copyright (c) 2025 Mihai Stancu (https://github.com/curatorium)
+
+set -Eeuo pipefail;
+shopt -s inherit_errexit;
+shopt -s nullglob;
+
+REPO="$(git rev-parse --show-toplevel)"
+
+shellcheck -x "$REPO/args" ||
+	(echo "ERROR: args failed shellcheck." && exit 1);
+
+"$REPO/args.test" > "$REPO/args.test.md" ||
+	(echo "ERROR: args tests failed." && exit 1);
+
+[[ "$("$REPO/.deps/readme")" == "$(cat "$REPO/README.md")" ]] ||
+	(echo "Docs are out of date." && exit 1);
+
+[[ "$("$REPO/args.test")" == "$(cat "$REPO/args.test.md")" ]] ||
+	(echo "Test reports are out of date.." && exit 1);

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push: {tags: ['v*']}
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install import
+        run: |
+          curl -1fsSLR https://github.com/curatorium/bash-import/releases/latest/download/import -o /usr/local/bin/import;
+          chmod +x /usr/local/bin/import;
+
+      - name: Run checks (shellcheck + tests)
+        run: .githooks/pre-commit
+
+      - name: Build release artifacts
+        run: import pack -f args -o .dist/args
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "${{ github.ref_name }}" --title "${{ github.ref_name }}" --generate-notes --latest .dist/args

.gitignore

@@ -0,0 +1,5 @@
+.idea/
+.deps/github/
+.deps/http/
+.deps/https/
+.dist/

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Mihai Stancu (https://github.com/curatorium)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.