clparser.1

.TH clparser 1 "29 May, 2023"
.
.SH NAME
clparser - command line argument parser for shells
.
.SH SYNOPSIS
.\" .SY clparser
.\" .RI [ OPTIONS ]
.\" .B --
.\" .I COMMAND_LINE_ARGS
.\" [\&\.\|.\|.\&]
.\" .YS
.\" .
.SY clparser
.\" .OP \-A|\-\-override-argv
.RB { \-A | \-\-override-argv }
.\" .OP \-a|\-\-maintain-argv
.RB { \-a | \-\-maintain-argv }
.\" .OP \-S|\-s|\-\-shell shell
.RB { \-S | \-s | \-\-shell
.IR shell }
.RB { \-H | \-m | \-\-help\-msg
.IR helpmessage }
.B \-\-
.RI [ COMMAND_LINE_ARGS
\&.\|.\|.\&]
.YS
.
.SY clparser
.BR \-\-help | \-h
.YS
.
.SH DESCRIPTION
.B clparser
takes in command line arguments to parse as command line arguments and a specification for which command line arguments should exist from stdin, and outputs shell code to set variables set from the command line arguments to stdout.
Command line arguments to be parsed should be given after
.BR -- .
This will prevent the command line arguments to be parsed from being interpreted as
.B clparser
command line arguments.
.
.SS Argument Specification Format
The format specifies
.I flags
for setting some optional value to true and
.I parameters
for setting some (optional) value to the value passed in the command line arguments.
There are also
.I positionals
for setting some parameter values (like
.IR parameters )
through named positional arguments rather than specifying the name through
.B \-n
or
.BR \-\-name .
Arguments as specified as flags, parameters, or positionals by being listed after
.IR flags: ,
.IR parameters: ,
or
.IR positionals: ,
respectively.
Arguments are defined as in a space separated list, ended with a semicolon
.RI ( ; ).
E.g.:
.IR "flags: f help test;" .
Arguments to be set together are listed together in a comma separated list.
E.g.:
.IR "flags: f,flags help,h test,t,T;" .
.I positionals
specify the positional arguments in the order given after the
.I positionals:
keyword.
.PP
Parameters (and positionals) can have default values.
Default values set the value of the parameters if the parameter is not set with the input command line arguments.
Default values are set by appending an equals
.RI ( = )
after the parameters (e.g.:
.IR line,l=default ).
.PP
Flags can specify other flags that would negate its value if both are defined.
When a flag with a negation is input and its negation flag is input after it, then the output of the first flag will be false because the second value (set to true) negated it.
E.g.: if
.B \-i
has
.B \-o
set as a negation flag, then the following input arguments
.B \-i \-\-param
.I value
.B \-o
will set set
.B i
to false and
.B o
to true.
This can be helpful, especially when users alias a script with arguments that the user might want to override (imagine
.B \-i
was set in the alias and
.B \-\-param
.I value
.B \-o
was set by the user).
Negation flags can be set by appending equals minus
.RB ( =- )
after flags (e.g.:
.BR i,in=-out ).
Multiple negation flags can be given (e.g.:
.BR i,in=-out=-h ),
which would reset the value of
.B i
if
.B \-\-out
or
.B \-h
are specified after
.BR \-i .
.PP
For a full example, see the
.B EXAMPLES
section below.
.
.SS Parsing Features
There are 2 different types of command line arguments: words and single letters.
Words are specified after 2 dashes
.RB ( -- ),
letters are specified after 1 dash
.RB ( - ).
Letters can be combined on the same input (e.g.:
.BR \-aBc ).
Word parameters can have dashes
.RB ( - )
in them.
These words will be output with underscores
.RB ( _ )
instead of dashes to make a valid variable name.
.PP
Single letter parameters can be used in the combined format if they are the last letter and the value of the parameter is given as the next argument (e.g.:
.BR "\-aBc value" ),
where
.B c
is a parameter, and
.B a
and
.B B
are flags.
.PP
Word parameters can have the value specified in the same argument after an equals
.RB ( = )
(e.g.:
.B \-\-word=\c
.IR value ).
.PP
Positional arguments are defined as values that don't start with \- and do not follow parameters.
If a
.B --
is found, all arguments after it are interpreted as positional arguments.
.SS Description of Output
.B clparser
outputs shell syntax to set variables to the values of the parameters.
By default, the shell will try to choose the shell syntax from the name of the calling process (found in
.RI /proc/ ppid /comm).
If the shell has associative arrays (maps, hash tables, dicts, etc.), 
.I flags
are set in an associative array called
.BR flags ,
and
.I parameters
are set in an associative array called
.BR params .
`sh`, `csh`, and `fish` do not have associative arrays, so flags and parameters are just set as variables.
Positional arguments are set in an array.
`sh` does not have arrays, so it overrides argv to place the positional arguments by default.
See the
.B OPTIONS
section below to see how to override these.
.PP
The output of parameter values and positional arguments is done through the existing positional arguments
.RB ( \(dq${\c
.I number\c
.BR }" )
to prevent issues with the shell interpreting whitespace or symbols in the parameters (see the
.B EXAMPLES
below for an example).
.
.SH OPTIONS
.BR \-h ,
.B \-\-help
Print help info to stderr.
Starts with options showing flags and params in usage for.
Parameters also include the value for the user to input based on the name of the parameter.
If parameters have default values, it shows it after an =.
Under the usage line, it shows lines for each argument with a specified help message (see \-\-help\-msg below).
.PP
.BR \-A ,
.B \-\-override\-argv
Output positional arguments in place of the shell's argv.
This may be useful in some cases, but most shells have arrays to put the arguments in.
This is used by default for `sh` since "$@" is the only way of splitting arguments by argument while maintaining whitespace.
.PP
.BR \-a ,
.B \-\-maintain\-argv
Output positional arguments in a variable named
.B args
instead of overriding argv.
This will allow the original argv to be analyzed and used after parsing arguments.
This will use an array for all shells other than `sh`, since it does not have arrays.
This is not a good option for `sh` since "$@" is the only way of splitting arguments by argument while maintaining whitespace.
.PP
.BR \-n ,
.B \-\-namespace
Namespace args by putting them in associative arrays when available or prepending flags_ or params_ to the variable names.
This option is on by default for shells with associative arrays.
.PP
.BR \-N ,
.B \-\-no\-namespace
Do not namespace args: set variable names directly, allowing flags and parameters to overlap.
This option is on by default for shells without associative arrays.
.PP
.BR \-E ,
.B \-\-no\-output\-empty
Do not output parameters that do not have a value (not specified on command line and no default value).
This can be helpful for a flag and parameter of the same name.
E.g.: a choose flag to indicate to use some user input, but also have a parameter of the same name that takes the user input.
This is only useful for shells that won't error on using undeclared variables that don't use associative arrays (sh and fish) (and namespace isn't used) (or no-namespace is used).
.PP
.BR \-u ,
.BR \-P ,
.B \-\-unknown\-positional
Rather than error on unknown arguments, assume all further arguments are positional.
This is basically allowing users to not need to pass in
.B --
to allow the rest of the arguments to be positional.
.PP
.BR \-e ,
.B \-\-help\-exits
The help option will automatically exit.
This is done by printing `exit` to stdout to be evaluated.
.PP
.BR \-s ,
.BR \-S ,
.B \-\-shell
.I shell
Specify the shell language syntax to be used.
By default, the shell will try to choose the shell syntax from the name of the calling process.
.PP
.BR \-p ,
.B \-\-prog\-name
.I prog_name
Specify the name of the script to use in the usage message.
By default, the shell will try to choose the path of the script of the calling process (the first argument in the cmdline).
This is taken from
.RI /proc/ ppid /cmdline.
.PP
.BR \-H ,
.BR \-m ,
.B \-\-help\-msg
.I helpmsgs
Specify help messages for specified flags/parameters.
The format is
.BR "argument = help message" ,
with argument, message pair per line.
See the
.B EXAMPLES
section below for an example format and output.
.
.SH EXIT STATUS
Exit with success (0) if the arguments and specification are parsed successfully.
Exit with code 1 if outputting help.
Exit with code 1 if there are not alphanumeric (or _ or \-) characters in input parameters.
Exit with code 2 if the passed argument was not found in the specification.
Exit with code 3 if parsing the specification string failed.
Exit with code 2 if there were neither flags or parameters defined in the specification string.
.PP
Yes, these should be separated better.
.
.SH EXAMPLES
Run
.B clparser
in POSIX compliant shells using
.EX sh
spec='flags: f,flag=-g=-h g=-h=-qwerty qwerty=-flag=-h=-g h,help; parameters: q,asdf u=defval nothing zzz,z,Z=someth;'
helpmsg='
help = print this help message
flag = a random flag
g    = i dunno, its nonsense
qwerty = a keyboard layout
asdf = q param
u    = something
zzz  = a bunch of zs
\(aq
eval "$(echo "$spec" | clparser -- "$@")"
.EE
This will output code that looks like
.EX sh
flag=false
f=false
h=false
help=false
g=false
qwerty=true
asdf="${2}"
q="${2}"
Z='test'
zzz='test'
z='test'
u='defval'
nothing="${8}"
set -- "${4}" "${6}" "${10}" "${11}"
.EE
if the user called the script with the arguments
.EX
-fgq whatever --qwerty 'i dunno' --zzz=test words --nothing else -- --test hi
.EE
.PP
For `csh`, call
.B clparser
in this format:
.EX csh
eval `echo $spec:q | ./clparser --help-msg $helpmsg:q -- $argv:q`
.EE
Note that just using
.B $argv
will not preserve whitespace, which will cause bugs, so appending `:q` at the end of variable names is necessary.
.B clparser
and evaluate the resulting `csh` code.
.PP
See `fish` and `xonsh` example syntax in the github repo example files.
For `xonsh`, don't bother using this; just use
.BR argparse .
.PP
The
.B \-\-help
output will look like
.EX
Usage:	"${0}" [ --flag -f ] [ -h --help ] [ -g ] [ --qwerty ] --asdf -q asdf [ -Z --zzz -z zzz = someth ] [ -u u = defval ] --nothing nothing
 [ -h --help ]                                    print this help message
 [ --flag -f ]                                    a random flag
 [ -g ]                                           i dunno, its nonsense
 [ --qwerty ]                                     a keyboard layout
 --asdf -q asdf                                   q param
 [ -u u = defval ]                                something
 [ -Z --zzz -z zzz = someth ]                     a bunch of zs
.EE
.PP
.B TODO
add examples of output for `bash` and `csh` and show use for `fish`.