What is ParseArger ?
ParseArger is a bash library that generate standalone argument parsing, in bash.
It uses itself to parse it's own arguments, and generate the output.
For a whole project, it generates :
- a project skeleton (optional but why do without ?)
- standalone argument, option and flag parsing for scripts (bread and butter)
- markdown documentation (it's not perfect, but it's there and easily up to date)
- standalone bash completion script (a good dev is a lazy dev), uses Completely
- An html form (to help teach people that command line applications, are faster.)
- An installer script
- A (very unsecure !!) web server that can handle calls to your program
TLDR ??
# 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
./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 !" \
--git-repo "myRandomDevName/my_awesome_project" \
--project-subcommand my-script \
--project-subcommand another-script
Cool, but why ?
Ever wanted to clean-up some cool script you created by adding arguments, options and flags ?
Maybe Boss wants a magic script that does, yesterday, with a smile ! And guess what ? You got stuck with creating it, or even
worse, maintaining it
Have you looked at the nightmare of bash option parsing ? I did, and I just wanted to burn my computer at the
idea of so much boilerplate !
And what about cli completion ? And documentation ? wanna maintain that, eh ?
Oooh oooh, want to deal with this collegue still afraid of the dark (terminal window that would for sure use your program if there was a web UI) ?
Yeah, me neither, so I created this, ParseArger !
And nothing does that already ?
Yes, Yes there are existing stuff, but the neighbor's wheel is not round enough to my taste !
parseArger is based off of
Argbash output, but
I wanted a few more things, and, I didn't understand how it worked...
If you have bigger and more complex project, you should have a look at
Bashly,
I use
Completely (part of Bashly) to
generate the bash completion code, but I wanted the main code to be generated in bash, not ruby
It's gonna be one of those nerd tools, eh ?
Weeeelll, dude, You use it to create command line programs in bash..., if you are afraid of the command line, you
ain't gonna have a good day that's for sure.
If not, this is just another command line program ;)
As it is built using itself, every command is documented using the `--help` flag, you have bash completion
available, and you can find all information concerning arguments and options in
the
readme
and
documentation.
And whose using it ?
Heuuum, me, but in several projects of mine :
- itself
- sshm0 : A terminal based ssh server
manager
- StationIO : An arduino
framework, used in the utility tools (create, upload, ...)
- A bunch of my scripts for various tasks
ParseArger is kind of my bash script template thingy, I need a script, small & dumb ? complex & several scripts ?
parseArger !
If you would like me to showcase your project, feel free to open an
issue, I'll be happy to add it here !
How do I install it ?
Guess what ? I made a script for that ;-D !
# download the script
curl -s https://raw.githubusercontent.com/DimitriGilbert/parseArger/main/utils/get_parseArger -o get_parseArger;
# NOW READ THE DAMN THING ! DO NOT RUN UNKNOWN SCRIPTS FROM THE INTERNET !
cat get_parseArger;
# Or
vim get_parseArger;
# Or ...
# add exec permission
chmod +x get_parseArger;
# get command help
./get_parseArger --help;
# generic install
./get_parseArger --install;
# reload your shell, change rc file accordingly
source ~/.bashrc;
How do I use it ?
In all the following, I'll consider you have parseArger installed
Create a new script
More information for --pos,
--opt,
--flag and
--nested
# output to stdout
parseArger generate [...]
# output to file
parseArger generate --output /path/to/script [...]
# add an argument
parseArger generate --output /path/to/script --pos 'my-argument "my argument description"'
# add an option
parseArger generate --output /path/to/script --opt 'my-option "my option description"'
# add a flag
parseArger generate --output /path/to/script --flag 'my-flag "my flag description"'
# add a nested option
parseArger generate --output /path/to/script --nested 'my-nested-opt "my nested option description"'
# add an argument, 2 options, a flag and a nested option
parseArger generate --output /path/to/script \
--pos 'my-argument "my argument description"' \
--opt 'my-option "my option description"' \
--opt 'my-other-option "my other option description"' \
--flag 'my-flag "my flag description"' \
--nested 'my-nested-opt "my nested option description"'
Parse an existing script
#output to stdout
parseArger parse /path/to/script
# parse in place
parseArger parse /path/to/script -i
# add an argument
parseArger parse -i --pos 'my-new-argument "new argument description"'
# add an option
parseArger parse -i --opt 'my-new-option "new option description"'
# add an flag
parseArger parse -i --flag 'm-newy-flag "new flag description"'
# add a nested option
parseArger parse -i --nested 'my-nested-opt "my nested option description"'
# update script version
parseArger parse -i --set-version 1.2.3
# ...
Generate bash completion for an existing script
# creating bash completion for a script
parseArger completely nameOfScript --file /path/to/script
Document an existing script
# creating documentation for a script to stdout
parseArger document --file /path/to/script
# creating documentation for a script to a file
parseArger document --file /path/to/script --out /path/to/output/file.md
# creating documentation for all scripts in a directory
parseArger document --directory /path/to/scripts/directory
Generate bash completion for an existing script
# creating bash completion for a script
parseArger completely nameOfScript --file /path/to/script
Generate an HTML form for an existing script
# creating form for a script to stdout
parseArger html-form /path/to/script
# creating form for a script to file
parseArger html-form /path/to/script > /path/to/output/file.html
But I really don't like terminal apps, I prefer GUIs
Suuuure, you get the
clicky-clik-tapy-tapotron 9001 right here.
You can generate your own with
parseArger html-form and it could be a start to an electron app front for your bash scripts ( X.D ).
And because, I know, you are lazy, you have a web server written in bash that can call you program, how, cooool, is, that, uh ?
And you have a script for thaaaaaaaat....?
Why yes sir, sure do !
you should have a look at util/webserver !
Am about sure you'll find what you were lookin' for (but it ain't no droids...)
