DEV Community: Dimitri Gilbert

ParseArger, completion, documentation and stuff

Dimitri Gilbert — Wed, 08 Nov 2023 22:39:02 +0000

Now that you can generate and parse scripts with fine tuned arguments, options and flags, we are going to generate supporting stuff for our scripts.

Completion

Completion is a great feature of the terminal that allows you to complete commands, options and arguments by pressing the tab key. It is a great way to avoid typos and to discover new commands and options. For me, it is the main selling point on why you should use the terminal. I use completely, so you have to install it before generating the completion script, but the script itself is standalone. Here comes the help :

  command-name: command-name
  file: file
  --subcommand-directory|--subcmd-dir <subcommand-directory>: directory for subcommand target
  --completely-cmd|--cmpcmd <completely-cmd>: completely command, repeatable
  --extra-file <extra-file>: extra yaml declaration, repeatable
  --yaml-file <yaml-file>: yaml file name [default: ' completely.yaml ']
  --completion-file <completion-file>: completion file name [default: ' completely.bash ']
  --run-completely|--no-run-completely: run completely, on by default (use --no-run-completely to turn it off)
          no-aliases: --no-run,
  --discover-subcommand|--no-discover-subcommand: auto run completely on found subcommand

Let’s have a look a few examples :

# generate completion for my-script
parseArger completely my-script "./my-script"

# generate completion for my-script and its subcommand in the ./bin directory
parseArger completely my-script "./my-script" --subcommand-directory "./bin"

Sometimes, for some esotheric reason, it does not work, but I found a work around :

# generate completion definition for completely
parseArger completely my-script "./my-script" --no-run-completely > completely.yaml
# run completely preview (that does work) and put the output in the completion script file
completely preview > completely.bash

command-name

The command you generate the completion for

parseArger completely my-script ./my-script

file

The executable file for command-name

parseArger completely my-script ./my-script

–subcommand-directory

If your command has subcommands, you can specify the directory where they are located so it will generate the completion as well.

parseArger completely my-script ./my-script --subcommand-directory ./bin

–completely-cmd

Completely is not installed inyour path ? It runs as a container ? That’s ok, you can specify the command to run completely.

parseArger completely my-script ./my-script --completely-cmd "docker run --rm -it completely"

–extra-file

The completion is generated from the arguments options and flags you defined in your script, but you can concatenate other yaml files to add more completion.

parseArger completely my-script ./my-script --extra-file ./my-script.completion.yaml

–yaml-file

If the yaml file name does not suit you.

parseArger completely my-script ./my-script --yaml-file ./not-completely.yaml

–completion-file

Same as for the yaml file.

parseArger completely my-script ./my-script --completion-file ./not-completely.bash

–[no-]run-completely

Output the yaml file to stdout

parseArger completely my-script ./my-script --no-run-completely

–[no-]discover-subcommand

If you have subcommands, you can generate the completion for them as well, but you don’t have to.

parseArger completely my-script ./my-script --no-discover-subcommand

Documentation

making things is coll, but making so that others (or you, after a while) can use whatever you put out there is even cooler. But it is also very long and boring. So I made a tool to do some of it for me. I don’t use the output as is but it’s a good starting point ;).

  -f, --file <file>: file to document, repeatable
  -d, --directory|--folder <directory>: directory to document, repeatable
  -o, --out <out>: output file
  --tag <tag>: markdown tag for title [default: ' ## ']
  --next-tag-prepend <next-tag-prepend>: prepend to next title tag level [default: ' # ']
  --title <title>: documentation title [default: ' Usage ']
  --title-tag <title-tag>: documentation title tag [default: ' # ']
  --sub-directory|--no-sub-directory: document subdirectory, on by default (use --no-sub-directory to turn it off)
  --append-output|--no-append-output: add to output file if it exists, on by default (use --no-append-output to turn it off)

and a few examples :

# generate completion for my-script
parseArger document --file "./my-script" --out "./my-script documentation.md"

# generate completion for my-script and all the scripts in the ./bin directory, erase "my-script documentatino.md" if it exists
parseArger document --file "./my-script" --directory "./bin" --out "./my-script documentation.md" --no-append-output

