parsearger-core

Critical Decision Tree

Before running any command, decide:

1. Does the target file exist?

   • YES → Use parse (modify EXISTING parseArger script)
   • NO → Use generate (create NEW script)

2. Check parseArger availability:

   • Run parseArger if in PATH
   • Otherwise use ./parseArger (from project root)

Invocation Rules

1. Check which parseArger → if found, use parseArger
2. Fallback: ./parseArger (in project root)
3. Never assume location - always check first

CRITICAL: Generated Code Sections

All parseArger scripts contain generated code between:

• # @parseArger-parsing
• # @parseArger-parsing-end

DO NOT manually edit code between these markers.

To modify argument parsing:

1. Edit the # @parseArger declarations at the top of the file
2. Run parseArger parse FILE --inplace to regenerate the parsing logic

The generated parsing code is regenerated every time you use parseArger parse.

---

1. Generate a NEW Parser (generate)

Use when creating a NEW script that doesn't exist yet.

CRITICAL: Always Use --output

parseArger generate --output /path/to/script.sh [OPTIONS]

Without --output, output goes to stdout only.

Core Definitions

Define arguments using specific flags. The value is a quoted string containing the name, description, and specific settings.

Positional Arguments (--pos) Syntax: --pos 'NAME "DESCRIPTION" [SETTINGS]'

Settings:

• --optional: Make the argument optional.
• --repeat: Allow multiple values (creates an array _arg_name).
• --repeat-min N: Min repetitions (implies --repeat).
• --repeat-max N: Max repetitions.
• --one-of "VAL": Restrict to specific values (repeatable).
• --complete "FUNC": Bash built-in completion (e.g., file, directory).
• --complete-custom "CMD": Custom dynamic completion command.
• --match "REGEX": Validate input against a regex pattern (e.g. ^[0-9]+$).
• --subcommand: Mark as a subcommand (see Subcommands below).

**Options (--opt)Syntax:--opt 'NAME "DESCRIPTION" [SETTINGS]'`

Settings:

• --short "C": Short flag character (e.g., o).
• --default-value "VAL": Default value if not provided.
• --repeat: Allow multiple occurrences.
• --alias "NAME": Alternative long name.
• --empty: Allow usage without value (acts like flag).
• --empty-value "VAL": Value to set if used without value (requires --empty).
• --env "VAR": Fallback to environment variable if option not provided.
• --required: Mark option as mandatory (script fails if missing).
• --match "REGEX": Validate input against a regex pattern (e.g. ^[0-9]+$).

Flags (--flag) Syntax: --flag 'NAME "DESCRIPTION" [SETTINGS]'

Settings:

• --short "C": Short flag character (e.g., f).
• --on: Flag is on by default (passing it turns it off).
• --alias "NAME": Alias.
• --no-name "NAME": Custom name for negation (e.g., --dont-do-it).

Nested Options (--nested) Syntax: --nested 'NAME "DESCRIPTION" [SETTINGS]' Creates an associative array for namespaced options (e.g., --config-db value). Settings:

• --one-of "KEY": Restrict accepted keys.
• --complete "FUNC", --complete-custom "CMD".

Global Settings

• --help-message "MSG": Main help text.
• --help-option "OPT": Custom help flag (default help).
• --version-opt: Enable --version.
• --set-version "VER": Set version number.
• --leftovers: Enable collecting extra arguments (into _arg_leftovers).
• --verbose-level N: Default verbose level (default 0).
• --die-fn-name "NAME": Rename internal die function.
• --log-fn-name "NAME": Rename internal log function.

Example: Generate a New Script

parseArger generate --output /path/to/my-script.sh \
  --pos 'filename "Input file" --complete file' \
  --opt 'output "Output file" --short o --default-value "out.txt"' \
  --flag 'force "Overwrite existing" --short f' \
  --nested 'config "Configuration namespace"' \
  --leftovers

Using Generated Variables

# Variables follow pattern $_arg_<name> (hyphens -> underscores)
echo "File: $_arg_filename"
echo "Output: $_arg_output"
if [ "$_arg_force" == "on" ]; then echo "Forcing..."; fi

# Nested options are associative arrays
# CLI: --config-db sqlite
echo "DB: ${_arg_config[db]}"

---

2. Parse/Modify EXISTING File (parse)

Use when the file EXISTS and was created with parseArger.

parseArger parse FILE [OPTIONS]

Common Options

• -i or --inplace: Modify the file directly (RECOMMENDED).
• --pos, --opt, --flag: Add new arguments to the existing ones.
• --set-version "VER": Update the version.

Example: Modify Existing Script

# Add a new verbose flag to an existing script
parseArger parse my-script.sh --inplace \
  --flag 'verbose "Enable verbose logging" --short v'

CRITICAL: Only use parse on files that:

• Already exist
• Contain # @parseArger comments
• Were created with parseArger

---

3. Subcommands

To create a subcommand structure:

1. Define a positional argument with --subcommand.
2. Use --subcommand-directory "DIR" to point to a directory of scripts.
3. parseArger will treat files in that directory as subcommands.

Example:

parseArger generate --output /path/to/main.sh \
  --pos 'action "What to do" --subcommand --subcommand-directory ./bin'

Specific Subcommand Settings:

• --subcommand-directory "DIR": Auto-populate valid values from scripts in DIR.
• --subcommand-run: Immediately execute the subcommand script found.
• --subcommand-use-leftovers: Pass any leftover arguments to the subcommand.
• --subcommand-variable "VAR": Store subcommand parts in a specific variable (default __subcommand).

---

Quick Reference: generate vs parse

| Scenario | Command | Key Options | |----------|---------|-------------| | Create new script | generate | --output PATH (REQUIRED) | | Modify existing script | parse | --inplace (RECOMMENDED) | | Add arguments to existing | parse | --pos, --opt, --flag | | Update version | parse | --set-version |