ParseArger - Because Bash Argument Parsing Shouldn't Suck

Arguments, Options & Flags

The holy trinity of CLI inputs. Here is the complete reference for how to define them. Generated variables follow the pattern $_arg_name. Hyphens are replaced by underscores.

Positional Arguments (--pos)

Arguments that depend on their position. script.sh arg1 arg2. Usage: --pos 'arg-name "description" [options]'

Validation & Completion

--one-of: Restrict values to a specific list. Repeatable.

parseArger generate --pos 'my-arg "description" --one-of value1 --one-of value2'

--complete: Use Completely built-ins for completion (file, directory, user, etc.).
```
parseArger generate --pos 'filename "file path" --complete file'
```

--complete-custom: Custom dynamic suggestions using a command or script.

parseArger generate --pos 'arg "desc" --complete-custom "$(echo "val1 val2")"'

Subcommands

Turn an argument into a dispatcher for subcommands.

--subcommand-directory: Automatically populate --one-of with scripts found in the specified directory. Forces --subcommand.
```
parseArger generate --pos 'cmd "subcommand" --subcommand-directory bin'
```
--subcommand-variable: Change the variable name for the subcommand (default: __subcommand). Forces --subcommand.
```
parseArger generate --pos 'arg "desc" --subcommand-variable notAsubCommand'
```
--subcommand: Mark this argument as a subcommand.
```
parseArger generate --pos 'arg "desc" --subcommand'
```
--subcommand-run: Run the subcommand immediately before handing control back (or exiting). Forces --subcommand.
```
parseArger generate --pos 'arg "desc" --subcommand-run'
```
--subcommand-use-leftovers: Pass leftover arguments to the subcommand. Forces --subcommand.
```
parseArger generate --pos 'arg "desc" --subcommand-use-leftovers'
```

Options (--opt)

Named arguments that take a value. --output file.txt. Usage: --opt 'arg-name "description" [options]'

Repetition

--repeat: Allow multiple values. The variable becomes an array.
```
parseArger generate --opt 'header "headers" --repeat'
```
--repeat-min: Enforce a minimum number of repetitions. Forces --repeat.
```
parseArger generate --opt 'item "items" --repeat-min 1'
```
--repeat-max: Enforce a maximum number of repetitions. Forces --repeat.
```
parseArger generate --opt 'item "items" --repeat-max 10'
```

Aliases & Shortcuts

--short: Single letter shortcut.

parseArger generate --opt 'output "output file" --short o'

--alias: Full word synonyms. Repeatable.

parseArger generate --opt 'user "username" --alias login --alias u'

Values & Defaults

--default-value: Value to use if not provided.

parseArger generate --opt 'mode "run mode" --default-value "production"'

--empty: Allow the option to be used without a value (acts like a flag in that case).
```
parseArger generate --opt 'optional-val "val" --empty'
```
--empty-value: Specific value to use when the option is present but empty (requires --empty).
```
parseArger generate --opt 'optional-val "val" --empty --empty-value "is-present"'
```
--one-of: Restrict values to a list. Repeatable.
--complete: Bash built-in completion.
--complete-custom: Custom completion.

Flags (--flag)

Booleans. True or False. On or Off. --verbose.

Configuration

--short: Single letter shortcut (e.g., -v).

--on: Default to true (flag turns it off).

parseArger generate --flag 'enable "enabled by default" --on'

--no-name: Custom name for the negation (e.g., --dont-do-that).
```
parseArger generate --flag 'do-it "do it" --no-name dont-do-it'
```

--alias: Alias for the flag. Repeatable.

parseArger generate --flag 'verbose "verbose" --alias loud'

--no-alias: Alias for the flag negation. Repeatable.

parseArger generate --flag 'verbose "verbose" --no-alias quiet --no-alias silent'