–file

Document this file, repeatable. First in first out.

# generate completion for my-script and my-other-script
parseArger document --file "./my-script" --file "./my-other-script"

–directory

Document all parseArger scripts in this directory, repeatable. First in first out.

# generate completion for all the scripts in the ./bin and ./I/put/stuff/every/where directories
parseArger document --directory "./bin" --directory "./I/put/stuff/every/where"

–out

If not specified, I will barf all over stdout !

# generate completion output to stdout
parseArger document --file "./my-script"
# generate completion output to documentation.md
parseArger document --file "./my-script" --out "./documentation.md"

–tag

I shall use a tag for titles, default is ##. But you know, if youd rather have h6, you can do that.

parseArger document --file "./my-script" --tag "######"

–next-tag-prepend

I start taggin with –tag value, but for each subsequent title, I prepend this value to the tag. Default is #.

parseArger document --file "./my-script" --next-tag-prepend "######"

–title

If you wanna get fancy with your title, otherwise you’ll get a boring Usage.

parseArger document --file "./my-script" --title "How to use my script"

–title-tag

I already have an h1 bladi bladi blada, whatever …!

parseArger document --file "./my-script" --title-tag "###"

–[no-]sub-directory

If you ain’t tellin’ me, I’ll go though your stuff !

parseArger document --directory "./bin" --no-sub-directory

–[no-]append-output

That is usually how I clean, using a black hole !

parseArger document --file "./my-script" --out "./documentation.md" --no-append-output

HTML form

Wait, what ?!! Why would a bash CLI script need a form ? Well, it doesn’t, but I had the idea of using them for documentation purposes. They come bundled with some (very dirty) javascript to generate a command from the input so less terminally inclined people can take advantage of your tools too (and maybe, just maybe learn to appreciate it ;) ).

  file: file to process
  --command <command>: command string, default to file 
  --action <action>: form action
  --form-class <form-class>: form html class
  --input-container-class <input-container-class>: input container class [default: ' form-group ']
  --input-class <input-class>: input class [default: ' form-control ']
  --label-class <label-class>: label class [default: ' form-label ']
  --select-class <select-class>: select class [default: ' form-select ']
  --checkbox-container-class|--radio-container-class <checkbox-container-class>: checkbox and radio class [default: ' form-check ']
  --checkbox-class|--radio-class <checkbox-class>: checkbox and radio class [default: ' form-check-input ']
  --checkbox-label-class|--radio-label-class <checkbox-label-class>: checkbox and radio label class [default: ' form-check-label ']
  --parent-form <parent-form>: parent form for result
  --form|--no-form: display form, on by default (use --no-form to turn it off)
  --button|--no-button: display button, on by default (use --no-button to turn it off)
  --js|--no-js: create javascript, --no-js forces --no-result, on by default (use --no-js to turn it off)
  --result|--no-result: display result, on by default (use --no-result to turn it off)

file

A simple form for a simple file.

# 
parseArger html-form my-script

–command

If your filename do not match the command you want to run (for alias reasons), you can specify it here.

# when you do not want to keep things simple
parseArger html-form my-script --command "my-script-alias"

–action

The form does not go anywhere by default, but you can change that !

# Where I want to go
parseArger html-form my-script --action "/over/the/rainbow"

–form-class

The form uses bootstrap classes by default so it’s easy and quick to make them pretty. I won’t repeat it, but it goes for all *-class options.

# Me no like bootstrap !
parseArger html-form my-script --form-class "my-form-class"

–input-container-class

# 
parseArger html-form my-script --input-container-class "my-input-container-class"

–input-class

# 
parseArger html-form my-script --input-class "my-input-class"

–label-class

# 
parseArger html-form my-script --label-class "my-label-class"

–select-class

# 
parseArger html-form my-script --select-class "my-select-class"

–checkbox-container-class

# 
parseArger html-form my-script  --checkbox-container-class "my-checkbox-container-class"

–checkbox-class

# 
parseArger html-form my-script --checkbox-class "my-checkbox-class"

–checkbox-label-class

