anvil / bash-argsparse

An high level argument parsing library for bash

bash-argsparse

An high level argument parsing library for bash.

Inspired, by the python argparse module, bash-argsparse purpose is to replace the option-parsing and usage-describing functions commonly rewritten in all scripts.

This library is implemented for GNU bash version >= 4.2. Prior versions of bash will fail at interpreting that code.

Online documentation

Doxygen documentation is available online here.

Tarballs

Though Bash Argsparse is hosted at github, you can download tarballs at the following URL: http://argsparse.livna.org/

RPMS

Though you can build your own package using the provided spec file, a bash-argsparse package is currently available in fedora repositories, for all releases from fedora 19 to rawhide. Ditto for RHEL/Centos 6 & 7, through the EPEL repository.

Features

The argsparse library offers to script developpers the following features:

• Automatic help message generation
• Simple option declarations
• Different option types: simple, with value, with cumulative (uniq or not) values
• User-input checkings (either by type, enumerations or custom checking)
• Hook settings
• Option properties making them excluding each other, aliasing other options, or (sic) non-optional.
• Automatic bash completion generation.

Requirements, Bash settings

A basic argsparse run requires no external commands except the quite-common "getopt" command. Some argsparse-built-in type checkings may require some other (like "host" and "getent") but you do not have to use those types.

Argsparse relies on a lot of bash built-in commands ("printf", "[", "read", ...) and internal features such as arrays, associative arrays, extended (ksh-like) globbing. That's why the "extglob" shell option is automatically enabled and posix-mode is automatically disabled when loading the argsparse library.

The code has been tested on bash 4.1, 4.2 and 4.3 and is definitely not POSIX-compliant.

Compliance with the "nounset" and "failglob" bash settings is supported.

Content

• argsparse.sh: the library.
• tutorial: a bunch of small demonstration scripts for new users.
• bash-argsparse.spec: a spec file to build RPM packages.
• debian: the directory required to build deb packages.
• Doxyfile: doxygen configuration file.
• doxygen-bash.sed: bash-doxygen doxygen input filter.
• unittest: a test script to validate most of argsparse features.

Testing

Here are the topics covered by scripts in tutorial directory:

• 0-completion: An automatic bash completion demo for all other tutorial scripts. This script will spawn a preconfigured interactive bash.
• 1-basics: Bash Argsparse basics
• 2-values: Options accepting values
• 3-cumulative-options: How to keep all user-given values
• 4-types: Type-checking
• 5-custom-types: User-defined types
• 6-properties: Option properties
• 7-value-checking: Advanced value checking using argsparse
• 8-setting-hook: Changing the way options are set
• 9-misc: Other misc argsparse features.

Invoke each script without parameter or with --help to obtain usage message.

Known limitations (or bugs)

• You cannot have a short option without a long option.
• Too few verifications about property values are made.
• Compliance with errexit is not supported (yet).
• Compliance with Non-bind versions of the "host" command has not been tested.

bash-argsparse's Issues

How to make all options "optional"

I have something like this:

. /argsparse.sh

argsparse_use_option =project: "Path of the project to publish. If empty PWD is assumed"

Notice that --project is NOT mandatory. And yet, when I run the script without commands it will print the help and exit.

How do I tell argsparse that it's OK if no option was passed?

Link to doc is broken

It's totaly minor but the link to your doxygen documentation is broken, there's only a 1.6.1 version on http://argsparse.livna.org

Accepted values not working

Hi,
the acceptable values feature does not work for me.
I am using GNU bash, version 4.4.23(1)-release (x86_64-unknown-linux-gnu).
The __argsparse_is_array_declared check never returns true.
Replacing the line with a simple is-set check [[ ! -z ${!array_name+x} ]] (stackoverflow) however, works for me.
I could create an PR, if you want :)

Thanks

Use bash-argsparse inside functions directly

Hello,

First thanks for this great arguments parsing tool.

I'm trying to use it inside function directly as I need to control function usage.
Some exit statement as in usage() function end all
I tried to use a return 1 statement but I have some error because parsing seems to continue and do not stop anymore after using -h argument.

I have errors as :

-bash: --source-path: option is mandatory.
-bash: --destination-path: option is mandatory.

Is there any way to use your bash-argsparse inside functions ?

Thanks in advance for your advices.

Kind regards

Question: bash 4.1 vs 4.2 as minimum requirement

Hi,

The master branch has a patch that started using [[ -v ]], which is a bash 4.2 feature:
0b2bbf6

https://github.com/bminor/bash/blob/master/CHANGES#L3642

README states that GNU bash version >= 4.1 is required.

Do you have plans to bump the min. required bash version to 4.2? Or alternatively, can I open a pull request that replaces -v with something that is 4.1-compatible?

[New Feature] require option1 OR option2

Hi,

Currently require only support 'AND'

argsparse_use_option option1 "desc option1"
argsparse_use_option option2 "desc option2"
argsparse_use_option option2 "desc option3" require:"option1 option2"

=> option3 requires option1 AND option2

It would be nice to have
=> option3 requires option1 OR option2
Or even
=> option3 requiques (option1 AND option2) OR requires (option4 AND option5)

simultaneous exclude and default attribute issue

Hello,

If two options are mutually exclusive (exclude property) and the first one has a default value, the second one is "unavailable", since default always set a value.

Example :
argsparse_use_option option1 "desc option1" value default:toto exclude:option2
argsparse_use_option option2 "desc option2" exclude:option1