playbooks

home / skills / dimitrigilbert / parsearger / parsearger-core

parsearger-core skill

/skills/parsearger-core

This skill helps generate or modify bash argument parsers using parseArger to define positional arguments, flags, and options efficiently.

npx playbooks add skill dimitrigilbert/parsearger --skill parsearger-core

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
6.3 KB
---
name: parsearger-core
description: Core functionality for parseArger. Use this skill to GENERATE new bash argument parsers or PARSE/MODIFY existing ones. Handles definition of positional arguments, flags, and options.
license: MIT
compatibility: Requires parseArger executable in the working directory or PATH.
---

# ParseArger Core Skills

## 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`

```bash
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

```bash
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

```bash
# 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`.**

```bash
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

```bash
# 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:
```bash
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` |

Overview

This skill provides the core functionality for parseArger: generating new bash argument parsers and parsing or modifying existing parseArger-managed scripts. It handles definitions for positional arguments, options, flags, nested options and subcommands, and emits safe, regenerable parsing code. Use it to produce consistent CLI parsing logic and to update existing scripts in-place.

How this skill works

When generating, the skill emits a bash script with a dedicated generated section between markers # @parseArger-parsing and # @parseArger-parsing-end; that block must never be edited by hand. When parsing/modifying, it inspects the target file to ensure it was created by parseArger, then injects or regenerates parsing logic based on top-of-file declarations. The tool always checks for a parseArger executable in PATH and falls back to ./parseArger in the project root if not found.

When to use it

  • Create a new CLI script with structured argument parsing (use generate with --output).
  • Add new flags, options, or positional arguments to a script already managed by parseArger (use parse --inplace).
  • Update the parsing logic after changing top-of-file --pos/--opt/--flag declarations.
  • Define subcommands backed by a directory of scripts and pass leftovers to subcommands.
  • Enforce argument validation (regex, one-of lists, repeat counts, completion hooks).

Best practices

  • Always run which parseArger first; fallback to ./parseArger if not found.
  • Never edit the code between # @parseArger-parsing and # @parseArger-parsing-end manually.
  • For new scripts always provide --output; otherwise output goes to stdout only.
  • Use --inplace when modifying existing scripts to regenerate parsing logic safely.
  • Name options and flags consistently; generated variables follow the _arg_<name> pattern (hyphens -> underscores).

Example use cases

  • Add a verbose flag to an existing parseArger script in-place: parseArger parse my-script.sh --inplace --flag 'verbose "Enable verbose" --short v'.
  • Define a subcommand entry and run matching subcommand scripts from a directory: use --pos with --subcommand and --subcommand-directory.
  • Create validated positional arguments with --match or restrict values with --one-of for safer CLI inputs.
  • Use nested options to model namespaced config like --config-db and access values via associative arrays in the generated script.

FAQ

What if the target file doesn't exist?

Use generate with --output to create a new script; parse is only for existing parseArger-managed files.

How do I update parsing after changing declarations?

Edit the top-of-file --pos/--opt/--flag declarations and run parseArger parse FILE --inplace to regenerate the parsing block.