# 
parseArger html-form my-script --checkbox-label-class "my-checkbox-label-class"

–parent-form

When you have sub commands, forms nest into one-another. You can specify the parent form id here.

# 
parseArger html-form my-script --parent-form "my-parent-form"

–form

Then main form id

# 
parseArger html-form my-script --form "my-form"

–[no-]button

On by default, –no- to not create a button

# 
parseArger html-form my-script --no-button

–[no-]js

On by default, –no- to not create javascript

# 
parseArger html-form my-script --no-js

–[no-]result

On by default, –no- to not show results

# 
parseArger html-form my-script --no-result

What now ?

Completion scripts and documentions are a waiting ! You can now more than ever make your bash tools even more awesome (or useful, but who cares about that, uh ? ;) ) ! And if you get so inclined as create a GUI for your script, you have a starting point with the html form (I never said it was a good one ^^). As always bugs and suggestions should go on parseArger’s github repo.

Thanks for the read and I hope you found it useful (or at least entertaining :D )

See you around and happy coding !

ParseArger deeper: --pos --opt and --flag

Dimitri Gilbert — Thu, 26 Oct 2023 09:51:11 +0000

Now that you know the basic of parseArger generate and parse, it's time to have a look at how we declare arguments, options and flags !

--pos

Positional arguments are what most of us use in a bash script with $1, $2, $...
Well same thing here, but they have names And much more :

arg-name: positional argument name
description: positional argument description
--one-of <one-of>: accepted values, repeatable
--complete <complete>: bash built-in completely function, repeatable
--complete-custom <complete-custom>: completely custom dynamic suggestion, repeatable
--subcommand-directory <subcommand-directory>: directory containing subcommands, force subcommand, list parseArger script in directory to fill --one-of
--subcommand-variable <subcommand-variable>: array variable containing subcommand parts, force subcommand [default: ' __subcommand ']
--subcommand|--no-subcommand: is a subcommand
--subcommand-run|--no-subcommand-run: run subcommand, forces sub command
--subcommand-use-leftovers|--no-subcommand-use-leftovers: add leftover arguments to subcommand, forces subcommand

And a dumb example that generates a script that take one argument my-cmd and execute it as a subcommand using the leftover arguments, my-cmd must be one of "ls", "cd" or "cat" :

parseArger generate --pos \
  'my-cmd "an argument" --subcommand --subcommand-run --subcommand-use-leftovers --one-of ls --one-of cd --one-of cat'

arg-name

The argument name, - will be replaced with _ and the variable will be prefixed with _arg_.
So --my-super-argument value is assigned to $_arg_my_super_argument.

description

Simple description for help, documentation and so on

--one-of

Repeatable, The argument value must be one of, the most basic input validation, yeah !

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

--complete

Repeatable, Completely built-ins.

parseArger generate --pos 'my-file "this is a file path" --complete file'

--complete-custom

Repeatable, Completely custom

parseArger generate --pos 'my-arg "this is an argument" --complete-custom "\$(echo \"some_value some_other you_get the_point\")"'

--subcommand-directory

You been a good kid and you did split your scripts ?
If they're all in the subcommand-directory, parseArger will add them to one of and build a __subcommand variable for you to use.
It forces --subcommand ... in case you were wondering.

parseArger generate --pos 'my-arg "this is an argument" --subcommand-directory bin'

--subcommand-variable

Ooooh, oh you don't like __subcommand !!? What should it be called then ? It forces --subcommand.

parseArger generate --pos 'my-arg "this is an argument" --subcommand-variable notAsubCommand'

--subcommand

This is a subcommand

parseArger generate --pos 'my-arg "this is a command argument" --subcommand'

--subcommand-run

Run the subcommand before handing you the script, forces --subcommand.

parseArger generate --pos 'my-arg "this is an argument" --subcommand-run'

--subcommand-use-leftovers

Maybe those leftovers are worth something..., after all ! Forces --subcommand

parseArger generate --pos 'my-arg "this is an argument" --subcommand-use-leftovers

--opt

I'm pretty sure most of you were waiting for that : (add ethereal music here) options !

arg-name: positional argument name
description: positional argument description
--repeat-min <repeat-min>: minimum repeatition forces repeat [default: ' 1 ']
--repeat-max <repeat-max>: maximum repeatition forces repeat
--one-of <one-of>: accepted values, repeatable
-d, --default-value <default-value>: value, repeatable
-s, --short <short>: short form
--alias <alias>: option alias, repeatable
--empty-value <empty-value>: value for empty option
--complete <complete>: bash built-in completely function, repeatable
--complete-custom <complete-custom>: completely custom dynamic suggestion, repeatable
-r|--repeat|--no-repeat: repeatable
--empty|--no-empty: use option as flag

I won't bore you with arg-name and description, and if you need me too, you might want to re read the previous part a tiny tad more attentively, maybe, if you'd like to.

--repeat-min

Repeatable option, yes ! but at least this many ! Forces --repeat.

parseArger generate --opt 'my-opt "this is an option" --repeat-min 42

--repeat-max

Repeatable option, yes ! but not too much ! Forces --repeat.

parseArger generate --opt 'my-opt "this is an option" --repeat-max 69

--one-of

see --pos --one-of above, it's the same ;)

--default-value

An option, why not, but it shall not be empty !

parseArger generate --opt 'my-opt "musnt be eeeemmmmpty" --default-value "this is not empty"'

--short

I know ya'll concerned about bodily efficiency (my mom called that "lazy"...), letters matters ! you got 26 of'em, that's how many options max my scripts have !

parseArger generate --opt 'my-opt "lazily call me" --short o'

--alias

I know it's hard to always agree (especially with yourself !), with aliases, no more decision (about option names), you can have your cake, and eat it, too !

parseArger generate --opt 'a-opt "lazily call me" --alias "an-opt" --alias "an-option" --alias "needlessly-long-option-name"'

--short

I know ya'll concerned about bodily efficiency (my mom called that "lazy"...), letters matters ! you got 26 of'em, that's how many options max my scripts have !

parseArger generate --opt 'my-opt "lazily call me" --short o'

--complete

see --pos --complete above, it's the same ;)

--complete-custom

see --pos --complete-custom above, it's the same ;)

--repeat

You can now have multiple values for your option. the option is now an array, even if only one value is given.

parseArger generate --opt 'my-opt "look ma', I'am an array !" --repeat'

--empty

Option or flag ? Well, why not both ? A flag if you don't give it anything, an option otherwise !

parseArger generate --opt 'my-opt "option>flag superposition" --empty'

--flag

Ahoy ! raise the flaaaaaag ! (I'd say I'm grasping at branches, but it seems tree do not grow in the ocean...)

arg-name: positional argument name
description: positional argument description
-s, --short <short>: short form
--no-name <no-name>: value for the negation
--alias <alias>: flag alias, repeatable
--no-alias <no-alias>: flag negation alias, repeatable
--on|--no-on: on by default

You know the drill with arg-name, description, --short and alias, it's up above ;)

--no-name

--no-<flag-name> do not fly ? Fine, you choose !

parseArger generate --flag 'do-that "flabbergasted, flag a..." --no-name dont-do-that'

--no-alias

There are plenty of ways to say no !

parseArger generate --flag 'do-that "flabbergasted, flag a..." --no-alias this-instead --no-alias do-this'

--on

It's already on... but you can turn it off.

parseArger generate --flag 'do-that "flabbergasted, flag a..." --on'

What now ?

Now you almost have the whole view on parseArger, enough for simple scripts anyway !
But maybe you do not value your mental health much and would like to create a whole program in bash ?
Well, What a coincidence, next time we'll have a look at the project command, it'll help you do just that ! (the program part, I do not deal in mental health)
As always bugs and suggestions should go on parseArger's github repo.

Thanks for the read and I hope you found it useful (or at least entertaining :D )

See you around and happy coding !

ParseArger : create bash scripts you'll want to use

Dimitri Gilbert — Sun, 08 Oct 2023 12:33:11 +0000

So, who here writes bash scripts ? And among these scripts, some take arguments, right ?
Ok ok, so, get me any kind of documentation, usage hint or anything, like, right NOW !

Yeah...it's ok, we've all been there, and if you didn't, you might (not) have had a look at parsing arguments and (AND!) options in a bash script...it's a whole kerfuffle ! Well, "NO MORE !" I say !

Meet parseArger

ParseArger is a bash program to generate standalone bash programs, at least :

the argument and option parsing (hey, I'm not gonna take your job !),
and a basic documentation (just the boring part),
and an install script (...),
and a bash completion script (...right ?),
and an html form (whut ..?!)
aaaaand a web server in bash (OH COOOOME ON !)(not really to be used apart from the time you can't do without... I'm just flexing ^^')

TLDR

Oh, I know ya'll abunch of impatient nerds (at least I am...) so here is a quick run down to get going !

# download the install script
curl -s https://raw.githubusercontent.com/DimitriGilbert/parseArger/main/utils/get_parseArger -O;
# make it executable
chmod +x get_parseArger;
# install, use --help for... help...
./get_parseArger --install;
# source bashrc, only needed once, modify according to your shell (if you don't know, it's the good one :D)
source "$HOME/.bashrc"

# generate a project
parseArger project my-awesome-project \
  --description "this is a cool project !" \
  # no commit, push or nothing, for install script generation
  --git-repo "myRandomDevName/my_awesome_project" \
  --project-subcommand my-script \
  --project-subcommand another-script

cd my-awesome-project
./my-awesome-project --help

Install

First things first, let's install the damn thing !
Open up a terminal and execute those commands :

# download the install script
curl -s https://raw.githubusercontent.com/DimitriGilbert/parseArger/main/utils/get_parseArger -O;
# You are thoughtfully encouraged to spend the next few minutes reading it, just to make sure I do not have nefarious purposes, thank you.

# make it executable
chmod +x get_parseArger;
# install
./get_parseArger --install;
# source bashrc, only needed once, modify according to your shell (if you don't know, it's the good one :D)
source "$HOME/.bashrc"

# check install
parseArger --help

More help is available on the install script, just type ./get_parseArger --help in your terminal.

Generate a script

Let's start simple with a script that has one argument, one option and one flag. We'll output the generated content to ./my-script.

parseArger generate \
  --help-message "this is a script" \
  --pos 'my-arg "my argument"' \
  --opt 'my-option "my option"' \
  --flag 'a-flag "boolean flag for my script"' \
  --output my-script

You are now free to add your actual code at the bottom of the generated file. It will not be modified if (when !) you update the parsing code using parse.
There are more options for --pos, --opt and --flag, I'll dive deeper into that in further articles ;).
Concerning variable created, - will be replaced with _ and the variable will be prefixed with _arg_.
So --my-super-argument value is assigned to $_arg_my_super_argument

Parse a script

Now that we have a script, needs have changed and we miss some options... Let's fix that then !

# -i (or --in-place) means that we update the file with the newly generated parsing code, keeping your custom code
parseArger parse ./my-script -i \
  --opt 'missing-option "my missing option"' \
  --opt 'another-opt "yet another one"'

Done, you you make the code that uses them :).

Completion script

The best thing about the terminal ? completion !
You can't get your mouse on the most likely button you'll need to click in a window (erf, maybe, but ...the usability...).
Well, you can in a terminal :D. Creating the scripts manually though ? Gee..., no !

parseArger completely my-script ./my-script

source ./completely.bash

Remember you'll have to source the completion script to access completion in the terminal, you can add source /path/to/my-script/completion.bash to your .bashrc (or .zshrc and so on)

You will need completely installed for the generation to work, but once generated it's standalone.

Sometimes, things here do not work as expected and I can't figure out why, if it does for you to, use this as a workaround

# do not run completely
parseArger completely my-script \
  ./my-script \
  --no-run-completely > completely.yaml

# use the completely preview and pipe to a file...
completely preview > completely.bash

Documentation

We all have that pesky collegue that never remember how to use the oh so fantastic tools that you create (AKA you in 6 months).
Let's think about that guy a bit and throw him a bone with some documentation !

parseArger document ./my-script --out documentation.md

It's not perfect as it is just the command help in a md file, but it's a whole lot better than nothing, eh ?

Project, anyone ?

You might say that is a whole bunch of mess for a puny script, and you'd be very right !
Who says you have to stop with one script though ? I didn't.
You'd have several ways to do that but I settled on a very opinionated project structure that is as follows

.
├── <program>
├── <program>.rc
├── completely.bash
├── completely.yaml
├── documentation.md
├── form.html
├── Makefile
├── readme.md
├── bin
│   ├── command-one
│   ├── command-two
│   ├── ...
└── utils
    ├── get_<program>
    ├── install
    └── webserver

And of course I made a parseArger command for that : project

parseArger project my-bash-project

Off the bat, it'll create the main program, an rc file for your bashrc, documentation, readme and misc stuff (makefile, installer, webserver, html form). It'll initialize a git repo in the created folder but won't add or commit anything.
With some options, it'll also create the bin folder and command scripts, configure the main program to use these commands (as for generate there'll be another article).

What belongs to Ceasar

This project was started because I couldn't find out how to modify argbash.
Most of the work was (well) done so I took the generated output and went at building a similar generator.
It is not as fancy as the original work and a bit of "grog brain developer" display ... but, meh, it works and it's miiiine.

On that subject, if you are interested in a more rounded up bash generator thingy, you might want to have a look at bashly, I use completely which is a part of it and it's awesome !

What now ?

Well, have at it ! Have fun, create awesome scripts with sh load of options !
Also as I am the only user, it's getting hard to find bugs to squash, though I am pretty sure nests can be found.
And if no bugs are to be found, maybe you have a use case I didn't think of and everyone would benefit from.
All that can be done using issues on parseArger's github repo.

Thanks for the read and I hope you found it useful (or at least entertaining :D )

See you around and happy coding !

ParseArger deeper : generate and parse scripts

Dimitri Gilbert — Sat, 07 Oct 2023 13:25:49 +0000

We previously had a quick look at parseArger.
Let's focus on the generate and parse command today !
I tried to make my arguments descriptions fairly clear, but an example is always nice don't you think ?

Generate

This command will generate (yeah I know, much creativity) a new bash script.
We'll have a look at them one by one but here are the whole lot of arguments, options and flags for the command. (yes, this is the output from --help ^^)

-p, --pos <pos>: positional argument declaration, repeatable
-o, --opt <opt>: optional arg declaration, repeatable
-f, --flag <flag>: flag declaration, repeatable
-s, --set <set>: declare var, repeatable
-l, --source <source>: file to source, repeatable
-m, --help-message <help-message>: help message for the command [default: ' I send an SOS to the world ']
--help-option <help-option>: help option trigger
--help-short-option <help-short-option>: short help option
--leftovers-name <leftovers-name>: extra arguments variable name [default: ' leftovers ']
--use-shebang <use-shebang>: shebang executable [default: ' /bin/bash ']
--set-version <set-version>: set version number
--version-opt-name <version-opt-name>: version option name [default: ' version ']
--version-short-option <version-short-option>: version short option name [default: ' v ']
--die-fn-name <die-fn-name>: die function name [default: ' die ']
--log-fn-name <log-fn-name>: log function name [default: ' log ']
--verbose-opt-name <verbose-opt-name>: verbose option name [default: ' verbose ']
--verbose-level <verbose-level>: default verbose level [default: ' 0 ']
--leftovers|--no-leftovers: accept extra arguments
--bang|--no-bang: include shebang, on by default (use --no-bang to turn it off)
--version-opt|--no-version-opt: generate version opt handling, on by default (use --no-version-opt to turn it off)
--use-verbose|--no-use-verbose: generate verbose level parser, on by default (use --no-use-verbose to turn it off)
--parse-leftovers|--no-parse-leftovers: parse leftovers, force leftover

Forget about --pos --opt and --flag, we are going over them in a different article.

--set

repeatable, declare a variable at the top of the script.
It can use $() to run commands but be careful about escaping (which might cause trouble with parsing sometimes...)

parseArger generate --set 'my_var="my value"' \
  --set 'my_var_dynamic_var="\$(cat /a/file)"'

--source

repeatable, source a file at the top of the script.

parseArger generate --source "/path/to/the/file"

--help-message

the script help message. It might be a good idea to make it useful, but you don't have to... 3:-D

parseArger generate --help-message 'my script does something'

--help-option

option used to trigger help, the fact that you can does not mean that you should.

parseArger generate --help-option 'not-very-helpful-help-opt'

--help-short-option

short option help trigger

parseArger generate --help-short-option z
# because why not z ?

--leftovers-name

extra argument array variable name. Forces --leftovers flag.

parseArger generate --leftovers-name "extra_args"

--use-shebang

specify the shebang, the generated script does not change though, use at your own risk ;).
If you have cross shell compatibility tips and tricks, I am all ears !

parseArger generate --use-shebang "#!/bin/zsh"

--set-version

give a version to the script, not enforcing any kind of whatever here, you can --set-version "potato", i won't judge

parseArger generate --set-version "0.1-alpha-preview-48"

--version-opt-name

version trigger option, --version by default, but if you hate conventions.

parseArger generate --version-opt-name revision

--version-short-option

short option trigger for version

parseArger generate --version-short-option i

--die-fn-name

who wouldn't choose how one dies ? Bar that, I'll let you choose how your script dies.

parseArger generate --die-fn-name wasted

--log-fn-name

same as die, but I have nothing funny to add, so I think I am just rambling at this point, don't you think ?

parseArger generate --log-fn-name report

--verbose-opt-name

parseArger generate --verbose-opt-name tmi

--verbose-level

default verbose level for your script

parseArger generate --verbose-level 42

--leftovers | --no-leftovers

do not waste ! Think about those poor scripts which do not have options.
So you pack all these nice extra arguments and options in an array for later ! And do not read from stdin before you finished it all !!

parseArger generate --leftovers

The array variable is $_arg_leftovers or $_arg_<whatever you chose with --leftovers-name>.

--parse-leftovers | --no-parse-leftovers

Force --leftovers and if you hate unordered mess, you can parse the leftovers and look for option like syntax to be extracted in an associative array. How neat.

parseArger generate --parse-leftovers

The array variable is $_arg_parsed_leftovers or $_arg_parsed_<whatever you chose with --leftovers-name>.

--bang | --no-bang

use a shebang, on by default

parseArger generate --no-bang

--version-opt | --no-version-opt

versions are for looooooosers ! #mainOrDie

parseArger generate --no-version-opt

--use-verbose | --no-use-verbose

when you have nothing to say anyway (or way too many, and you won't stop, and you know you should, but you won't...)

parseArger generate --no-use-verbose

Parse

Whether it is because you forgot something, "oooh, i might be able to do that..." or "DO THAT !", requirements change, just generating the script is already nice but a way to update it would be nicer, like if we couuuuld... parse the script (...).
Like with generate command, the whole bunch of options and then details, if you don't find the documentation below, it's because it's the same as generate, so look up !

file: file to parse
-p, --pos <pos>: add positional argument declaration, repeatable
-o, --opt <opt>: add optional arg declaration, repeatable
-f, --flag <flag>: add flag declaration, repeatable
-s, --set <set>: add declare var, repeatable
-l, --source <source>: add file to source, repeatable
--set-version <set-version>: set version
-i|--inplace|--no-inplace: replace parseArger generated content in place
--leftovers|--no-leftovers: add leftovers
--parse-leftovers|--no-parse-leftovers: parse leftovers

file

path to the file to parse, yes it is a positional argument, thank you for noticing the absence of -.
You are such an attentive reader :)

--inplace

update the file directly, goes to stdout by default

What now ?

Another article is coming to dive deeper in --pos, --opt and --flag options for both generate and parse so you can truly take full advantage of parseArger ;) !
But this has been most of my usage, barebones arguments, simple options (and a few flags, not often).
This is such a step up from bash scripts I created in the past, especially with the generated help !
What about you ? Would this help you or are you using other languages when "more complex" scripts are needed ?

See you around and happy coding !