├── debian
    ├── compat
    ├── docs
    ├── rules
    ├── control
    └── changelog
├── .gitignore
├── .travis.yml
├── COPYING
├── tutorial
    ├── 5-custom-types
    ├── 0-completion
    ├── 7-value-checking
    ├── 3-cumulative-options
    ├── 2-values
    ├── 9-misc
    ├── 8-setting-hook
    ├── 1-basics
    ├── 6-properties
    └── 4-types
├── bash-argsparse.spec
├── README.md
├── doxygen-bash.sed
├── argsparse-completion.sh
├── unittest
└── argsparse.sh


/debian/compat:
--------------------------------------------------------------------------------
1 | 5
2 | 


--------------------------------------------------------------------------------
/debian/docs:
--------------------------------------------------------------------------------
1 | html
2 | tutorial
3 | README.md
4 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | *~
 2 | html
 3 | latex
 4 | debian/bash-argsparse*
 5 | debian/files
 6 | debian/debhelper-build-stamp
 7 | unittest.log
 8 | \#*
 9 | .\#*
10 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | matrix:
 2 |   include:
 3 |     - os: linux
 4 |       dist: precise
 5 |     - os: linux
 6 |       dist: trusty
 7 |     - os: linux
 8 |       dist: xenial
 9 | 
10 | language: bash
11 | 
12 | script:
13 |   - ./unittest
14 | 


--------------------------------------------------------------------------------
/debian/rules:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/make -f
 2 | 
 3 | override_dh_install:
 4 | 	dh_install
 5 | 	rm -R debian/bash-argsparse
 6 | 	mkdir -p debian/bash-argsparse/usr/bin
 7 | 	for file in argsparse argsparse-completion; do \
 8 | 	install -m 0755 "$$file.sh" debian/bash-argsparse/usr/bin ; \
 9 | 	ln -s "$$file.sh" debian/bash-argsparse/usr/bin/"$$file" ; \
10 | 	done
11 | 
12 | build:
13 | 	dh build
14 | 	doxygen
15 | 
16 | %:
17 | 	dh $@
18 | 


--------------------------------------------------------------------------------
/COPYING:
--------------------------------------------------------------------------------
 1 |             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
 2 |                     Version 2, December 2004
 3 | 
 4 |  Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
 5 | 
 6 |  Everyone is permitted to copy and distribute verbatim or modified
 7 |  copies of this license document, and changing it is allowed as long
 8 |  as the name is changed.
 9 | 
10 |             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
11 |    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
12 | 
13 |   0. You just DO WHAT THE FUCK YOU WANT TO.
14 | 
15 | 


--------------------------------------------------------------------------------
/debian/control:
--------------------------------------------------------------------------------
 1 | Source: bash-argsparse
 2 | Section: libs
 3 | Priority: optional
 4 | Maintainer: Damien Nade <bash-argsparse@livna.org>
 5 | Build-Depends: debhelper (>= 7.0.50), doxygen
 6 | 
 7 | Package: bash-argsparse
 8 | Architecture: all
 9 | Depends: bash (>= 4), util-linux
10 | Homepage: https://github.com/Anvil/bash-argsparse
11 | Description: An high level argument parsing library for bash 
12 |  An high level argument parsing library for bash.
13 |  .
14 |  The purpose is to replace the option-parsing and usage-describing
15 |  functions commonly rewritten in all scripts.
16 |  .
17 |  This library is implemented for bash version 4. Prior versions of
18 |  bash will fail at interpreting that code.
19 |  .
20 | 


--------------------------------------------------------------------------------
/debian/changelog:
--------------------------------------------------------------------------------
 1 | bash-argsparse (1.8) unstable; urgency=low
 2 | 
 3 |   * Version 1.8
 4 | 
 5 |  -- Damien Nadé <bash-argsparse@livna.org>  Tue, 05 Sep 2017 13:57:55 +0200
 6 | 
 7 | bash-argsparse (1.7) unstable; urgency=low
 8 | 
 9 |   * Version 1.7
10 | 
11 |  -- Damien Nadé <bash-argsparse@livna.org>  Thu, 5 Mar 2015 12:20:00 +0100
12 | 
13 | bash-argsparse (1.6.2) unstable; urgency=low
14 | 
15 |   * Version 1.6.2
16 | 
17 |  -- Damien Nadé <bash-argsparse@livna.org>  Thu, 22 Jan 2015 16:35:00 +0100
18 | 
19 | bash-argsparse (1.6.1) unstable; urgency=low
20 | 
21 |   * Version 1.6.1
22 | 
23 |  -- Damien Nadé <bash-argsparse@livna.org>  Thu, 10 Oct 2014 19:40:00 +0200
24 | 
25 | bash-argsparse (1.6) unstable; urgency=low
26 | 
27 |   * Version 1.6
28 |   * Doxygen documentation
29 | 
30 |  -- Damien Nadé <bash-argsparse@livna.org>  Mon, 13 Jan 2014 10:31:12 +0100
31 | 
32 | bash-argsparse (1.5) unstable; urgency=low
33 | 
34 |   * Initial packaging
35 | 
36 |  -- Damien Nadé <bash-argsparse@livna.org>  Mon, 18 Mar 2013 12:39:40 +0200
37 | 
38 | 


--------------------------------------------------------------------------------
/tutorial/5-custom-types:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # Argsparse also allows user-defined types. To do so, just define a
 9 | # check_option_type_<your_type_name> function.
10 | # E.g, for a `binary' type.
11 | 
12 | check_option_type_binary() {
13 | 	local value=$1
14 | 	# the function must return 0 if the provided argument (the value
15 | 	# submitted by the user) is valid.
16 | 	[[ "$value" =~ ^[01]+$ ]]
17 | }
18 | 
19 | # This function allows you to give the 'type' property the value
20 | # 'binary'.
21 | argsparse_use_option bin-option "An binary word." type:binary value
22 | 
23 | printf -v argsparse_usage_description "%s\n" \
24 | 	"A example script using user-defined types." \
25 | 	"Try command lines such as:" \
26 | 	" $0 --bin-option something-wrong" \
27 | 	" $0 --bin-option 0101010101111"
28 | 
29 | # Command line parsing is done here.
30 | argsparse_parse_options "$@"
31 | 
32 | printf "Options reporting:\n"
33 | # Simple reporting function.
34 | argsparse_report
35 | printf "End of argsparse report.\n\n"
36 | 


--------------------------------------------------------------------------------
/tutorial/0-completion:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | tutorial_directory=${BASH_SOURCE[0]%/*}
 4 | 
 5 | # This script creates a custom (volatile) bashrc that will basically
 6 | # just enable programmable completion for other tutorial scripts and
 7 | # invoke an interactive shell
 8 | read -N 4096 bashrc <<EOF
 9 | . /etc/profile
10 | shopt -s progcomp sourcepath
11 | PATH="$PATH:$tutorial_directory"
12 | . "$tutorial_directory/../argsparse-completion.sh"
13 | complete -F _argsparse_complete \
14 | 	1-basics 2-values 3-cumulative-options \
15 | 	4-types 5-custom-types 6-properties \
16 | 	7-value-checking 8-setting-hook 9-misc
17 | 
18 | cd "$tutorial_directory" || exit
19 | 
20 | printf "You are currently in %s directory and completion is enabled.\\\\n" \
21 | 	"$tutorial_directory"
22 | printf "Try:\\\n\\\\n./1-basics -<tab><tab>\\\\n\\\\n"
23 | EOF
24 | exec bash --rcfile <(printf %s "$bashrc") -i
25 | 
26 | cat <<EOF
27 | 
28 | As you can see, the Bash Argsparse Completion module can automatically
29 | enable the bash completion for the scripts you develop with the Bash
30 | Argsparse library.
31 | 
32 | To enable completion for your own scripts, please ensure
33 | bash_completion is enabled, and then in your ~/.bashrc, add lines such
34 | as:
35 | 
36 |     . argsparse-completion.sh
37 |     complete -F _argsparse_complete yourscript your_other_script
38 | 
39 | EOF
40 | 


--------------------------------------------------------------------------------
/tutorial/7-value-checking:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # Beside the 'type', you can control options user-given values by
 9 | # using other methods.
10 | 
11 | argsparse_use_option option1 "An enumerated option." value
12 | 
13 | # *Instead* of declaring a type for the option, you can declare an
14 | # array named option_<optionname>_values, which will contain the
15 | # acceptable values for said option.
16 | option_option1_values=(only accepting those values)
17 | # Acceptable values are mentioned in argsparse usage.
18 | 
19 | # And, after either type checking of enumerated values checking, you
20 | # have the possibility to simply define a function named
21 | # check_value_of_<optionname>. If the function return with value 0, it
22 | # means the value is correct. Any other value returned by the function
23 | # would make the value incorrect.
24 | argsparse_use_option option2 "An always bad option." value
25 | check_value_of_option2() {
26 | 	# So, this would make all values return an error.
27 | 	false
28 | }
29 | 
30 | # If an option name contains '-' chars...
31 | argsparse_use_option long-option "An option with a long name." value
32 | # ... then the array name...
33 | option_long_option_values=(long option acceptable values)
34 | # ... and the function name must have '_' in place of '-'.
35 | check_value_of_long_option() {
36 | 	local value=$1
37 | 	[[ "$value" = long ]]
38 | }
39 | 
40 | # 
41 | printf -v argsparse_usage_description "%s\n" \
42 | 	"A tutorial script teaching advanced value checking." \
43 | 	"Try command lines such as:" \
44 | 	" $0" \
45 | 	" $0 -h" \
46 | 	" $0 --option1 only" \
47 | 	" $0 --option2 something" \
48 | 	" $0 --long-option only"
49 | 
50 | # Command line parsing is done here.
51 | argsparse_parse_options "$@"
52 | 
53 | printf "Options reporting:\n"
54 | # Simple reporting function.
55 | argsparse_report
56 | printf "End of argsparse report.\n\n"
57 | 


--------------------------------------------------------------------------------
/tutorial/3-cumulative-options:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # It is possible to have cumulative options with argsparse. Cumulative
 9 | # options can be repeated and all values are kept in an array.
10 | # To have a cumulative option just declare an option with the
11 | # 'cumulative' property.
12 | argsparse_use_option =option1 "A cumulative option" cumulative
13 | # The user-given values will be stored in the array named
14 | # cumulated_values_<option name>
15 | 
16 | # The cumulativeset property acts exactly like cumulative, except that
17 | # there can not be any repetition of a value, like in a python 'set'.
18 | 
19 | # e.g: In this example, using "--option2 foo --option2 foo" wont add a
20 | # second 'foo' to option2 list of user-given values.
21 | argsparse_use_option option2 "A uniqly-cumulative option" \
22 | 	cumulativeset short:O
23 | 
24 | # 
25 | printf -v argsparse_usage_description "%s\n" \
26 | 	"A tutorial script for cumulative options." \
27 | 	"Try command lines such as:" \
28 | 	" $0" \
29 | 	" $0 -h" \
30 | 	" $0 --option1 123" \
31 | 	" $0 --option1 123 -o 456 -o 'foo bar'" \
32 | 	" Also note the difference of behaviour between those 2 lines:" \
33 | 	" $0 --option1 123 -o 123 -o 456 -o 'foo bar' -o 456" \
34 | 	" $0 --option2 123 -O 123 -O 456 -O 'foo bar' -O 456"
35 | 
36 | # Command line parsing is done here.
37 | argsparse_parse_options "$@"
38 | 
39 | printf "Options reporting:\n"
40 | # Simple reporting function.
41 | argsparse_report
42 | printf "End of argsparse report.\n\n"
43 | 
44 | # 
45 | if argsparse_is_option_set option1
46 | then 
47 | 	printf 'option1 has been set %d time(s):\nUser-given values are:\n' \
48 | 		"${#cumulated_values_option1[@]}"
49 | 	printf -- '- %s\n' "${cumulated_values_option1[@]}"
50 | fi
51 | 
52 | if argsparse_is_option_set option2
53 | then 
54 | 	printf 'option2 has been set %d time(s):\nUser-given values are:\n' \
55 | 		"${#cumulated_values_option2[@]}"
56 | 	printf -- '- %s\n' "${cumulated_values_option2[@]}"
57 | fi
58 | 


--------------------------------------------------------------------------------
/tutorial/2-values:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | #
 3 | 
 4 | PATH="..:$PATH"
 5 | 
 6 | # Load argsparse library.
 7 | . argsparse.sh
 8 | 
 9 | # We declare an option accepting a value by giving it the "value"
10 | # property. By default, if an option with the "value" property is
11 | # repeated on the command line, only the last value is kept in
12 | # program_options. See other tutorials to learn how to have such
13 | # cumulative options.
14 | argsparse_use_option option1 "An option." value
15 | 
16 | # Declaring an option accepting a value and not having a
17 | # single-char equivalent. (Alternative syntax)
18 | # Ending the option name by ':' is equivalent
19 | argsparse_use_option option2: "Another option."
20 | 
21 | # Of course, options can accept multiple properties.
22 | argsparse_use_option option3 "A 3rd option." short:o value
23 | 
24 | # Alternative syntaxes for the same thing.
25 | argsparse_use_option option4: "A 4th option." short:p
26 | argsparse_use_option op=tion5: "A 5th option."
27 | 
28 | # Another option accepting a value, with a single-char equivalent.
29 | # Setting the "default" property to an option make it have a default
30 | # value. An option with a default value is considered as always set.
31 | argsparse_use_option option6 "A 6th option." short:i value default:some_value
32 | # Note that 'default' does not imply 'value'.
33 | 
34 | # Declaring the option... 
35 | argsparse_use_option option7 "A 7th option."
36 | # ...and setting properties after.
37 | argsparse_set_option_property value option7
38 | argsparse_set_option_property short:n option7
39 | argsparse_set_option_property default:default_option7_value option7
40 | 
41 | # 
42 | printf -v argsparse_usage_description "%s\n" \
43 | 	"A example script with options accepting values." \
44 | 	"Try command lines such as:" \
45 | 	" $0 --help" \
46 | 	" $0 --option1" \
47 | 	" $0 --option1 my_value" \
48 | 	" $0 -o some_other_value --option2 asdf" \
49 | 	" $0 --option7 not_default_anymore"
50 | 
51 | # Command line parsing is done here.
52 | argsparse_parse_options "$@"
53 | 
54 | printf "Options reporting:\n"
55 | # Simple reporting function.
56 | argsparse_report
57 | printf "End of argsparse report.\n\n"
58 | 


--------------------------------------------------------------------------------
/tutorial/9-misc:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # Miscellaneous other functions. See below.
 9 | 
10 | argsparse_use_option option1 "An option" value exclude:option2
11 | argsparse_use_option option2 "Another option"
12 | 
13 | # 
14 | printf -v argsparse_usage_description "%s\n" \
15 | 	"A tutorial script to show other misc argsparse features." \
16 | 	"Try command lines such as:" \
17 | 	" $0" \
18 | 	" $0 -h" \
19 | 	" $0 --option1 123a" \
20 | 	" $0 --option2"
21 | 
22 | # You can define your own usage function
23 | usage() {
24 | 	printf "Beginning of usage\n"
25 | 	# Unless you want it to be completely removed, you can still call
26 | 	# argsparse_usage function to also have auto-generated argsparse
27 | 	# usage message.
28 | 	argsparse_usage
29 | 	printf "End of usage\n"
30 | 	# And perform your own exit.
31 | 	exit 16
32 | }
33 | 
34 | # Allow empty command line
35 | argsparse_allow_no_argument yes
36 | 
37 | # Command line parsing is done here.
38 | argsparse_parse_options "$@"
39 | 
40 | if [[ $# -eq 0 ]]
41 | then
42 | 	cat <<'information'
43 | Though this script has been called without any parameter, `usage' has
44 | not been triggered, due to the "argsparse_allow_no_argument yes"
45 | executed a few lines above in the script.
46 | 
47 | To obtain the usage message, explicitly add --help on the command line.
48 | 
49 | information
50 | fi
51 | 
52 | # The argsparse_has_option_property function returns with 0 if a named
53 | # option has a named property. If the property has a value, it is
54 | # printed to standard input. So you can do things like that:
55 | if exclusion=$(argsparse_has_option_property option1 exclude)
56 | then
57 | 	printf "The option %s excludes these other options: %s\n" \
58 | 		option1 "$exclusion"
59 | fi
60 | 
61 | for option in option1 option2
62 | do
63 | 	if argsparse_has_option_property "$option" value
64 | 	then
65 | 		printf "%s has the value property.\n" "$option"
66 | 	else
67 | 		printf "%s does not have the value property.\n" "$option"
68 | 	fi
69 | done
70 | 
71 | printf "\nOptions reporting:\n"
72 | # Simple reporting function.
73 | argsparse_report
74 | printf "End of argsparse report.\n\n"
75 | 


--------------------------------------------------------------------------------
/tutorial/8-setting-hook:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # You can also change the way options are set by defining a function
 9 | # named set_option_<optionname>.
10 | argsparse_use_option option1 "An option." value type:hexa
11 | 
12 | set_option_option1() {
13 | 	local option=$1
14 | 	local value=$2
15 | 	# You can do own stuff here. Whatever you want, including,
16 | 	# transforming the value, calling other functions, performing some
17 | 	# actions..
18 | 	# E.g: you could enforce the 0x in front of a user-given
19 | 	# hexadecimal value.
20 | 	if [[ "$value" != 0x* ]]
21 | 	then
22 | 		value="0x$value"
23 | 	fi
24 | 	# This is the original argsparse setting action.
25 | 	argsparse_set_option_with_value "$option" "$value"
26 | }
27 | 
28 | # For options without value.
29 | argsparse_use_option option2 "Another option."
30 | 
31 | set_option_option2() {
32 | 	local option=$1
33 | 	# Again, you can do whatever you want here.
34 | 	: some command with some params.
35 | 	# You dont have to do it, but it makes sense to call in the end
36 | 	# the original argsparse action.
37 | 	argsparse_set_option_without_value "$option"
38 | }
39 | 
40 | # This is a way to re-implement a cumulative option if you're
41 | # satisfied with the 'cumulative' property.
42 | argsparse_use_option cumul "A cumulative option." value
43 | 
44 | all_cumul_values=()
45 | set_option_cumul() {
46 | 	local option=$1
47 | 	local value=$2
48 | 	# Append the value to the array.
49 | 	all_cumul_values+=( "$value" )
50 | 	# Doing this will prevent the argsparse_is_option_set test from
51 | 	# returning false.
52 | 	argsparse_set_option_with_value "$option" 1
53 | }
54 | 
55 | # 
56 | printf -v argsparse_usage_description "%s\n" \
57 | 	"A tutorial script teaching how to change the way options are set." \
58 | 	"Try command lines such as:" \
59 | 	" $0" \
60 | 	" $0 -h" \
61 | 	" $0 --option1 123a" \
62 | 	" $0 --option2" \
63 | 	" $0 --cumul first --cumul second --cumul other"
64 | 
65 | # Command line parsing is done here.
66 | argsparse_parse_options "$@"
67 | 
68 | printf "Options reporting:\n"
69 | # Simple reporting function.
70 | argsparse_report
71 | printf "End of argsparse report.\n\n"
72 | 
73 | printf "These are all the 'cumul' option values:\n"
74 | i=0
75 | for v in ${all_cumul_values[@]}
76 | do
77 | 	printf "Value #%d: %s\n" $((++i)) "$v"
78 | done
79 | 


--------------------------------------------------------------------------------
/tutorial/1-basics:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # Declaring an option not accepting a value and not having a
 9 | # single-char equivalent.
10 | argsparse_use_option option1 "An option."
11 | 
12 | # Declaring an option not accepting a value but with a single-char
13 | # equivalent.
14 | 
15 | # "short" is a property, and "o" is the value of the "short" property
16 | # for this option. Argsparse can handle other properties, see other
17 | # tutorials.
18 | argsparse_use_option option2 "Another option." short:o
19 | 
20 | # Alternative syntax to declare an option with a single-char
21 | # equivalent. A '=' char can be put prior to a char in the option name
22 | # to make a single-letter equivalent. e.g:
23 | argsparse_use_option o=ption3 "A 3rd option."
24 | # does the same as:
25 | # argsparse_use_option option3 "A 3rd option." short:p
26 | 
27 | # You can declare an option without property...
28 | argsparse_use_option option4 "A 4th option."
29 | # ... and set a property after the declaration using the
30 | # argsparse_set_option_property function.
31 | argsparse_set_option_property short:4 option4 
32 | 
33 | # argsparse_usage_description is a simple variable printed at the end
34 | # of the usage function invocation.
35 | printf -v argsparse_usage_description "%s\n" \
36 | 	"A tutorial script for argsparse basics." \
37 | 	"Try command lines such as:" \
38 | 	" $0" \
39 | 	" $0 -h" \
40 | 	" $0 --option1" \
41 | 	" $0 --option1 -h" \
42 | 	" $0 --option2" \
43 | 	" $0 -o -p -4" \
44 | 	" $0 -op4" \
45 | 	" $0 --doesnt-exist" \
46 | 	" $0 --option1 -o -o -o one two 5"
47 | 
48 | # Command line parsing is done here.
49 | argsparse_parse_options "$@"
50 | 
51 | printf "Options reporting:\n"
52 | # Simple reporting function.
53 | argsparse_report
54 | printf "End of argsparse report.\n\n"
55 | 
56 | for option in option{1..4}
57 | do
58 | 	# This is the way you should test your options....
59 | 	if argsparse_is_option_set "$option"
60 | 	then
61 | 		printf "%s was set %d time(s) on the command line.\n" \
62 | 			"$option" \
63 | 			"${program_options[$option]}" # ... and this is the way
64 | 										  # you should access them.
65 | 	else
66 | 		printf "%s was not on the command line.\n" "$option"
67 | 	fi
68 | done
69 | printf "\n"
70 | 
71 | i=1
72 | # You can access all other script parameters through the
73 | # program_params array.
74 | for param in "${program_params[@]}"
75 | do
76 | 	printf "Parameter #%d: %s\n" $((i++)) "$param"
77 | done
78 | 


--------------------------------------------------------------------------------
/tutorial/6-properties:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # In previous tutorials, we have already seen some properties: 
 9 | # * short
10 | # * value
11 | # * default
12 | # * cumulative
13 | # * type
14 | 
15 | # There exists other properties.
16 | 
17 | # options with 'mandatory' property are not an option (sic). All
18 | # 'mandatory' must be set on the command line.
19 | argsparse_use_option option1 "A mandatory option." mandatory
20 | 
21 | # The 'hidden' property hides an option to the user by not showing the
22 | # option in the usage message nor in the argsparse_report output.
23 | argsparse_use_option option2 "An hidden option." hidden
24 | 
25 | # Options can exclude each others, through the 'exclude' property.
26 | argsparse_use_option option3 "A 3rd option."
27 | argsparse_use_option option4 "A 4th option." exclude:option3
28 | # The 'exclude' property value is actually a space-separated option list.
29 | argsparse_use_option option5 "A 5th option." exclude:'option3 option4'
30 | 
31 | # You can set option aliases using the 'alias' property. Only options
32 | # without the 'value' property are accepted both as the alias and as
33 | # 'alias' property value.
34 | # As for the 'exclude' property, the 'alias' property value is a
35 | # space-separated option list.
36 | argsparse_use_option option6 "A 6th option." alias:'option1 option2 option3'
37 | # Aliases are mentioned in argsparse usage.
38 | 
39 | # You can make an alias of an alias. But be careful, though, as there
40 | # is currently no loop detection.
41 | argsparse_use_option option7 "A 7th option" alias:option6
42 | 
43 | # You can also create dependencies between options. In this case, if
44 | # you specify --option8, you cannot omit --option2 nor --option3.
45 | argsparse_use_option option8 "A 8th option" require:"option2 option3"
46 | 
47 | # 
48 | printf -v argsparse_usage_description "%s\n" \
49 | 	"A tutorial script teaching other argsparse option properties." \
50 | 	"Try command lines such as:" \
51 | 	" $0" \
52 | 	" $0 -h" \
53 | 	" $0 --option1" \
54 | 	" $0 --option2" \
55 | 	" $0 --option3 --option4" \
56 | 	" $0 --option5 --option4" \
57 | 	" $0 --option1 --option6"
58 | 
59 | # Command line parsing is done here.
60 | argsparse_parse_options "$@"
61 | 
62 | printf "Options reporting:\n"
63 | # Simple reporting function.
64 | argsparse_report
65 | printf "End of argsparse report.\n\n"
66 | 
67 | if argsparse_is_option_set option2
68 | then
69 | 	printf "The hidden option %s has been set. %d time(s)\n" \
70 | 		option2 "${program_options[option2]}"
71 | else
72 | 	printf "The hidden option %s remains hidden and unset.\n" option2
73 | fi
74 | 


--------------------------------------------------------------------------------
/tutorial/4-types:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | 
 3 | PATH="..:$PATH"
 4 | 
 5 | # Load argsparse library.
 6 | . argsparse.sh
 7 | 
 8 | # Here is an option accepting a integer-typed value, by simply using
 9 | # the 'type' property. Note that 'type' doesnt imply 'value'.
10 | argsparse_use_option option1 "An option" value type:int
11 | 
12 | # Argsparse has a bunch of built-in types. Most of them are self explicit.
13 | argsparse_use_option file: "A regular file" type:file
14 | argsparse_use_option =directory: "A directory" type:directory
15 | argsparse_use_option pipe: "An on-disk named FIFO" type:pipe
16 | argsparse_use_option terminal: \
17 | 	"A file descriptor pointing number to a terminal" type:terminal
18 | argsparse_use_option socket: "An unix named socket" type:socket
19 | argsparse_use_option link: "A symbolic link name" type:link
20 | argsparse_use_option char: "A single char" type:char
21 | # type:unsignedint is the same as type:uint 
22 | argsparse_use_option unsignedint: "An unsigned integer" type:uint
23 | # type:integer is the same as type:int
24 | argsparse_use_option int: "Just some random possibly negative integer" \
25 | 	type:int
26 | argsparse_use_option hexa: "Some hexadecimal value" type:hexa
27 | # IP excludes IP4 and IP6 (and vice-versa)
28 | argsparse_use_option IP: "An IP (either v4 *or* v6) address" type:ip
29 | # IP4 excludes IP6
30 | argsparse_use_option IP4: "An IPv4 address" type:ipv4
31 | argsparse_use_option IP6: "An IPv6 address" type:ipv6
32 | argsparse_use_option host: "Some host" type:host
33 | argsparse_use_option user: "A system UNIX user name" type:username
34 | argsparse_use_option group: "A UNIX group name" type:group
35 | argsparse_use_option date: "Valid date string" type:date
36 | 
37 | # A port number is just a regular postive <1-65535> integer.
38 | argsparse_use_option portnumber: "An IP port number" type:portnumber
39 | 
40 | # An IP port can be referenced either by its port number or it can be
41 | # resolved using (among other things) the /etc/services file. 
42 | # The command "telnet localhost domain" would actually do 
43 | # "telnet 127.0.0.1 53"
44 | # Check the getserent(3) man page for details about this magic.
45 | argsparse_use_option port: "An IP port number _or_ name" type:port
46 | 
47 | # Type names are case insensitive, by the way.
48 | argsparse_use_option hostname: "Some host name (not an IP)" type:hOsTnAmE
49 | 
50 | printf -v argsparse_usage_description "%s\n" \
51 | 	"A example script with type-checking options." \
52 | 	"Try command lines such as:" \
53 | 	" $0 --option1 something-wrong" \
54 | 	" $0 --option1 123" \
55 | 	" Also try playing with other options, giving either good or bad values." \
56 | 	" Check the comments in this script for some more informations."
57 | 
58 | # Command line parsing is done here.
59 | argsparse_parse_options "$@"
60 | 
61 | printf "Options reporting:\n"
62 | # Simple reporting function.
63 | argsparse_report
64 | printf "End of argsparse report.\n\n"
65 | 


--------------------------------------------------------------------------------
/bash-argsparse.spec:
--------------------------------------------------------------------------------
 1 | Summary: An high level argument parsing library for bash
 2 | Name: bash-argsparse
 3 | Version: 1.8
 4 | Release: 1%{?dist}
 5 | License: WTFPL
 6 | URL: https://github.com/Anvil/bash-argsparse
 7 | Source0: http://argsparse.livna.org/%{name}-%{version}.tar.gz
 8 | BuildArch: noarch
 9 | # Binaries are required for unittest to perform cleanly.
10 | BuildRequires: doxygen glibc-common util-linux /usr/bin/host
11 | 
12 | Requires: bash >= 4.2
13 | Requires: util-linux glibc-common /usr/bin/host
14 | 
15 | %description
16 | An high level argument parsing library for bash.
17 | 
18 | The purpose is to replace the option-parsing and usage-describing
19 | functions commonly rewritten in all scripts.
20 | 
21 | This library is implemented for bash version 4. Prior versions of bash
22 | will fail at interpreting that code.
23 | 
24 | %prep
25 | %setup -q
26 | 
27 | %build
28 | # Nothing to build, except the documentation.
29 | doxygen
30 | 
31 | %install
32 | mkdir -p $RPM_BUILD_ROOT/%{_bindir}
33 | for file in argsparse argsparse-completion; do
34 |     install -m 0755 "$file.sh" $RPM_BUILD_ROOT/%{_bindir}
35 |     ln -s "$file".sh $RPM_BUILD_ROOT/%{_bindir}/"$file"
36 | 
37 | %check
38 | ./unittest
39 | 
40 | %files
41 | %doc tutorial README.md html COPYING
42 | %{_bindir}/argsparse*
43 | 
44 | 
45 | %changelog
46 | * Tue Sep  5 2017 Dams <bash-argsparse[AT]livna.org> - 1.8-1
47 | - Version 1.8
48 | 
49 | * Thu Mar 5 2015 Dams <bash-argsparse[AT]livna.org> - 1.7-1
50 | - Version 1.7
51 | 
52 | * Wed Jan 28 2015 Dams <bash-argsparse[AT]livna.org> - 1.6.2-1
53 | - Version 1.6.2
54 | - Dropped fedora patch (included upstream)
55 | 
56 | * Fri Oct 24 2014 Dams <bash-argsparse[AT]livna.org> - 1.6.1-3
57 | - Using package names instead of path for Requires/BuildRequires
58 | 
59 | * Wed Oct 15 2014 Dams <bash-argsparse[AT]livna.org> - 1.6.1-2
60 | - Added patch to fix some unittest issues
61 | 
62 | * Thu Oct 9 2014 Dams <bash-argsparse[AT]livna.org> - 1.6.1-1
63 | - Version 1.6.1
64 | - Fixed changelog names
65 | 
66 | * Thu Oct 9 2014 Dams <bash-argsparse[AT]livna.org> - 1.6-4
67 | - Update host path in *Requires tags.
68 | 
69 | * Wed Oct 8 2014 Dams <bash-argsparse[AT]livna.org> - 1.6-3
70 | - Added more BuildRequires to allow unittest script to run correctly
71 |   restricted small environments
72 | 
73 | * Mon Sep 15 2014 Dams <bash-argsparse[AT]livna.org> - 1.6-2
74 | - Fixed date in changelog entry
75 | 
76 | * Tue Aug 12 2014 Dams <bash-argsparse[AT]livna.org> - 1.6-1
77 | - License tag is now WTFPL
78 | - Removed trailing dot at the end of Summary
79 | - Removed BuildRoot tag
80 | - Requiring commands instead of packages
81 | 
82 | * Mon Jan 13 2014 Dams <bash-argsparse[AT]livna.org> - 1.6-0
83 | - Version 1.6
84 | - Added doxygen documentation
85 | - check section
86 | 
87 | * Thu Mar 21 2013 Dams <bash-argsparse[AT]livna.org> - 1.5-0
88 | - Version 1.5
89 | - Updated Requires
90 | - Removed old/fedora-obsolete directives/noise
91 | 
92 | * Thu Mar 14 2013 Dams <bash-argsparse[AT]livna.org> - 1.4-0
93 | - Initial build.
94 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | bash-argsparse
  2 | ==============
  3 | 
  4 | An high level argument parsing library for bash.
  5 | 
  6 | Inspired, by the python argparse module, bash-argsparse purpose is to
  7 | replace the option-parsing and usage-describing functions commonly
  8 | rewritten in all scripts.
  9 | 
 10 | This library is implemented for GNU bash version >= 4.2. Prior
 11 | versions of bash will fail at interpreting that code.
 12 | 
 13 | 
 14 | ### Online documentation
 15 | 
 16 | Doxygen documentation is available online
 17 | [here](http://argsparse.livna.org/doxygen/1.8/).
 18 | 
 19 | 
 20 | ### Tarballs
 21 | 
 22 | Though Bash Argsparse is hosted at
 23 | [github](https://github.com/Anvil/bash-argsparse), you can download
 24 | tarballs at the following URL:
 25 | [http://argsparse.livna.org/](http://argsparse.livna.org/)
 26 | 
 27 | ### RPMS
 28 | 
 29 | Though you can build your own package using the provided spec file, a
 30 | bash-argsparse package is currently available in fedora repositories,
 31 | for all releases from fedora 19 to rawhide. Ditto for RHEL/Centos 6 &
 32 | 7, through the EPEL repository.
 33 | 
 34 | ### Features
 35 | 
 36 | The argsparse library offers to script developpers the following features:
 37 | 
 38 | * Automatic help message generation
 39 | * Simple option declarations
 40 | * Different option types: simple, with value, with cumulative (uniq or
 41 |   not) values
 42 | * User-input checkings (either by type, enumerations or custom checking)
 43 | * Hook settings
 44 | * Option properties making them excluding each other, aliasing other
 45 |   options, or (sic) non-optional.
 46 | * Automatic bash completion generation.
 47 | 
 48 | 
 49 | ### Requirements, Bash settings
 50 | 
 51 | A basic argsparse run requires no external commands except the
 52 | quite-common "getopt" command. Some argsparse-built-in type checkings
 53 | may require some other (like "host" and "getent") but you do not have
 54 | to use those types.
 55 | 
 56 | Argsparse relies on a lot of bash built-in commands ("printf", "[",
 57 | "read", ...) and internal features such as arrays, associative arrays,
 58 | extended (ksh-like) globbing. That's why the "extglob" shell option is
 59 | automatically enabled and posix-mode is automatically disabled when
 60 | loading the argsparse library.
 61 | 
 62 | The code has been tested on bash 4.1, 4.2 and 4.3 and is definitely
 63 | not POSIX-compliant.
 64 | 
 65 | Compliance with the "nounset" and "failglob" bash settings is
 66 | supported.
 67 | 
 68 | Content
 69 | -------
 70 | 
 71 | * argsparse.sh: the library.
 72 | * tutorial: a bunch of small demonstration scripts for new users.
 73 | * bash-argsparse.spec: a spec file to build RPM packages.
 74 | * debian: the directory required to build deb packages.
 75 | * Doxyfile: doxygen configuration file.
 76 | * doxygen-bash.sed:
 77 |   [bash-doxygen](https://github.com/Anvil/bash-doxygen) doxygen input
 78 |   filter.
 79 | * unittest: a test script to validate most of argsparse features.
 80 | 
 81 | ### Testing
 82 | 
 83 | Here are the topics covered by scripts in tutorial directory:
 84 | * 0-completion: An automatic bash completion demo for all other
 85 |   tutorial scripts. This script will spawn a preconfigured interactive
 86 |   bash.
 87 | * 1-basics: Bash Argsparse basics
 88 | * 2-values: Options accepting values
 89 | * 3-cumulative-options: How to keep all user-given values
 90 | * 4-types: Type-checking
 91 | * 5-custom-types: User-defined types
 92 | * 6-properties: Option properties
 93 | * 7-value-checking: Advanced value checking using argsparse
 94 | * 8-setting-hook: Changing the way options are set
 95 | * 9-misc: Other misc argsparse features.
 96 | 
 97 | Invoke each script without parameter or with --help to obtain usage message.
 98 | 
 99 | Known limitations (or bugs)
100 | ---------------------------
101 | 
102 | * You cannot have a short option without a long option.
103 | * Too few verifications about property values are made.
104 | * Compliance with errexit is not supported (yet).
105 | * Compliance with Non-bind versions of the "host" command has not been
106 |   tested.
107 | 


--------------------------------------------------------------------------------
/doxygen-bash.sed:
--------------------------------------------------------------------------------
  1 | #!/bin/sed -nf
  2 | ##
  3 | ##             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
  4 | ##                     Version 2, December 2004
  5 | ##
  6 | ##  Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
  7 | ##
  8 | ##  Everyone is permitted to copy and distribute verbatim or modified
  9 | ##  copies of this license document, and changing it is allowed as long
 10 | ##  as the name is changed.
 11 | ##
 12 | ##             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
 13 | ##    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 14 | ##
 15 | ##   0. You just DO WHAT THE FUCK YOU WANT TO.
 16 | ##
 17 | ##
 18 | ## Project Home Page: http://github.com/Anvil/bash-doxygen/
 19 | ## Project Author: Damien Nadé <github@livna.org>
 20 | ##
 21 | 
 22 | /^## \+@fn/{
 23 |     :step
 24 |     /@param [^ ]\+ .*$/{
 25 |         # Groups are
 26 |         # \1: @fn <funcname>
 27 |         # \2: already identified params
 28 |         # \3: previous doc string
 29 |         # \4: @param<space>
 30 |         # \5: newly identified param name plus optional dot-dot-dot string
 31 |         # \6: optional dot-dot-dot string
 32 |         # \7: everything after \5 to end of line
 33 |         # Here, we-reinsert param names into the <funcname>()
 34 |         s/\(@fn [^(\n]\+\)(\([^(]*\))\(.*\)\(@param \)\([^ \n]\+\(\.\.\.\)\?\)\([^\n]*\)$/\1(\2, \5)\3\4\5\7/
 35 |     }
 36 |     / *\(function \+\)\?[a-z:.A-Z0-9_]\+ *() *{ *$/!{
 37 |         N
 38 |         b step
 39 |     }
 40 |     # Remove optional 'function' keyword (and some extra spaces).
 41 |     s/ *\(function \+\)\?\([a-z:.A-Z0-9_]\+ *() *{\) *$/\2/
 42 |     # Here, we should have @fn (, param1, param2, param3), we remove
 43 |     # the first extra ", ".
 44 |     s/\(@fn[^(]\+\)(, /\1(/
 45 |     # Remove the function body to avoid interference, and re-introduce
 46 |     # list of parameters in the funcname(<here>).
 47 |     s/\(@fn \([^(]\+\)(\)\([^)]*\)\().*\)\n\2() *{/\1\3\4\n\2(\3) { }/
 48 |     # Replace all '## ' by '//! ' at beginning-of-line.
 49 |     s/\(^\|\n\)##\n/\1\/\/!\n/g
 50 |     s/\(^\|\n\)## /\1\/\/! /g
 51 |     p
 52 |     b end
 53 | }
 54 | 
 55 | /^declare /{
 56 |     # The principle is quite easy. For every declare option, we add a
 57 |     # keyword into the sed exchange buffer. Once everything is parsed,
 58 |     # we add the variable identifier and maybe the variable default
 59 |     # value, add that to the exchange buffer and print the result.
 60 | 
 61 |     # Reset exchange buffer
 62 |     x
 63 |     s/.*//
 64 |     x
 65 |     # Remove declare keyword, we wont need it anymore
 66 |     s/^declare \+//
 67 |     # Simple declaration case.
 68 |     /^[^-]/{
 69 |         x
 70 |         s/.*/&String /
 71 |         x
 72 |         b declareprint
 73 |     }
 74 |     # Concat options. Some of them are ignored, such as -f.
 75 |     :declare
 76 |     s/^-\([aAilrtux]\+\) \+-\([aAilrtux]\+\) \+/-\1\2 /
 77 |     t declare
 78 | 
 79 |     # Prepend Exported and ReadOnly attributes
 80 |     /^-[aAiltur]*x/{
 81 |         x
 82 |         s/.*/&Exported /
 83 |         x
 84 |     }
 85 |     /^-[aAiltux]*r/{
 86 |         x
 87 |         s/.*/&ReadOnly /
 88 |         x
 89 |     }
 90 | 
 91 |     # Integer type, exclusive with default 'String' type.
 92 |     /^-[aAlturx]*i/{
 93 |         x
 94 |         s/.*/&Integer /
 95 |         x
 96 |         b array
 97 |     }
 98 | 
 99 |     # String type. handling.
100 |     /^-[aAtrx]*l/{
101 |         x
102 |         s/.*/&LowerCase /
103 |         x
104 |     }
105 |     /^-[aAtrx]*u/{
106 |         x
107 |         s/.*/&UpperCase /
108 |         x
109 |     }
110 |     x
111 |     s/.*/&String /
112 |     x
113 | 
114 |     : array
115 |     # For arrays, we remove the initialisation since I dont know yet
116 |     # how to print it for doxygen to understand.
117 |     /^-[Ailturx]*a/{
118 |         x
119 |         s/.*/&Array /
120 |         x
121 |         b deletevalue
122 |     }
123 |     /^-[ailturx]*A/{
124 |         x
125 |         s/.*/&AssociativeArray /
126 |         x
127 |         b deletevalue
128 |     }
129 | 
130 |     :declareprint
131 |     # Remove the declare option, x, then G will concat the exchange
132 |     # buffer (the 'type' string) and the regular buffer (the var
133 |     # possibly followed by an init value). The rest is quite easy to
134 |     # understand.
135 |     s/-[^ ]\+ \+//
136 |     x
137 |     G
138 |     s/\n//
139 |     s/=/ = /
140 |     s/$/;/
141 |     p
142 |     x
143 |     b end
144 | }
145 | 
146 | /^ *export \+[_a-zA-Z]/{
147 |     s/=/ = /
148 |     s/\([^;]\) *$/\1;/
149 |     s/^ *export \+/Exported String /
150 |     p
151 |     b end
152 | }
153 | 
154 | 
155 | # Delete non doxygen-related lines content, but not the line
156 | # themselves.
157 | /^## \|^##$/!{
158 |      s/^.*$//p
159 | }
160 | b end
161 | 
162 | # For arrays, to avoid duplication.
163 | : deletevalue
164 | s/\(-[^ ]\+ \+[^=]\+\)=.*/\1/
165 | b declareprint
166 | 
167 | :end
168 | # Make all ## lines doxygen-able.
169 | s/^##\( \|$\)/\/\/!\1/p
170 | 


--------------------------------------------------------------------------------
/argsparse-completion.sh:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env bash
  2 | # -*- tab-width: 4; encoding: utf-8; -*-
  3 | #
  4 | #########
  5 | # License:
  6 | #
  7 | #             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
  8 | #                    Version 2, December 2004
  9 | #
 10 | # Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
 11 | #
 12 | # Everyone is permitted to copy and distribute verbatim or modified
 13 | # copies of this license document, and changing it is allowed as long
 14 | # as the name is changed.
 15 | #
 16 | #            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
 17 | #   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 18 | #
 19 | #  0. You just DO WHAT THE FUCK YOU WANT TO.
 20 | #
 21 | #########
 22 | #
 23 | ## @file
 24 | ## @author Damien Nadé <bash-argsparse@livna.org>
 25 | ## @brief Bash completion for scripts using argsparse library.
 26 | ## @copyright WTFPLv2
 27 | ## @version 1.8
 28 | ## @details
 29 | ## @par URL
 30 | ## https://github.com/Anvil/bash-argsparse @n
 31 | ##
 32 | ## @par Purpose
 33 | ##
 34 | ## To automatically enable, for bash-completion users, completion for
 35 | ## scripts that use the argsparse library.
 36 | ##
 37 | ## @par Usage
 38 | ##
 39 | ## In your ~/.bashrc, add the following lines to enable completion for
 40 | ## all your argsparse-written scripts:
 41 | ##
 42 | ## @code
 43 | ##     . argsparse-completion.sh
 44 | ##     complete -F _argsparse_complete [ your scripts names ... ]
 45 | ## @endcode
 46 | ##
 47 | ## @par Required configuration
 48 | ##
 49 | ## argsparse-completion relies on a few shell settings:
 50 | ##
 51 | ## @li "sourcepath" shell option must be enabled. This should be
 52 | ##   enabled by default, but you can enforce it by running:
 53 | ##
 54 | ## @code
 55 | ##   shopt -s sourcepath
 56 | ## @endcode
 57 | ##
 58 | ## If correctly enabled, the following command below should return
 59 | ## this output.
 60 | ##
 61 | ## @code
 62 | ##   $ shopt sourcepath
 63 | ##   sourcepath      on
 64 | ## @endcode
 65 | ##
 66 | ## @par Limitations
 67 | ##
 68 | ## @li Every time the completion is invoked, the completed script will
 69 | ##   be sourced, up to either the argsparse_parse_options() function
 70 | ##   call or any the first return top-level statement. This means that
 71 | ##   up to this point the script should not have any side effect (like
 72 | ##   file system alteration, network connections, ...), and should
 73 | ##   avoid time-consuming tasks up to this point.
 74 | ##
 75 | ## @li Only a limited set of option types completion are currently
 76 | ##   implemented.
 77 | ##
 78 | ##
 79 | ##
 80 | ## @defgroup ArgsparseCompletion Bash Completion-related functions.
 81 | 
 82 | ## @fn __argsparse_compgen()
 83 | ## @private
 84 | ## @brief A compgen wrapper.
 85 | ## @details This function will just call compgen with given argument,
 86 | ## safely adding $cur in the command line. Also if compgen_prefix is
 87 | ## set, a -P option will be provided to compgen.
 88 | ## @note __argsparse_compgen() makes use of the bash-completion
 89 | ## standard variables.
 90 | ## @param param... any set of compgen options
 91 | ## @return compgen output and return code.
 92 | ## @ingroup ArgsparseCompletion
 93 | __argsparse_compgen() {
 94 | 	if [[ -v compgen_prefix ]]
 95 | 	then
 96 | 		set -- "$@" -P "$compgen_prefix"
 97 | 	fi
 98 | 	compgen "$@" -- "$cur"
 99 | }
100 | 
101 | ## @fn __argsparse_complete_value()
102 | ## @brief Complete the value an option.
103 | ## @details Run compgen with values matching given option. If an array
104 | ## "option_<optionname>_values" exists, complete with its values. Else
105 | ## if option has a type, complete values according to type when
106 | ## possible. Else do nothing.
107 | ## @note __argsparse_complete_value() makes use of the bash-completion
108 | ## standard variables.
109 | ## @param option a long option name.
110 | ## @ingroup ArgsparseCompletion
111 | __argsparse_complete_value() {
112 | 	[[ $# -eq 1 ]] || return 1
113 | 	local option=$1
114 | 	local array option_type
115 | 	local -a values
116 | 	if array=$(__argsparse_values_array_identifier "$option")
117 | 	then
118 | 		# Option accepts an enumeration of values.
119 | 		values=( "${!array}" )
120 | 		__argsparse_compgen -W "${values[*]}"
121 | 	elif option_type=$(argsparse_has_option_property "$option" type)
122 | 	then
123 | 		case "$option_type" in
124 | 			file|pipe|socket|link)
125 | 				__argsparse_compgen -A file
126 | 				;;
127 | 			directory|group)
128 | 				__argsparse_compgen -A "$option_type"
129 | 				;;
130 | 			username)
131 | 				__argsparse_compgen -A user
132 | 				;;
133 | 			host|hostname)
134 | 				__argsparse_compgen -A hostname
135 | 				;;
136 | 			hexa)
137 | 				values=( "$cur"{a..f} )
138 | 				;;&
139 | 			int|hexa)
140 | 				values+=( "$cur"{0..9} )
141 | 				__argsparse_compgen -W "${values[*]}"
142 | 				;;
143 | 		esac
144 | 	fi
145 | }
146 | 
147 | ## @fn __argsparse_complete_get_long()
148 | ## @brief Find the option we want to complete.
149 | ## @details If given word parameter is a recognized option, print the
150 | ## matching long option name. Also if "$cur" should be this option
151 | ## value, then return 0.
152 | ## @param word any word.
153 | ## @param long... a list of long options.
154 | ## @return the long option matching given parameter.
155 | ## @retval 0 if given word matches an option and if that option
156 | ## accepts a value.
157 | ## @private
158 | ## @ingroup ArgsparseCompletion
159 | __argsparse_complete_get_long() {
160 | 	[[ $# -ge 1 ]] || return 1
161 | 	local word=$1
162 | 	shift
163 | 	local -a longs=( "$@" )
164 | 	local long
165 | 	if [[ $word = -[!-] ]]
166 | 	then
167 | 		long=$(argsparse_short_to_long "${word#-}") || return
168 | 	elif __argsparse_index_of "$word" "${longs[@]}" >/dev/null
169 | 	then
170 | 		long=${word#--}
171 | 	else
172 | 		# Unknown option
173 | 		return 1
174 | 	fi
175 | 	printf %s "$long"
176 | 	argsparse_has_option_property "$long" value
177 | }
178 | 
179 | ## @fn __argsparse_complete()
180 | ## @brief Completion for the command stored in ${words[0]}.
181 | ## @details Will load the script to complete, and invoke compgen
182 | ## according to context.
183 | ## @retval non-zero if completed command cannot be sourced.
184 | ## @ingroup ArgsparseCompletion
185 | __argsparse_complete() {
186 | 	local script=${words[0]}
187 | 	(
188 | 		set +o posix
189 | 		ARGSPARSE_COMPLETION_MODE=1
190 | 		shopt -s expand_aliases
191 | 		unalias -a
192 | 		. "$script" 2>/dev/null || return
193 | 		longs=( "${!__argsparse_options_descriptions[@]}" )
194 | 		longs=( "${longs[@]/#/--}" )
195 | 		option=${prev#--}
196 | 		if __argsparse_index_of -- "${words[@]:0:${#words[@]}-1}" >/dev/null
197 | 		then
198 | 			# We're after the -- parameter, complete positionnal arguments
199 | 			__argsparse_compgen -A file
200 | 		elif long=$(__argsparse_complete_get_long "$prev" "${longs[@]}")
201 | 		then
202 | 			# We're right after an option that accepts a value, so
203 | 			# complete a value.
204 | 			__argsparse_complete_value "$long"
205 | 		else
206 | 			# Complete current token
207 | 			case "$cur" in
208 | 				--?*=*|-[!-]?*)
209 | 					# Complete the --foo=something pattern as if
210 | 					# prev=--foo and cur=something
211 | 					# Complete -fsomething as if prev=-f and cur=something
212 | 					if [[ "$cur" =~ ^((--[^=]+)=)(.*)$ ||
213 | 						"$cur" =~ ^((-[^-]))(.*)$ ]]
214 | 					then
215 | 						compgen_prefix=${BASH_REMATCH[1]}
216 | 						option=${BASH_REMATCH[2]}
217 | 						cur=${BASH_REMATCH[3]}
218 | 						long=$(__argsparse_complete_get_long \
219 | 								"$option" "${longs[@]}") && \
220 | 							__argsparse_complete_value "$long"
221 | 					fi
222 | 					;;
223 | 				""|-)
224 | 					shorts=( "${!__argsparse_short_options[@]}" )
225 | 					shorts=( "${shorts[@]/#/-}" )
226 | 					;;&
227 | 				""|-*)
228 | 					__argsparse_compgen -W "${shorts[*]} ${longs[*]}"
229 | 					;;
230 | 				*)
231 | 					# Default non-option completion.
232 | 					__argsparse_compgen -A file
233 | 					;;
234 | 			esac
235 | 		fi
236 | 	)
237 | }
238 | 
239 | ## @fn _argsparse_complete()
240 | ## @brief The argsparse completion function.
241 | ## @details To enable completion on a script that uses the argsparse
242 | ## library, call the "complete" built-in as following: @n
243 | ## @code
244 | ##     complete -F _argsparse_complete <your script>
245 | ## @endcode
246 | ## @note Technically, this function gets a parameter (the name of the
247 | ## command to complete), but it is ignored.
248 | ## @ingroup ArgsparseCompletion
249 | _argsparse_complete() {
250 | 	local cur prev words cword split
251 | 	_init_completion -s || return
252 | 	COMPREPLY=(	$(__argsparse_complete) )
253 | }
254 | 


--------------------------------------------------------------------------------
/unittest:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env bash
  2 | # -*- tab-width: 4; encoding: utf-8 -*-
  3 | #
  4 | #
  5 | #
  6 | 
  7 | PS4='+ ${FUNCNAME:-main}${LINENO:+:$LINENO}>'
  8 | 
  9 | # If it works with failglob and nounset, it will work without.
 10 | shopt -s failglob
 11 | set -o nounset
 12 | 
 13 | . ./argsparse.sh
 14 | 
 15 | shopt -s extdebug
 16 | errors=0
 17 | disabled=0
 18 | 
 19 | rm -f unittest.log unittest.env.log
 20 | 
 21 | err_trap() {
 22 | 	: $((errors+=1))
 23 | 	return 1
 24 | }
 25 | 
 26 | trap err_trap ERR
 27 | 
 28 | print_exit_status() {
 29 |     # Prints [OK] at the end of the screen of first argument is 0,
 30 |     # else [FAILURE].
 31 |     # 1st Parameter: a number, usually the exit status of your
 32 |     # previous command. If omitted, will use $?.
 33 |     # returns the first parameter value
 34 |     local ret="${1:-$?}"
 35 |     # If you want you can override the FAILED and OK messages by
 36 |     # pre-defining those variables.
 37 |     local FAILED=${FAILED:-FAILED}
 38 |     local OK=${OK:-OK}
 39 |     # Move to column default is 70
 40 |     local COL=${COL:=70}
 41 |     [[ -t 1 ]] && echo -en "\033[${COL}G"
 42 |     # Colors
 43 |     if [[ -t 1 ]]
 44 |     then
 45 |         local COLOR_SUCCESS=${COLOR_SUCCESS:-'\033[1;32m'}
 46 |         local COLOR_FAILURE=${COLOR_FAILURE:-'\033[1;31m'}
 47 |         local COLOR_WARNING='\033[1;33m' COLOR_NORMAL='\033[0;39m'
 48 |     else
 49 |         local COLOR_SUCCESS= COLOR_FAILURE= COLOR_WARNING= COLOR_NORMAL=
 50 |     fi
 51 |     [[ "$ret" -eq 0 ]] && echo -e "[$COLOR_SUCCESS$OK$COLOR_NORMAL]" || \
 52 | 		echo -e "[$COLOR_FAILURE$FAILED$COLOR_NORMAL]"
 53 |     return $ret
 54 | }
 55 | 
 56 | echo_for_print_status() {
 57 |     local m=$1
 58 |     if tty >/dev/null 2>&1 && [[ -n "${PRINT_STATUS_COLOR:-}" ]]
 59 |     then
 60 |         m="$(tput setaf $PRINT_STATUS_COLOR)$m$(tput sgr0)"
 61 |     fi
 62 |     printf "%s: " "$m"
 63 | }
 64 | 
 65 | exec_and_print_status() {
 66 |     # prints a message, execute a command and print its exit status
 67 |     # using print_exit_status function.
 68 |     # 1st Parameter: a message
 69 |     # all other parameter: the command to execute
 70 |     # returns the exit status code of the command
 71 |     [[ $# -lt 2 ]] && return 1
 72 |     local m=$1 ; shift
 73 |     PRINT_STATUS_COLOR="${PRINT_STATUS_COLOR-}" \
 74 | 		echo_for_print_status "$m"
 75 |     "$@"
 76 |     print_exit_status $?
 77 | }
 78 | 
 79 | default_test() {
 80 | 	[[ $? -eq 0 ]]
 81 | }
 82 | 
 83 | failure() {
 84 | 	[[ $? -ne 0 ]]
 85 | }
 86 | 
 87 | shell_env() {
 88 | 	# Greps are:
 89 | 	# * variables automatically altered by bash itself.
 90 | 	# * local environment variables, used by the environment checking routines.
 91 | 	# * argsparse private variables, subjects to modifications/deletion.
 92 | 	# * argsparse public variables.
 93 | 	# * argsparse results, which are expected to change.
 94 | 	set | \
 95 | 		grep -vE '^(FIRST|SECOND|SHELLOPTS|FUNCNAME|_|LINENO|BASH_(ARG[CV]|LINENO|SOURCE|REMATCH)|PIPESTATUS)=' | \
 96 | 		grep -vE '^before=' | \
 97 | 		grep -vE '^__argsparse_(options_descriptions|short_options|tmp_identifiers)=' | \
 98 | 		grep -vE '^argsparse_usage_description=' | \
 99 | 		grep -vE '^(program_(params|options))|cumulated_values_[0-9a-zA-Z_]+='
100 | 	shopt
101 | 	set -o | grep -v xtrace
102 | }
103 | 
104 | check_env() {
105 | 	{
106 | 		printf "For test: %s\n" "$message"
107 | 		diff -u <(echo "$before") <(shell_env)
108 | 	} >> unittest.env.log
109 | }
110 | 
111 | parse_option_wrapper() {
112 | 	local message=$1
113 | 	local TEST=${TEST:-default_test}
114 | 	shift
115 | 	local before=$(shell_env)
116 | 	echo_for_print_status "Checking $message"
117 | 	(
118 | 		printf "Test is: %s\n" "$message"
119 | 		printf "Validation is: %s\n" "$TEST"
120 | 		set -x
121 | 		(
122 | 			trap check_env EXIT
123 | 			argsparse_parse_options "$@"
124 | 			${INNERTEST:-exit $?}
125 | 		)
126 | 	) >>unittest.log 2>&1
127 | 	$TEST
128 | 	print_exit_status || exit
129 | }
130 | 
131 | (
132 | 	argsparse_usage_description="Usage has been triggered"
133 | 	echo_for_print_status "Checking no parameter triggers usage"
134 | 	( 
135 | 		argsparse_parse_options
136 | 	) | grep -q "$argsparse_usage_description"
137 | 	[ ${PIPESTATUS[0]} -ne 0 -a ${PIPESTATUS[1]} -eq 0 ]
138 | 	print_exit_status 
139 | )
140 | 
141 | (
142 | 	argsparse_allow_no_argument yes
143 | 	argsparse_use_option option ""
144 | 	parse_option_wrapper "argsparse_allow_no_argument yes"
145 | )
146 | 
147 | (
148 | 	argsparse_usage_description="Usage has been triggered"
149 | 	echo_for_print_status "Checking dummy option triggers usage"
150 | 	( 
151 | 		argsparse_parse_options --dumb 2>/dev/null
152 | 	) | grep -q "$argsparse_usage_description"
153 | 	[ ${PIPESTATUS[0]} -ne 0 -a ${PIPESTATUS[1]} -eq 0 ]
154 | 	print_exit_status 
155 | )
156 | 
157 | (
158 | 	argsparse_use_option first-option "first option description"
159 | 	echo_for_print_status "Checking if option description appear in usage"
160 | 	(
161 | 		argsparse_parse_options -h
162 | 	) | grep -q "first option description"
163 | 	print_exit_status
164 | )
165 | 
166 | (
167 | 	argsparse_use_option shortcut ""
168 | 	parse_option_wrapper "option detection" --shortcut
169 | 
170 | 	argsparse_set_option_property short:S shortcut
171 | 	parse_option_wrapper "short property" -S
172 | )
173 | 
174 | (
175 | 	argsparse_use_option =shortcut ""
176 | 	parse_option_wrapper "= in optstring" -s
177 | )
178 | 
179 | (
180 | 	argsparse_use_option option1 "" type:weird:value
181 | 	echo_for_print_status "Checking 'weird:value' property value"
182 | 	[[ $(argsparse_has_option_property option1 type) = 'weird:value' ]]
183 | 	print_exit_status
184 | )
185 | 
186 | (
187 | 	argsparse_use_option option1 ""
188 | 	for weirdo in '?' , '*' '!'
189 | 	do
190 | 		(
191 | 			echo_for_print_status "Checking forbidden '$weirdo' property value"
192 | 			argsparse_set_option_property type:"foo${weirdo}bar" option1 2>/dev/null
193 | 			failure
194 | 			print_exit_status
195 | 		)
196 | 	done
197 | )
198 | 
199 | value_check_test() {
200 | 	[[ ${program_options[$value_check_option]} = $value_check_value ]]
201 | }
202 | 
203 | value_check() {
204 | 	local value_check_option=$1
205 | 	local value_check_value=$2
206 | 	shift 2
207 | 	INNERTEST=value_check_test parse_option_wrapper "$@"
208 | }
209 | 
210 | (
211 | 	argsparse_use_option value ""
212 | 	argsparse_set_option_property value value
213 | 	TEST=failure parse_option_wrapper "if value property expects value" --value
214 | 	value_check value 1 "if value is correctly detected" --value 1
215 | )
216 | 
217 | (
218 | 	argsparse_use_option value: ""
219 | 	value_check value 1 "if value is correctly detected with optstring" --value 1
220 | 	TEST=failure parse_option_wrapper "if value property expects value if set with optstring" --value
221 | )	
222 | 
223 | (
224 | 	argsparse_use_option option1 ""
225 | 	argsparse_use_option option2 "" mandatory
226 | 	TEST=failure parse_option_wrapper "if missing mandatory option triggers error" --option1
227 | 	parse_option_wrapper "if mandatory option makes return code 0" --option1 --option2
228 | 	argsparse_use_option option3 "" mandatory
229 | 	TEST=failure parse_option_wrapper "if missing mandatory options trigger error (1)" --option1
230 | 	TEST=failure parse_option_wrapper "if missing mandatory options trigger error (2)" --option1 --option2
231 | 	TEST=failure parse_option_wrapper "if missing mandatory options trigger error (3)" --option1 --option3
232 | 	parse_option_wrapper "if missing mandatory options trigger error (4)" --option3 --option2
233 | )
234 | 
235 | cumul_test() {
236 | 	[[ $? -ne 0 ]] && return 1
237 | 	local cumul="cumulated_values_$option[@]"
238 | 	# Shoud never trigger nounset
239 | 	local -a array=( "${!cumul}" )
240 | 	local i
241 | 	[[ ${#array[@]} -eq "${#cumul_array[@]}" ]] || return 1
242 | 	for ((i=0 ; i < ${#array[@]} ; i++))
243 | 	do
244 | 		[[ ${array[$i]} = "${cumul_array[$i]}" ]] || return 1
245 | 	done
246 | 	return 0
247 | }
248 | 
249 | (
250 | 	argsparse_use_option option1 "" cumulative
251 | 	option=option1
252 | 	cumul_array=(1 2 1 2)
253 | 	INNERTEST=cumul_test parse_option_wrapper "cumulative property behaviour" "${cumul_array[@]/#/--option1=}"
254 | )
255 | 
256 | (
257 | 	option=option2
258 | 	cumul_array=(1 2)
259 | 	argsparse_use_option option2 "" cumulativeset
260 | 	INNERTEST=cumul_test parse_option_wrapper "cumulativeset property behaviour" "${cumul_array[@]/#/--option2=}" "${cumul_array[@]/#/--option2=}"
261 | )
262 | 
263 | (
264 | 	argsparse_use_option option1 ""
265 | 	argsparse_use_option option2 "" alias:option1
266 | 	value_check option1 1 "simple alias" --option1
267 | 	argsparse_use_option option3 "" alias:option2
268 | 	value_check option1 1 "recursive alias" --option1
269 | )
270 | 
271 | (
272 | 	argsparse_use_option option1 ""
273 | 	argsparse_use_option option2 "" require:option1
274 | 	parse_option_wrapper "simple require (1)" --option2 --option1
275 | 	TEST=failure parse_option_wrapper "simple require (2)" --option2
276 | 	argsparse_use_option option3 "" require:option2
277 | 	TEST=failure parse_option_wrapper "recursive require (1)" --option3
278 | 	TEST=failure parse_option_wrapper "recursive require (2)" --option3 --option2
279 | 	parse_option_wrapper "recursive require (3)" --option3 --option2 --option1
280 | )
281 | 
282 | (
283 | 	argsparse_use_option option1 ""
284 | 	argsparse_use_option option2 "" exclude:option1
285 | 	TEST=failure parse_option_wrapper "exclusion" --option2 --option1
286 | )
287 | 
288 | (
289 | 	argsparse_use_option option1 ""
290 | 	argsparse_use_option option2 "" default:1 exclude:option1
291 | 	parse_option_wrapper "exclusion does not prevent default values" --option1
292 | )
293 | 
294 | (
295 | 	argsparse_use_option option1 ""
296 | 	argsparse_use_option option2 ""
297 | 	argsparse_use_option option3 "" require:"option1 option2"
298 | 	TEST=failure parse_option_wrapper "multiple require (1)" --option3
299 | 	TEST=failure parse_option_wrapper "multiple require (2)" --option3 --option2
300 | 	TEST=failure parse_option_wrapper "multiple require (3)" --option3 --option1
301 | 	parse_option_wrapper "multiple require (4)" --option3 --option2 --option1
302 | )
303 | 
304 | 
305 | (
306 | 	declare -a option_option1_values=(accept)
307 | 	argsparse_use_option option1: ""
308 | 	TEST=failure parse_option_wrapper "accepted values (bad value)" \
309 | 		--option1 foo
310 | 	parse_option_wrapper "accepted values (good value)" --option1 accept
311 | )
312 | 
313 | dir=$(mktemp -d)
314 | file=$(mktemp --tmpdir="$dir")
315 | declare -A types=(
316 | 	[link]="$dir/link1 $dir/link2"
317 | 	[file]="$file $dir/link1"
318 | 	[directory]=". .. $dir $dir/linkdir"
319 | 	[char]="c . 0 @"
320 | 	[unsignedint]=123
321 | 	[int]="1 123 0 -1 -938945349"
322 | 	[hexa]="0x123abc 71234 abc"
323 | 	[ipv4]="192.168.40.254 127.0.0.1 1.2.3.4"
324 | 	[ipv6]="2001:7a8:b018::1 ::1 2001:7a8:b018:0:21f:c6ff:fe59:71fd"
325 | 	[username]=$(whoami)
326 | 	[group]=$(id -gn)
327 | 	[port]="ssh 80"
328 | 	[portnumber]=1234
329 | )
330 | 
331 | fifo="$dir/fifo"
332 | if mkfifo "$fifo"
333 | then
334 | 	types[pipe]=$fifo
335 | else
336 | 	printf "Could not create persistent fifo. Disabling pipe type test.\n"
337 | 	: $((disabled++))
338 | fi
339 | 
340 | for socket in /dev/log
341 | do
342 | 	[[ -S $socket ]] || continue
343 | 	types[socket]=$socket
344 | done
345 | 
346 | # Look for a terminal
347 | for stdfd in 0
348 | do
349 | 	[[ -t $stdfd ]] || continue
350 | 	types[terminal]=$stdfd
351 | done
352 | 
353 | for t in terminal socket
354 | do
355 | 	if [[ ${types[$t]-unset} = unset ]]
356 | 	then
357 | 		: $((disabled++))
358 | 		printf "No %s found: won't test.\n" "$t"
359 | 	fi
360 | done
361 | 
362 | # Default 'host' type test case:
363 | types[host]="${types[ipv4]} ${types[ipv6]}"
364 | # Test hostnames only if we can actually resolv.
365 | if host localhost >/dev/null 2>&1
366 | then
367 | 	types[hostname]="livna.org localhost"
368 | 	types[host]+=" ${types[hostname]}"
369 | else
370 | 	printf "Cannot resolv localhost. Not testing hostname type.\n"
371 | 	: $((disabled++))
372 | fi
373 | 
374 | (cd "$dir" && ln -s "$file" link1 && ln -s asdf link2 && ln -s . linkdir)
375 | 
376 | for type in "${!types[@]}"
377 | do
378 | 	(
379 | 		argsparse_use_option option: "" "type:$type"
380 | 		# Left unquoted on purpose. There's no funny chars in this array.
381 | 		i=1
382 | 		for value in ${types[$type]}
383 | 		do
384 | 			parse_option_wrapper "type '$type' ($i)" --option "$value"
385 | 			: $((i++))
386 | 		done
387 | 	)
388 | done
389 | 
390 | declare -A bad_types=(
391 | 	[file]=". .. $dir $fifo"
392 | 	[directory]="${types[file]} $fifo $dir/link1"
393 | 	[pipe]="${types[file]} ${types[dir]-}"
394 | 	[socket]="${types[file]} $fifo $dir/link1"
395 | 	[link]="$file $fifo"
396 | 	[char]="12 abc"
397 | 	[unsignedint]="-1 -2234958 abc"
398 | 	[int]="a b casdf"
399 | 	[ipv4]="${types[ipv6]}"
400 | 	[ipv6]="${types[ipv4]}"
401 | 	[host]="livna.org1"
402 | 	[username]="asdkfjasdkfanfk1234"
403 | 	[group]="asdkfjasdkfanfk1234"
404 | 	[port]="12345678 foobar"
405 | 	[portnumber]=12345678
406 | 	[hostname]="livna.org1 google.com1"
407 | )
408 | 
409 | for type in "${!bad_types[@]}"
410 | do
411 | 	(
412 | 		argsparse_use_option option: "" "type:$type"
413 | 		# Left unquoted on purpose. (again)
414 | 		i=1
415 | 		for value in ${bad_types[$type]}
416 | 		do
417 | 			TEST=failure parse_option_wrapper "failure with type '$type' ($i)" --option "$value"
418 | 			: $((i++))
419 | 		done
420 | 	)
421 | done
422 | 
423 | (
424 | 	argsparse_use_option option: "" "type:terminal"
425 | 	TEST=failure parse_option_wrapper "failure with type 'terminal' (1)" --option 0 </dev/null
426 | )
427 | rm -Rf "$dir"
428 | 
429 | (
430 | 	check_option_type_unittest() {
431 | 		local value=$1
432 | 		[[ $value = 1 ]]
433 | 	}
434 | 	argsparse_use_option option: "" type:unittest
435 | 	parse_option_wrapper "custom type (1)" --option 1
436 | 	TEST=failure parse_option_wrapper "custom type (2)" --option asdf
437 | )
438 | 
439 | printf "Tests report:\n"
440 | if [[ $disabled -ne 0 ]]
441 | then
442 | 	printf "* %d test(s) disabled.\n" "$disabled"
443 | fi
444 | 
445 | if [[ $errors -ne 0 ]]
446 | then
447 | 	printf "* %d error(s) encountered. (See above)\n" "$errors"
448 | 	exit_code=1
449 | else
450 | 	printf "All tests passed.\n"
451 | 	exit_code=0
452 | fi
453 | 
454 | printf "Environment alteration detected:\n"
455 | if grep -v -B 1 '^For test:' unittest.env.log
456 | then
457 | 	: exit_code $((exit_code))
458 | else
459 | 	printf "None.\n"
460 | fi
461 | 
462 | if [[ $exit_code -ne 0 ]]
463 | then
464 | 	printf "Runtime environment was:\n"
465 | 	set -x
466 | 	{
467 | 		command -v bash
468 | 		bash --version
469 | 		shopt
470 | 		set -o
471 | 	} 2>&1
472 | fi
473 | 
474 | printf "Completed in %d seconds.\n" "$SECONDS"
475 | 
476 | exit "$exit_code"
477 | 


--------------------------------------------------------------------------------
/argsparse.sh:
--------------------------------------------------------------------------------
   1 | #!/usr/bin/env bash
   2 | # -*- tab-width: 4; encoding: utf-8; -*-
   3 | #
   4 | #########
   5 | # License:
   6 | #
   7 | #             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
   8 | #                    Version 2, December 2004
   9 | #
  10 | # Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
  11 | #
  12 | # Everyone is permitted to copy and distribute verbatim or modified
  13 | # copies of this license document, and changing it is allowed as long
  14 | # as the name is changed.
  15 | #
  16 | #            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
  17 | #   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  18 | #
  19 | #  0. You just DO WHAT THE FUCK YOU WANT TO.
  20 | #
  21 | #########
  22 | #
  23 | ## @file
  24 | ## @author Damien Nadé <bash-argsparse@livna.org>
  25 | ## @copyright WTFPLv2
  26 | ## @version 1.8
  27 | ## @brief Bash Argsparse Library
  28 | ## @details
  29 | ## @par URL
  30 | ## https://github.com/Anvil/bash-argsparse @n
  31 | ##
  32 | ## @par Purpose
  33 | ##
  34 | ## To replace the option-parsing and usage-describing functions
  35 | ## commonly rewritten in all scripts.
  36 | ##
  37 | ## @note
  38 | ## This library is implemented for bash version 4. Prior versions of
  39 | ## bash will fail at interpreting that code.
  40 | ## @note
  41 | ## The extglob shell option will be enabled and posix mode will be
  42 | ## disabled when loading the library. Changing those settings
  43 | ## afterwards will make the library execution fail.
  44 | ##
  45 | ## @par Usage
  46 | ## Use the argsparse_use_option() function to declare your options with
  47 | ## their single letter counterparts, along with their description.
  48 | ##
  49 | ## @par
  50 | ## The argsparse_use_option() syntax is:
  51 | ##
  52 | ## @code
  53 | ##     argsparse_use_option "optstring" "option description string" \
  54 | ##     [ "property" ... ] [ "optional default value" ]
  55 | ## @endcode
  56 | ##
  57 | ##
  58 | ## @par
  59 | ## An "optstring" is of the form "som=estring:". This would declare a
  60 | ## long option named somestring. The ending ":" is optional and, if
  61 | ## present, means the long option expects a value on the command
  62 | ## line. The "=" char is also optional and means the immediatly
  63 | ## following letter is the short single-letter equivalent option of
  64 | ## --something.
  65 | ##
  66 | ## @par
  67 | ## The "something" string must only contains ASCII
  68 | ## letters/numbers/dash/underscore characters.
  69 | ##
  70 | ## @note
  71 | ## What is referred later as "option" or "option name" (or even "long
  72 | ## option name") is the optstring without the ':' and '=' characters.
  73 | ##
  74 | ##
  75 | ##
  76 | ## @par Options may have properties.
  77 | ##
  78 | ## Properties are set either at option declarations through the
  79 | ## argsparse_use_option() function, or using the
  80 | ## argsparse_set_option_property() function
  81 | ##
  82 | ## The currently supported properties are:
  83 | ##
  84 | ## - "hidden" @n
  85 | ## 	 An hidden option will not be shown in usage.
  86 | ##
  87 | ## - "mandatory" @n
  88 | ## 	 An option marked as mandatory is required on the command line. If
  89 | ##   a mandatory option is omited by the user, usage() will be
  90 | ##   triggered by argsparse_parse_options().
  91 | ##
  92 | ## - "value" @n
  93 | ##   On the command line, the option will require a value.
  94 | ## 	 Same effect if you end your optstring with a ':' char.
  95 | ##
  96 | ## - "default:<defaultvalue>" @n
  97 | ## 	 The default value for the option.
  98 | ##
  99 | ## - "short:<char>" @n
 100 | ##   The short single-letter equivalent of the option.
 101 | ##
 102 | ## - "type:<typename>" @n
 103 | ##   Give a type to the option value. User input value will be checked
 104 | ## 	 against built-in type verifications _or_ the
 105 | ## 	 "check_type_<typename>" function. You cannot override a built-in
 106 | ## 	 type. Built-in types are:
 107 | ##   - file
 108 | ##   - directory
 109 | ##   - pipe
 110 | ##   - terminal
 111 | ##   - socket
 112 | ##   - link
 113 | ##   - char
 114 | ##   - unsignedint
 115 | ##   - uint
 116 | ##   - integer
 117 | ##   - int
 118 | ##   - hexa
 119 | ##   - ipv4
 120 | ##   - ipv6
 121 | ##   - ip
 122 | ##   - hostname
 123 | ##   - host
 124 | ##   - portnumber
 125 | ##   - port
 126 | ##   - username
 127 | ##   - group
 128 | ##   - date
 129 | ##   .
 130 | ##
 131 | ## - "exclude:<option> <option>" @n
 132 | ##   The exclude property value is a space-separated list of other
 133 | ##   options. User wont be able to provided two mutually exclusive
 134 | ##   options on the command line. @n
 135 | ##
 136 | ##   e.g: if you set exclude property for the --foo option this way:
 137 | ##   @code argsparse_set_option_property "exclude:opt1 opt2" foo @endcode
 138 | ##   Then --opt1 and --foo are not allowed on the same command line
 139 | ##   invokation. And same goes for --opt2 and --foo.
 140 | ##   This foo exclude property setting wouldnt make --opt1 and --opt2,
 141 | ##   mutually exclusive though.
 142 | ##
 143 | ## - "alias:<option> <option>" @n
 144 | ##   This property allows an option to set multiple other without-value
 145 | ##   options instead. Recursive aliases are permitted but no loop
 146 | ##   detection is made, so be careful. @n
 147 | ##   e.g: if you declare an option 'opt' like this:
 148 | ##   @code argsparse_use_option opt "my description" "alias:opt1 opt2" @endcode
 149 | ##   Then if the user is doing --opt on the command line, it will be as
 150 | ##   if he would have done --opt1 --opt2
 151 | ##
 152 | ## - cumulative @n
 153 | ##   Implies 'value'.
 154 | ##   Everytime a cumulative option "optionname" is passed on the
 155 | ##   command line, the value is stored at the end of an array named
 156 | ##   "cumulated_values_<optionname>". @n
 157 | ##
 158 | ##   e.g: for a script with an opt1 option declared this way:
 159 | ##   @code argsparse_use_option opt1 "some description" cumulative @endcode
 160 | ##   and invoked with:
 161 | ##   @code --opt1 value1 --opt1 value2 @endcode
 162 | ##   after argsparse_parse_options(), "${cumulated_values_opt1[0]}" will
 163 | ##   expand to value1, and ${cumulated_values_opt1[1]} will expand to
 164 | ##   value2.
 165 | ##
 166 | ## - cumulativeset @n
 167 | ##   Exactly like cumulative, except only uniq values are kept. @n
 168 | ##
 169 | ##   e.g: for a script with an opt1 option declared this way:
 170 | ##   @code argsparse_use_option opt1 "some description" cumulativeset @endcode
 171 | ##   and invoked with:
 172 | ##   @code --opt1 value1 --opt1 value2 --opt1 value1 @endcode
 173 | ##   after argsparse_parse_options(), "${cumulated_values_opt1[0]}" will
 174 | ##   expand to value1, and "${cumulated_values_opt1[1]}" will expand to
 175 | ##   value2. There would be no "${cumulated_values_opt1[2]}" value.
 176 | ##
 177 | ## - "require:<option> <option>" @n
 178 | ##   Creates a dependency between options. if you declare an option with:
 179 | ##   @code
 180 | ##   argsparse_use_option opt1 "something" require:"opt2 opt3"
 181 | ##   @endcode
 182 | ##   argsparse_parse_options() would return with an error if "--opt1"
 183 | ##   is given on the commande line without "--opt2" or without "--opt3".
 184 | ##
 185 | ## @par
 186 | ## You can test if an option has a property using the
 187 | ## argsparse_has_option_property() function.
 188 | ## @code argsparse_has_option_property <option> <property> @endcode
 189 | ##
 190 | ##
 191 | ## @par Parsing positionnal parameters
 192 | ## After the options are declared, invoke the function
 193 | ## argsparse_parse_options() with the all script parameters. This will
 194 | ## define:
 195 | ##
 196 | ## - program_params, an array, containing all non-option parameters.
 197 | ##
 198 | ## - program_options, an associative array. For each record of the
 199 | ##   array:
 200 | ##   - The key is the long option name.
 201 | ##   - And about values:
 202 | ##     - If option doesn't expect a value on the command line, the
 203 | ##       value represents how many times the option has been
 204 | ##       found on the command line
 205 | ##
 206 | ##     - If option does require a value, the array record value is the
 207 | ##       value of the last occurence of the option found on the command
 208 | ##       line.
 209 | ##     .
 210 | ##   - If option is cumulative (or cumulativeset), the array record
 211 | ##     value is the number of values passed by the user.
 212 | ##   .
 213 | ##
 214 | ## After argsparse_parse_options() invokation, you can check if an
 215 | ## option have was on the command line (or not) using the
 216 | ## argsparse_is_option_set() function. @n
 217 | ##
 218 | ## e.g:
 219 | ## @code argsparse_is_option_set "long-option-name" @endcode
 220 | ##
 221 | ##
 222 | ## @par The "usage()" function
 223 | ## If a 'usage' function is defined, and shall
 224 | ## argsparse_parse_options() return with non-zero status, 'usage' will
 225 | ## be automatically called.
 226 | ##
 227 | ## @note
 228 | ## This library automatically defines a default 'usage' function,
 229 | ## which may be removed or overridden by the sourcing program
 230 | ## afterwards.
 231 | ##
 232 | ## @par Value setting internal logic
 233 | ## During option parsing, for every option of the form '--optionname'
 234 | ## expecting a value:
 235 | ##
 236 | ## - If there exists an array named "option_<optionname>_values" and
 237 | ##   the user-given value doesn't belong to that array, then the
 238 | ##   argsparse_parse_options() function immediately returns with
 239 | ##   non-zero status, triggering 'usage'.
 240 | ##
 241 | ## - If the "option_<optionname>_values" array does not exist, but if
 242 | ##   the option has a type property field, then the value format will
 243 | ##   be checked against that type.
 244 | ##
 245 | ## - If a function named "check_value_of_<optionname>" has been
 246 | ##   defined, it will be called with the user-given value as its first
 247 | ##   positionnal parameter. If check_value_of_<optionname> returns
 248 | ##   with non-zero status, then parse_option immediately returns with
 249 | ##   non-zero status, triggering the 'usage' function.
 250 | ##
 251 | ## @par
 252 | ## Also, still during option parsing and for @b every option of the form
 253 | ## "--optionname":
 254 | ##
 255 | ## - After value-checking, if a function named
 256 | ##   "set_option_<optionname>" exists, then, instead of directly
 257 | ##   modifying the "program_options" associative array, this function
 258 | ##   is automatically called with 'optionname' as its first
 259 | ##   positionnal parameter, and, if 'optionname' expected a value, the
 260 | ##   value is given as the function second positionnal parameter.
 261 | ##
 262 | ## @par About functions return values...
 263 | ##
 264 | ## All argsparse functions will return with an error (usually a return
 265 | ## code of 1) if called with a wrong number of parameters, and return
 266 | ## with 0 if everything went fine.
 267 | ##
 268 | ## @defgroup ArgsparseUsage Calling program usage description message.
 269 | ## @defgroup ArgsparseOptionSetter Setting options values.
 270 | ## @defgroup ArgsparseCLIParsing ...
 271 | ## @defgroup ArgsparseProperty Options properties handling.
 272 | ## @defgroup ArgsparseParameter Non-optional positionnal parameters.
 273 | ## @defgroup ArgsparseUtils Misc Functions.
 274 | ## @defgroup ArgsparseOptionTyping ...
 275 | 
 276 | # We're not compatible with older bash versions.
 277 | if [[ "$BASH_VERSINFO" -lt 4 ]]
 278 | then
 279 | 	printf >&2 "This requires bash >= 4 to run.\n"
 280 | 	return 1 2>/dev/null
 281 | 	exit 1
 282 | fi
 283 | 
 284 | if ! command -v getopt >/dev/null 2>&1
 285 | then
 286 | 	printf >&2 "Cannot find the getopt command.\n"
 287 | 	return 1 2>/dev/null
 288 | 	exit 1
 289 | fi
 290 | 
 291 | if declare -rp ARGSPARSE_VERSION >/dev/null 2>&1
 292 | then
 293 | 	# argsparse is already loaded.
 294 | 	return 0 2>/dev/null
 295 | fi
 296 | 
 297 | ## @var ARGSPARSE_VERSION
 298 | ## @brief argsparse version number
 299 | ## @showinitializer
 300 | declare -r ARGSPARSE_VERSION=1.8
 301 | 
 302 | 
 303 | ## @var ARGSPARASE_GNU_GETOPT
 304 | ## @brief the location of the GNU getopt program.
 305 | ## @details If empty (the default), a PATH lookup will be
 306 | ## performed. When specified, it should be an absolute-path reference
 307 | ## as current working directory invariance is not guaranteed.
 308 | ## @showinitializer
 309 | declare ARGSPARSE_GNU_GETOPT=${ARGSPARSE_GNU_GETOPT:-getopt}
 310 | 
 311 | 
 312 | # Enable required features
 313 | shopt -s extglob
 314 | set +o posix
 315 | 
 316 | ## @brief The name of the program currently using argsparse.
 317 | ## @details Automatically set by argsparse at load time, it contains
 318 | ## the basename (path-less but with extension, if any) of the main
 319 | ## script. Used internally to print error messages and by
 320 | ## usage-related functions, but can be used by the loading script.
 321 | ## @hideinitializer
 322 | declare -r argsparse_pgm=${0##*/}
 323 | 
 324 | 
 325 | ## @var String __argsparse_environment_variable_prefix
 326 | ## @brief The prefix for option-setting environment variables
 327 | ## @private
 328 | ## @ingroup ArgsparseOptionSetter
 329 | declare __argsparse_environment_variable_prefix
 330 | 
 331 | 
 332 | ## @fn argsparse_use_environment_variables()
 333 | ## @brief Enable option setting through environment variables.
 334 | ## @details
 335 | ## Once enabled, it cannot be disabled.
 336 | ## @param prefix an environment variable prefix
 337 | ## @ingroup ArgsparseOptionSetter
 338 | argsparse_use_environment_variables() {
 339 | 	local prefix
 340 | 	case $# in
 341 | 		0)
 342 | 			prefix=$(argsparse_option_to_identifier "${argsparse_pgm%.sh}")
 343 | 			prefix=${prefix^^}
 344 | 			;;
 345 | 		1)
 346 | 			prefix=$1
 347 | 			;;
 348 | 		*)
 349 | 			return 1
 350 | 	esac
 351 | 	__argsparse_environment_variable_prefix=$prefix
 352 | }
 353 | 
 354 | 
 355 | ## @fn argsparse_are_environment_variables_enabled()
 356 | ## @brief Tell if option setting through environment variables is
 357 | ## enabled or not.
 358 | ## @details
 359 | ## @retval 0 if argsparse_parse_options would also retrieve option
 360 | ## values from environment variables.
 361 | ## @ingroup @ArgsparseOptionSetter
 362 | argsparse_are_environment_variables_enabled() {
 363 | 	[[ ${__argsparse_environment_variable_prefix:-} ]]
 364 | }
 365 | 
 366 | 
 367 | ## @fn argsparse_option_environment_variable_name()
 368 | ## @brief Give the environment variable name linked to an option
 369 | ## @details0
 370 | ## Return the name of the environment variable name that can be used
 371 | ## to set a given option. Works whether option setting through
 372 | ## environment variables is enabled or not.
 373 | ## @param option an option name
 374 | ## @return the environment variable name linked to the option
 375 | argsparse_option_environment_variable_name() {
 376 | 	[[ $# -eq 1 ]] || return 1
 377 | 	local option=$1
 378 | 	local identifier=$(argsparse_option_to_identifier "$option")
 379 | 	printf %s_%s "$__argsparse_environment_variable_prefix" "${identifier^^}"
 380 | }
 381 | 
 382 | 
 383 | ## @fn argsparse_option_environment_variable()
 384 | ## @brief Give the content of the environment variable that can be
 385 | ## used to set a given option.
 386 | ## @details
 387 | ## Does not check if option setting through environment variable is
 388 | ## enabled or not.
 389 | ## @param option An option name
 390 | ## @return The content of the environment variable that matches the
 391 | ## given option.
 392 | ## @retval 0 if the variable that matches the given option actually
 393 | ## exists (even if its value is empty)
 394 | argsparse_option_environment_variable() {
 395 | 	[[ $# -eq 1 ]] || return 1
 396 | 	local option=$1
 397 | 	local var=$(argsparse_option_environment_variable_name "$option")
 398 | 	if [[ -v $var ]]; then
 399 | 		printf %s "${!var}"
 400 | 		return 0
 401 | 	fi
 402 | 	return 1
 403 | }
 404 | 
 405 | 
 406 | ## @fn argsparse_set_option_from_environment_value()
 407 | ## @brief Give a value to an option, from environment variable value.
 408 | ## @details
 409 | ## Options can be set from environment variables, and in some cases,
 410 | ## those values have special meanings:
 411 | ## - 0, "false", "no" and the empty string are explicit values to
 412 | ## disable a non-valued option
 413 | ## - (probably more to come)
 414 | ## .
 415 | ## @param option an option name
 416 | ## @param value the value, as found in the process environment, to set
 417 | ## the option to.
 418 | argsparse_set_option_from_environment_value() {
 419 | 	[[ $# -eq 2 ]] || return 1
 420 | 	local option=$1
 421 | 	local value=$2
 422 | 	if ! argsparse_has_option_property "$option" value
 423 | 	then
 424 | 		if [[ $value != +(0|false|no|"") ]]
 425 | 		then
 426 | 			argsparse_set_option "$option"
 427 | 		fi
 428 | 	# There should be an elif statement here, if we want to consider
 429 | 	# cumulated options differently.
 430 | 	else
 431 | 		argsparse_set_option "$option" "$value"
 432 | 	fi
 433 | }
 434 | 
 435 | 
 436 | ## @fn __argsparse_parse_options_env_and_defaults()
 437 | ## @brief set options from environment and from default values.
 438 | ## @details
 439 | ## For every option that have not been set from command line, look for
 440 | ## a matching environment variable (when
 441 | ## argsparse_are_environment_variables_enabled() is true) and apply
 442 | ## default values right after if still left unset.
 443 | ## @private
 444 | __argsparse_parse_options_env_and_defaults() {
 445 | 	local option value
 446 | 	for option in "${!__argsparse_options_descriptions[@]}"
 447 | 	do
 448 | 		if ! argsparse_is_option_set "$option"
 449 | 		then
 450 | 			if argsparse_are_environment_variables_enabled &&
 451 | 					value=$(argsparse_option_environment_variable "$option")
 452 | 			then
 453 | 				argsparse_set_option_from_environment_value "$option" "$value"
 454 | 			elif __argsparse_has_array_item \
 455 | 					 __argsparse_options_default_values "$option"
 456 | 			then
 457 | 				 argsparse_set_option "$option" \
 458 | 					"${__argsparse_options_default_values[$option]}"
 459 | 			fi
 460 | 		fi
 461 | 	done
 462 | }
 463 | 
 464 | 
 465 | ## @fn __argsparse_index_of()
 466 | ## @param value a value
 467 | ## @param values... array values
 468 | ## @brief Tells if a value is found in a set of other values.
 469 | ## @details Look for @a value and print its position in the @a values
 470 | ## set. Return false if it can not be found.
 471 | ## @retval 0 if @a value is amongst @a values
 472 | ## @retval 1 if @a value is not found.
 473 | ## @ingroup ArgsparseUtils
 474 | __argsparse_index_of() {
 475 | 	[[ $# -ge 2 ]] || return 1
 476 | 	local key=$1 ; shift
 477 | 	local index=0
 478 | 	local elem
 479 | 	for elem in "$@"
 480 | 	do
 481 | 		if [[ "$key" = "$elem" ]]
 482 | 		then
 483 | 			printf %s "$index"
 484 | 			return 0
 485 | 		fi
 486 | 		: $((index++))
 487 | 	done
 488 | 	return 1
 489 | }
 490 | 
 491 | ## @fn __argsparse_join_array()
 492 | ## @param c a single char
 493 | ## @param strings... strings to join
 494 | ## @brief join multiple strings by a char.
 495 | ## @details Like the 'str.join' string method in python, join multiple
 496 | ## strings by a char. Only work with a single char, though.
 497 | ## @retval 1 if first parameter is invalid.
 498 | ## @retval 0 else.
 499 | ## @ingroup ArgsparseUtils
 500 | __argsparse_join_array() {
 501 | 	[[ $# -ge 1 && $1 = ? ]] || return 1
 502 | 	local IFS="$1$IFS"
 503 | 	shift
 504 | 	printf %s "$*"
 505 | }
 506 | 
 507 | 
 508 | # @private
 509 | # @fn __argsparse_max_length()
 510 | # @details Prints the length of the longest argument _or_ 50.
 511 | # @brief Internal use.
 512 | # @param string... a list of strings
 513 | # @return 0
 514 | __argsparse_max_length() {
 515 | 	local max=50
 516 | 	shift
 517 | 	local max_length=0 str
 518 | 	for str in "$@"
 519 | 	do
 520 | 		max_length=$((max_length>${#str}?max_length:${#str}))
 521 | 	done
 522 | 	printf %d "$((max_length>max?max:max_length))"
 523 | }
 524 | 
 525 | 
 526 | ## @fn __argsparse_is_array_declared()
 527 | ## @param name A potential array name
 528 | ## @retval 0 if an array named after the parameter does exist
 529 | ## @ingroup ArgsparseUtils
 530 | __argsparse_is_array_declared() {
 531 | 	[[ $# -eq 1 ]] || return 1
 532 | 	local array_name=$1
 533 | 	[[ "$(declare -p "$array_name" 2>/dev/null)" = \
 534 | 		"declare -"[aA]" $array_name="* ]]
 535 | }
 536 | 
 537 | 
 538 | ## @fn __argsparse_has_array_item()
 539 | ## @param array_name an array name.
 540 | ## @param item an item key.
 541 | ## @retval 0 if an array has been already declared by the name of
 542 | ## the parameter AND if said array holds given key.
 543 | ## @ingroup ArgsparseUtils
 544 | __argsparse_has_array_item() {
 545 | 	[[ $# = [12] ]] || return 1
 546 | 	local array_name=$1
 547 | 	local index=${2:-@}
 548 | 	local var="$array_name[$index]"
 549 | 	(
 550 | 		set +o nounset
 551 | 		[[ ${!var+set} = set ]]
 552 | 	)
 553 | }
 554 | 
 555 | 
 556 | ## @fn argsparse_option_to_identifier()
 557 | ## @brief Give the identifier name associated to an option.
 558 | ## @details Transforms and prints an option name into a string which
 559 | ## suitable to be part of a function or a variable name.
 560 | ## @param option an option name.
 561 | ## @ingroup ArgsparseUtils
 562 | argsparse_option_to_identifier() {
 563 | 	[[ $# -eq 1 ]] || return 1
 564 | 	local option=$1
 565 | 	printf %s "${option//-/_}"
 566 | }
 567 | 
 568 | 
 569 | ## @fn __argsparse_values_array_identifier()
 570 | ## @private
 571 | ## @brief Prints the name of the array containing all user-declared
 572 | ## acceptable values for an option.
 573 | ## @details from "opt" or "opt-name" string, prints
 574 | ## "option_opt_values[@]" or "option_opt_name_values[@]", unless array
 575 | ## is not declared, in which case function will return an error.
 576 | ## @param option an option name.
 577 | ## @retval 1 if array has not been declared
 578 | ## @retval 0 else. Array name will be written to stdout.
 579 | ## @ingroup ArgsparseUtils
 580 | __argsparse_values_array_identifier() {
 581 | 	local option=$1
 582 | 	local array="option_$(argsparse_option_to_identifier "$option")_values"
 583 | 	__argsparse_is_array_declared "$array" || return 1
 584 | 	printf %s'[@]' "$array"
 585 | }
 586 | 
 587 | 
 588 | ## @brief Internal use only.
 589 | ## @details An associative array where options default values are
 590 | ## stored as soon as the 'default:' property is set.
 591 | ## @ingroup ArgsparseProperty
 592 | declare -A __argsparse_options_default_values=()
 593 | 
 594 | 
 595 | ## @var AssociativeArray __argsparse_options_properties
 596 | ## @private
 597 | ## @brief Internal use only.
 598 | ## @ingroup ArgsparseProperty
 599 | declare -A __argsparse_options_properties=()
 600 | 
 601 | 
 602 | # Association short option -> long option.
 603 | ## @var AssociativeArray __argsparse_short_options
 604 | ## @private
 605 | ## @brief Internal use only.
 606 | declare -A __argsparse_short_options=()
 607 | 
 608 | 
 609 | # @fn __argsparse_optstring_has_short()
 610 | # @brief Internal use only.
 611 | # @details Prints the short option string suitable for getopt command
 612 | # line.
 613 | # @param optstring an optstring
 614 | # @return non-zero if given optstring doesnt have any short option
 615 | # equivalent.
 616 | __argsparse_optstring_has_short() {
 617 | 	[[ $# -eq 1 ]] || return 1
 618 | 	local optstring=$1
 619 | 	if [[ "$optstring" =~ .*=(.).* ]]
 620 | 	then
 621 | 		printf %c "${BASH_REMATCH[1]}"
 622 | 		return 0
 623 | 	fi
 624 | 	return 1
 625 | }
 626 | 
 627 | 
 628 | ## @fn argsparse_set_option_property()
 629 | ## @brief Enable a property to a list of options.
 630 | ## @param property a property name.
 631 | ## @param option... option names.
 632 | ## @return non-zero if property is not supported.
 633 | ## @ingroup ArgsparseProperty
 634 | argsparse_set_option_property() {
 635 | 	[[ $# -ge 2 ]] || return 1
 636 | 	local property=$1
 637 | 	shift
 638 | 	local option p short
 639 | 	for option in "$@"
 640 | 	do
 641 | 		case "$property" in
 642 | 			cumulative|cumulativeset)
 643 | 				argsparse_set_option_property value "$option"
 644 | 				;;&
 645 | 			type:*|exclude:*|alias:*|require:*)
 646 | 				if [[ "$property" =~ ^.*:(.+)$ ]]
 647 | 				then
 648 | 					# If property has a value, check its format, we
 649 | 					# dont want any funny chars.
 650 | 					if [[ "${BASH_REMATCH[1]}" = *[*?!,]* ]]
 651 | 					then
 652 | 						printf >&2 "%s: %s: invalid property value.\n" \
 653 | 							"$argsparse_pgm" "${BASH_REMATCH[1]}"
 654 | 						return 1
 655 | 					fi
 656 | 				fi
 657 | 				;&
 658 | 			mandatory|hidden|value|cumulative|cumulativeset)
 659 | 				# We use the comma as the property character separator
 660 | 				# in the __argsparse_options_properties array.
 661 | 				p=${__argsparse_options_properties["$option"]:-}
 662 | 				__argsparse_options_properties["$option"]="${p:+$p,}$property"
 663 | 				;;
 664 | 			short:?)
 665 | 				short=${property#short:}
 666 | 				if __argsparse_has_array_item \
 667 | 					__argsparse_short_options "$short"
 668 | 				then
 669 | 					printf >&2 \
 670 | 						"%s: %s: short option for %s conflicts with already-configured short option for %s.\n" \
 671 | 						"$argsparse_pgm" "$short" "$option" \
 672 | 						"${__argsparse_short_options[$short]}"
 673 | 					return 1
 674 | 				fi
 675 | 				__argsparse_short_options["$short"]=$option
 676 | 				;;
 677 | 			default:*)
 678 | 				# The default value
 679 | 				__argsparse_options_default_values["$option"]=${property#default:}
 680 | 				;;
 681 | 			*)
 682 | 				return 1
 683 | 				;;
 684 | 		esac
 685 | 	done
 686 | }
 687 | 
 688 | ## @fn argsparse_has_option_property()
 689 | ## @brief Determine if an option has a property.
 690 | ## @details Return True if property has been set for given option, and
 691 | ## print the property value, if available.
 692 | ## @param option an option name.
 693 | ## @param property a property name.
 694 | ## @retval 0 if option has given property.
 695 | ## @ingroup ArgsparseProperty
 696 | argsparse_has_option_property() {
 697 | 	[[ $# -eq 2 ]] || return 1
 698 | 	local option=$1
 699 | 	local property=$2
 700 | 	local p=${__argsparse_options_properties["$option"]:-""}
 701 | 
 702 | 	if [[ "$p" =~ (^|.+,)"$property"(:([^,]+))?($|,.+) ]]
 703 | 	then
 704 | 		printf %s "${BASH_REMATCH[3]}"
 705 | 	elif [[ $property = default && \
 706 | 		"${__argsparse_options_default_values[$option]+yes}" = yes ]]
 707 | 	then
 708 | 			print %s "${__argsparse_options_default_values[$option]}"
 709 | 	else
 710 | 		return 1
 711 | 	fi
 712 | }
 713 | 
 714 | 
 715 | ## @fn argsparse_short_to_long()
 716 | ## @brief
 717 | ## @param char a short option letter
 718 | ## @return if found, the long option name matching given short option
 719 | ## letter.
 720 | argsparse_short_to_long() {
 721 | 	[[ $# -eq 1 ]] || return 1
 722 | 	local char=$1
 723 | 	local long=${__argsparse_short_options[$char]}
 724 | 	[[ -n "$long" ]] && printf %s "$long"
 725 | }
 726 | 
 727 | 
 728 | # This is an associative array. It should contains records of the form
 729 | # "something" -> "Some usage description string".
 730 | # The "something" string is referred as the "option name" later in
 731 | # source code and comments.
 732 | ## @var AssociativeArray __argsparse_options_descriptions
 733 | ## @private
 734 | ## @brief Internal use only.
 735 | declare -A __argsparse_options_descriptions=()
 736 | 
 737 | 
 738 | # @fn __argsparse_check_declaration_conflict()
 739 | # @brief Internal use.
 740 | # @details Check if an option conflicts with another and, if it does,
 741 | # prints the conflicted option.
 742 | # @param option an option name
 743 | # @return True if option *does* conflict with a previously declared
 744 | # option.
 745 | __argsparse_check_declaration_conflict() {
 746 | 	[[ $# -eq 1 ]] || return 1
 747 | 	local option=$1
 748 | 	local identifier=$(argsparse_option_to_identifier "$option")
 749 | 	local -a identifiers=("${!__argsparse_tmp_identifiers[@]}")
 750 | 	local conflict
 751 | 	if __argsparse_has_array_item identifiers @ && \
 752 | 		   conflict=$(__argsparse_index_of "$identifier" "${identifiers[@]}")
 753 | 	then
 754 | 		printf %s "${__argsparse_tmp_identifiers[${identifiers[$conflict]}]}"
 755 | 		return 0
 756 | 	fi
 757 | 	__argsparse_tmp_identifiers["$identifier"]=$option
 758 | 	return 1
 759 | }
 760 | 
 761 | 
 762 | ## @fn argsparse_use_option()
 763 | ## @brief Define a @b new option.
 764 | ## @param optstring an optstring.
 765 | ## @param description the option description, for the usage() function.
 766 | ## @param property... an non-ordered list of keywords. Recognized
 767 | ## property keywords are:
 768 | ##   - mandatory: missing option will trigger usage. If a default
 769 | ##     value is given, the option is considered as if provided on
 770 | ##     the command line.
 771 | ##   - hidden: option wont show in default usage function.
 772 | ##   - value: option expects a following value.
 773 | ##   - short:c: option has a single-lettered (c) equivalent.
 774 | ##   - exclude:"option1 [ option2 ... ]" option is not
 775 | ##   compatible with other options option1, option2...
 776 | ##   - cumulative
 777 | ##   - cumulativeset
 778 | ##   - type:sometype
 779 | ##   - The @b last non-keyword parameter will be considered as the
 780 | ##     default value for the option. All other parameters and
 781 | ##     values will be ignored. - might be broken / obsolete and broken
 782 | ## @retval 0 if no error is encountered.
 783 | ## @retval 2 if option name is bad (a message will be printed)
 784 | ## @retval 3 if option name conflicts with another option (a message
 785 | ## will be printed)
 786 | ## @retval 4 if a wrong property name is provided. (a message will be
 787 | ## printed)
 788 | argsparse_use_option() {
 789 | 	[[ $# -ge 2 ]] || return 1
 790 | 	local optstring=$1
 791 | 	local description=$2
 792 | 	shift 2
 793 | 	local long short conflict
 794 | 	# configure short option.
 795 | 	if short=$(__argsparse_optstring_has_short "$optstring")
 796 | 	then
 797 | 		set -- "short:$short" "$@"
 798 | 		optstring=${optstring/=/}
 799 | 	fi
 800 | 	# --$optstring expect an argument.
 801 | 	if [[ "$optstring" = *: ]]
 802 | 	then
 803 | 		set -- value "$@"
 804 | 		long=${optstring%:}
 805 | 	else
 806 | 		long=$optstring
 807 | 	fi
 808 | 
 809 | 	if [[ "$long" = *[!-0-9a-zA-Z_]* ]]
 810 | 	then
 811 | 		printf >&2 "%s: %s: bad option name.\n" "$argsparse_pgm" "$long"
 812 | 		return 2
 813 | 	fi
 814 | 
 815 | 	if conflict=$(__argsparse_check_declaration_conflict "$long")
 816 | 	then
 817 | 		printf >&2 "%s: %s: option conflicts with already-declared %s.\n" \
 818 | 			"$argsparse_pgm" "$long" "$conflict"
 819 | 		return 3
 820 | 	fi
 821 | 
 822 | 	__argsparse_options_descriptions["$long"]=$description
 823 | 
 824 | 	# Any other parameter to this function should be a property.
 825 | 	while [[ $# -ne 0 ]]
 826 | 	do
 827 | 		if ! argsparse_set_option_property "$1" "$long"
 828 | 		then
 829 | 			printf >&2 '%s: %s: unknown property.\n' "$argsparse_pgm" "$1"
 830 | 			return 4
 831 | 		fi
 832 | 		shift
 833 | 	done
 834 | }
 835 | 
 836 | ## @fn argsparse_option_description()
 837 | ## @brief Prints to stdout the description of given option.
 838 | ## @param option an option name.
 839 | ## @retval 0 if given option has been previously declared.
 840 | argsparse_option_description() {
 841 | 	[[ $# -eq 1 ]] || return 1
 842 | 	local option=$1
 843 | 	[[ -n "${__argsparse_options_descriptions[$option]+yes}" ]] && \
 844 | 		printf %s "${__argsparse_options_descriptions[$option]}"
 845 | }
 846 | 
 847 | 
 848 | ## @fn argsparse_check_option_type()
 849 | ## @brief Check if a value matches a given type.
 850 | ## @details Return True if @a value is of type @a type.
 851 | ## @param type A case-insensitive type name.
 852 | ## @param value a value to check.
 853 | ## @retval 0 if the value matches the given type format.
 854 | ## @ingroup ArgsparseOptionTyping
 855 | argsparse_check_option_type() {
 856 | 	[[ $# -eq 2 ]] || return 1
 857 | 	local option_type=${1,,}
 858 | 	local value=$2
 859 | 	local t
 860 | 	case "$option_type" in
 861 | 		file|directory|pipe|terminal)
 862 | 			# [[ wont accept the -$var as an operator.
 863 | 			[ -"${option_type:0:1}" "$value" ]
 864 | 			;;
 865 | 		socket|link)
 866 | 			t=${option_type:0:1}
 867 | 			[ -"${t^^}" "$value" ]
 868 | 			;;
 869 | 		char)
 870 | 			[[ "$value" = ? ]]
 871 | 			;;
 872 | 		unsignedint|uint)
 873 | 			[[ "$value" = +([0-9]) ]]
 874 | 			;;
 875 | 		integer|int)
 876 | 			[[ "$value" = ?(-)+([0-9]) ]]
 877 | 			;;
 878 | 		hexa)
 879 | 			[[ "$value" = ?(0x)+([a-fA-F0-9]) ]]
 880 | 			;;
 881 | 		ipv4)
 882 | 			# Regular expression for ipv4 and ipv6 have been found on
 883 | 			# http://www.d-sites.com/2008/10/09/regex-ipv4-et-ipv6/
 884 | 			[[ "$value" =~ ^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ ]]
 885 | 			;;
 886 | 		ipv6)
 887 | 			[[ "$value" =~ ^((([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){6}:[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){5}:([0-9A-Fa-f]{1,4}:)?[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){4}:([0-9A-Fa-f]{1,4}:){0,2}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){3}:([0-9A-Fa-f]{1,4}:){0,3}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){2}:([0-9A-Fa-f]{1,4}:){0,4}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){6}((b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b).){3}(b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b))|(([0-9A-Fa-f]{1,4}:){0,5}:((b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b).){3}(b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b))|(::([0-9A-Fa-f]{1,4}:){0,5}((b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b).){3}(b((25[0-5])|(1d{2})|(2[0-4]d)|(d{1,2}))b))|([0-9A-Fa-f]{1,4}::([0-9A-Fa-f]{1,4}:){0,5}[0-9A-Fa-f]{1,4})|(::([0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4})|(([0-9A-Fa-f]{1,4}:){1,7}:))$ ]]
 888 | 			;;
 889 | 		ip)
 890 | 			# Generic IP address.
 891 | 			argsparse_check_option_type ipv4 "$value" || \
 892 | 				argsparse_check_option_type ipv6 "$value"
 893 | 			;;
 894 | 		hostname)
 895 | 			# check if value resolv as an IPv4 or IPv6 address.
 896 | 			host -t a "$value" >/dev/null 2>&1 || \
 897 | 				host -t aaaa "$value" >/dev/null 2>&1
 898 | 			;;
 899 | 		host)
 900 | 			# An hostname or an IP address.
 901 | 			argsparse_check_option_type hostname "$value" || \
 902 | 				argsparse_check_option_type ipv4 "$value" || \
 903 | 				argsparse_check_option_type ipv6 "$value"
 904 | 			;;
 905 | 		portnumber)
 906 | 			argsparse_check_option_type uint "$value" && \
 907 | 				[[ "$value" -gt 0 && "$value" -le 65536 ]]
 908 | 			;;
 909 | 		port)
 910 | 			# Port number or service.
 911 | 			argsparse_check_option_type portnumber "$value" || \
 912 | 				getent services "$value" >/dev/null 2>&1
 913 | 			;;
 914 | 		username)
 915 | 			getent passwd "$value" >/dev/null 2>&1
 916 | 			;;
 917 | 		group)
 918 | 			getent group "$value" >/dev/null 2>&1
 919 | 			;;
 920 | 		date)
 921 | 			date --date "$value"  >/dev/null 2>&1
 922 | 			;;
 923 | 		*)
 924 | 			# Invoke user-defined type-checking function if available.
 925 | 			if ! declare -f "check_option_type_$option_type" >/dev/null
 926 | 			then
 927 | 				printf >&2 \
 928 | 					"%s: %s: type has no validation function. This is a bug.\n" \
 929 | 					"$argsparse_pgm" "$option_type"
 930 | 				return 2
 931 | 			fi
 932 | 			"check_option_type_$option_type" "$value"
 933 | 			;;
 934 | 	esac
 935 | }
 936 | 
 937 | 
 938 | # The usage-related functions.
 939 | 
 940 | ## @var Array __argsparse_parameters_description
 941 | ## @private
 942 | ## @brief Internal use only.
 943 | ## @ingroup ArgsparseUsage
 944 | # @details Used by argsparse_describe_parameters() to store
 945 | # non-option positionnal parameters short descriptions and by
 946 | # argsparse_usage_short() to print them to end-users.
 947 | declare -a __argsparse_parameters_description
 948 | 
 949 | 
 950 | __argsparse_usage_short_line_management() {
 951 | 	[[ $# -eq 1 ]] || return 1
 952 | 	local next_token=$1
 953 | 	local max_length=78
 954 | 	local bigger_line
 955 | 	bigger_line="$current_line $next_token"
 956 | 	if [[ "${#bigger_line}" -gt "$max_length" ]]
 957 | 	then
 958 | 		printf -- '%s \\\n' "$current_line"
 959 | 		printf -v current_line "\t%s" "$next_token"
 960 | 	else
 961 | 		current_line=$bigger_line
 962 | 	fi
 963 | }
 964 | 
 965 | 
 966 | ## @fn argsparse_usage_short()
 967 | ## @brief Print a short description of the program syntax.
 968 | ## @details Generate and print the "short" description of the program
 969 | ## usage.
 970 | ## @ingroup ArgsparseUsage
 971 | argsparse_usage_short() {
 972 | 	local option values current_line current_option param
 973 | 	local max_length=78
 974 | 	current_line=$argsparse_pgm
 975 | 	for option in "${!__argsparse_options_descriptions[@]}"
 976 | 	do
 977 | 		if argsparse_has_option_property "$option" hidden
 978 | 		then
 979 | 			continue
 980 | 		fi
 981 | 		current_option="--$option"
 982 | 		if argsparse_has_option_property "$option" value
 983 | 		then
 984 | 			if values=$(__argsparse_values_array_identifier "$option")
 985 | 			then
 986 | 				current_option="$current_option <$(
 987 | 					__argsparse_join_array '|' "${!values}")>"
 988 | 			else
 989 | 				current_option="$current_option ${option^^}"
 990 | 			fi
 991 | 		fi
 992 | 		if ! argsparse_has_option_property "$option" mandatory
 993 | 		then
 994 | 			current_option="[ $current_option ]"
 995 | 		fi
 996 | 		__argsparse_usage_short_line_management "$current_option"
 997 | 	done
 998 | 	if __argsparse_has_array_item __argsparse_parameters_description @
 999 | 	then
1000 | 	   for param in "${__argsparse_parameters_description[@]}"
1001 | 	   do
1002 | 		   __argsparse_usage_short_line_management "$param"
1003 | 	   done
1004 | 	fi
1005 | 	printf -- "%s\n" "$current_line"
1006 | }
1007 | 
1008 | 
1009 | ## @fn argsparse_describe_parameters()
1010 | ## @brief Describe non-option positionnal parameters.
1011 | ## @details This function has currently 2 purposes:
1012 | ## - enhance the "short" usage program description (see
1013 | ## argsparse_usage_short())
1014 | ## - compute the minimum and maximum numbers of non-option
1015 | ## positionnal parameters and will overwrite previous settings using
1016 | ## argsparse_minimum_parameters() and argsparse_maximum_parameters().
1017 | ##
1018 | ## @param param... a list of label describing positionnal
1019 | ## parameters. These labels can have special forms such as:
1020 | ## - "label?" a single optional non-repeatable parameter
1021 | ## - "label+" a non-empty list of parameters
1022 | ## - "label*" a potentially-empty list of parameters
1023 | ## - "label" a single non-optional non-repeatable parameter
1024 | ## @retval 0
1025 | ## @ingroup ArgsparseUsage
1026 | argsparse_describe_parameters() {
1027 | 	[[ $# -eq 0 ]] && return
1028 | 	local param last name
1029 | 	local -i min=0 max=0
1030 | 	__argsparse_parameters_description=( "[--]" )
1031 | 	for param in "$@"
1032 | 	do
1033 | 		name=${param%?}
1034 | 		last=${param#$name}
1035 | 		case "$last" in
1036 | 			'?')
1037 | 				: maximum param $((++max))
1038 | 				__argsparse_parameters_description+=( "[ $name ]" )
1039 | 				;;
1040 | 			'*')
1041 | 				max=1000000
1042 | 				__argsparse_parameters_description+=( "[ $name ... ]" )
1043 | 				;;
1044 | 			+)
1045 | 				max=1000000
1046 | 				: minimum param $((++min))
1047 | 				__argsparse_parameters_description+=( "$name [ $name ... ]" )
1048 | 				;;
1049 | 			*)
1050 | 				: maximum param $((++max))
1051 | 				: minimum param $((++min))
1052 | 				__argsparse_parameters_description+=( "$param" )
1053 | 		esac
1054 | 	done
1055 | 	argsparse_minimum_parameters "$min"
1056 | 	argsparse_maximum_parameters "$max"
1057 | }
1058 | 
1059 | 
1060 | ## @fn argsparse_usage_long()
1061 | ## @brief Fully describe the program syntax and options to the end-user.
1062 | ## @details This function generates and prints the "long" description
1063 | ## of the program usage. Print all options along with their
1064 | ## descriptions provided to argsparse_use_option().
1065 | ## @ingroup ArgsparseUsage
1066 | argsparse_usage_long() {
1067 | 	local long short sep format array property propstring
1068 | 	local q=\' bol='\t\t  '
1069 | 	local -A long_to_short=()
1070 | 	local -a values
1071 | 	# Reverse the __argsparse_short_options array.
1072 | 	for short in "${!__argsparse_short_options[@]}"
1073 | 	do
1074 | 		long=${__argsparse_short_options["$short"]}
1075 | 		long_to_short["$long"]=$short
1076 | 	done
1077 | 	for long in "${!__argsparse_options_descriptions[@]}"
1078 | 	do
1079 | 		if argsparse_has_option_property "$long" hidden
1080 | 		then
1081 | 			continue
1082 | 		fi
1083 | 		# Pretty printer issue here. If the long option length is
1084 | 		# greater than 8, we just use next line to print the option
1085 | 		# description.
1086 | 		if [[ "${#long}" -le 9 ]]
1087 | 		then
1088 | 			sep=' '
1089 | 		else
1090 | 			sep="\n$bol"
1091 | 		fi
1092 | 		# Define format according to the presence of the short option.
1093 | 		if __argsparse_has_array_item long_to_short "$long"
1094 | 		then
1095 | 			short="${long_to_short[$long]}"
1096 | 			format=" -%s | %- 11s$sep%s\n"
1097 | 		else
1098 | 			short=""
1099 | 			format=" %s     %- 11s$sep%s\n"
1100 | 		fi
1101 | 		printf -- "$format" "$short" "--$long" \
1102 | 			"${__argsparse_options_descriptions["$long"]}"
1103 | 		if argsparse_has_option_property "$long" cumulative || \
1104 | 			argsparse_has_option_property "$long" cumulativeset
1105 | 		then
1106 | 			printf "${bol}Can be repeated.\n"
1107 | 		fi
1108 | 		if argsparse_has_option_property "$long" value
1109 | 		then
1110 | 			if array=$(__argsparse_values_array_identifier "$long")
1111 | 			then
1112 | 				values=( "${!array}" )
1113 | 				values=( "${values[@]/%/$q}" )
1114 | 				values=( "${values[@]/#/$q}" )
1115 | 				printf "${bol}Acceptable values: %s\n" \
1116 | 					"$(__argsparse_join_array " " "${values[@]}")"
1117 | 			fi
1118 | 			if __argsparse_index_of "$long" \
1119 | 				"${!__argsparse_options_default_values[@]}" >/dev/null
1120 | 			then
1121 | 				printf "${bol}Default: %s\n" \
1122 | 					"${__argsparse_options_default_values[$long]}"
1123 | 			fi
1124 | 		fi
1125 | 		local -A properties=([require]="Requires" [alias]="Same as")
1126 | 		for property in "${!properties[@]}"
1127 | 		do
1128 | 			if propstring=$(argsparse_has_option_property "$long" "$property")
1129 | 			then
1130 | 				read -a values <<<"$propstring"
1131 | 				values=( "${values[@]/#/--}" )
1132 | 				printf "${bol}%s: %s\n" \
1133 | 					"${properties[$property]}" "${values[*]}"
1134 | 			fi
1135 | 		done
1136 | 		if argsparse_are_environment_variables_enabled
1137 | 		then
1138 | 			printf "${bol}Environment variable: %s\n" \
1139 | 				"$(argsparse_option_environment_variable_name "$long")"
1140 | 		fi
1141 | 	done
1142 | }
1143 | 
1144 | ## @var String argsparse_usage_description
1145 | ## @brief Usage description additionnal string.
1146 | ## @details The content of this variable will be appended to the
1147 | ## argsparse_usage() output.
1148 | ## @ingroup ArgsparseUsage
1149 | declare argsparse_usage_description
1150 | 
1151 | ## @fn argsparse_usage()
1152 | ## @brief A generic help message generated from the options and their
1153 | ## descriptions.
1154 | ## @details Will print both a rather-short and a quite long
1155 | ## description of the program and its options. Just provided to be
1156 | ## wrapped in your own usage().
1157 | ## @ingroup ArgsparseUsage
1158 | argsparse_usage() {
1159 | 	# There's still a lot of room for improvement here.
1160 | 	argsparse_usage_short
1161 | 	printf "\n"
1162 | 	# This will print option descriptions.
1163 | 	argsparse_usage_long
1164 | 	[[ -n "${argsparse_usage_description:-}" ]] && \
1165 | 		printf "\n%s\n" "$argsparse_usage_description" || :
1166 | }
1167 | 
1168 | 
1169 | # Following functions define the default option-setting hook and its
1170 | # with/without value counter-parts. They can be referered in external
1171 | # source code, though they should only be in user-defined
1172 | # option-setting hooks.
1173 | 
1174 | # All user-defined option-setting hook should be defined like
1175 | # argsparse_set_option
1176 | 
1177 | ## @fn argsparse_set_option_without_value()
1178 | ## @brief The option-setting hook for options not accepting values.
1179 | ## @param option an option name.
1180 | ## @retval 0
1181 | ## @ingroup ArgsparseOptionSetter
1182 | argsparse_set_option_without_value() {
1183 | 	[[ $# -eq 1 ]] || return 1
1184 | 	local option=$1
1185 | 	: $((program_options["$option"]++))
1186 | }
1187 | 
1188 | ## @fn argsparse_set_option_with_value()
1189 | ## @brief "value" property specific option-setting hook.
1190 | ## @param option an option name.
1191 | ## @param value the value put on command line for given option.
1192 | ## @ingroup ArgsparseOptionSetter
1193 | argsparse_set_option_with_value() {
1194 | 	[[ $# -eq 2 ]] || return 1
1195 | 	local option=$1
1196 | 	local value=$2
1197 | 	program_options["$option"]=$value
1198 | }
1199 | 
1200 | ## @fn argsparse_get_cumulative_array_name()
1201 | ## @param option an option name.
1202 | ## @brief Print the name of the array used for "cumulative" and
1203 | ## "cumulativeset" options.
1204 | ## @details For "option-name" usually prints
1205 | ## "cumulated_values_option_name".
1206 | ## @ingroup ArgsparseOptionSetter
1207 | argsparse_get_cumulative_array_name() {
1208 | 	[[ $# -eq 1 ]] || return 1
1209 | 	local option=$1
1210 | 	local ident=$(argsparse_option_to_identifier "$option")
1211 | 	printf "cumulated_values_%s" "$ident"
1212 | }
1213 | 
1214 | ## @fn argsparse_set_cumulative_option()
1215 | ## @brief "cumulative" property specific option-setting hook.
1216 | ## @details Default action to take for cumulative options. Store @a
1217 | ## value into an array whose name is generated using
1218 | ## argsparse_get_cumulative_array_name().
1219 | ## @param option an option name.
1220 | ## @param value the value put on command line for given option.
1221 | ## @ingroup ArgsparseOptionSetter
1222 | argsparse_set_cumulative_option() {
1223 | 	[[ $# -eq 2 ]] || return 1
1224 | 	local option=$1
1225 | 	local value=$2
1226 | 	local array="$(argsparse_get_cumulative_array_name "$option")"
1227 | 	local size temp="$array[@]"
1228 | 	local -a copy
1229 | 	if __argsparse_has_array_item "$array" 0
1230 | 	then
1231 | 		copy=( "${!temp}" )
1232 | 		size=${#copy[@]}
1233 | 	else
1234 | 		size=0
1235 | 	fi
1236 | 	printf -v "$array[$size]" %s "$value"
1237 | 	argsparse_set_option_without_value "$option"
1238 | }
1239 | 
1240 | ## @fn argsparse_set_cumulativeset_option()
1241 | ## @param option an option name.
1242 | ## @param value a new value for the option.
1243 | ## @brief "cumulativeset" property specific option-setting hook.
1244 | ## @details Default action to take for cumulativeset options. Act
1245 | ## exactly like argsparse_set_cumulative_option() except that values
1246 | ## are not duplicated in the cumulated values array.
1247 | ## @ingroup ArgsparseOptionSetter
1248 | argsparse_set_cumulativeset_option() {
1249 | 	[[ $# -eq 2 ]] || return 1
1250 | 	local option=$1
1251 | 	local value=$2
1252 | 	local array_name="$(argsparse_get_cumulative_array_name "$option")"
1253 | 	local array="$array_name[@]"
1254 | 	if ! __argsparse_has_array_item "$array_name" || \
1255 | 		   ! __argsparse_index_of "$value" "${!array}" >/dev/null
1256 | 	then
1257 | 		# The value is not already in the array, so add it.
1258 | 		argsparse_set_cumulative_option "$option" "$value"
1259 | 	fi
1260 | }
1261 | 
1262 | ## @fn argsparse_set_alias()
1263 | ## @param option an option name.
1264 | ## @brief "alias" property specific option-setting hook.
1265 | ## @details When an option is an alias for other option(s), then set
1266 | ## the aliases options.
1267 | ## @ingroup ArgsparseOptionSetter
1268 | argsparse_set_alias() {
1269 | 	# This option will set all options aliased by another.
1270 | 	[[ $# -eq 1 ]] || return 1
1271 | 	local option=$1
1272 | 	local aliases
1273 | 	if ! aliases="$(argsparse_has_option_property "$option" alias)"
1274 | 	then
1275 | 		return 1
1276 | 	fi
1277 | 	while [[ "$aliases" =~ ^\ *([^\ ]+)(\ (.+))?\ *$ ]]
1278 | 	do
1279 | 		# At this point, BASH_REMATCH[1] is the first alias, and
1280 | 		# BASH_REMATCH[3] is the maybe-empty list of other aliases.
1281 | 		# __argsparse_set_option will alter BASH_REMATCH, so modify
1282 | 		# aliases first.
1283 | 		aliases=${BASH_REMATCH[3]}
1284 | 		__argsparse_set_option "${BASH_REMATCH[1]}"
1285 | 	done
1286 | }
1287 | 
1288 | 
1289 | ## @fn argsparse_set_option()
1290 | ## @brief Default option-setting hook.
1291 | ## @param option The option being set.
1292 | ## @param value the value of the option (optional).
1293 | ## @details This function will be called by argsparse_parse_options()
1294 | ## whenever a given option is being set and no custom setting hook is
1295 | ## defined for said option. Depending of the properties of the option,
1296 | ## a more specific setting hook will be called.
1297 | ## @ingroup ArgsparseOptionSetter
1298 | argsparse_set_option() {
1299 | 	[[ $# -eq 2 || $# -eq 1 ]] || return 1
1300 | 	local option=$1
1301 | 	if [[ $# -eq 2 ]]
1302 | 	then
1303 | 		local value=$2
1304 | 	fi
1305 | 	local property
1306 | 	local -A setters=(
1307 | 		[cumulative]=argsparse_set_cumulative_option
1308 | 		[cumulativeset]=argsparse_set_cumulativeset_option
1309 | 		[value]=argsparse_set_option_with_value
1310 | 	)
1311 | 
1312 | 	if ! argsparse_set_alias "$option"
1313 | 	then
1314 | 		# We dont use ${!setters[@]} here, because order matters.
1315 | 		for property in cumulative cumulativeset value
1316 | 		do
1317 | 			if argsparse_has_option_property "$option" "$property"
1318 | 			then
1319 | 				"${setters[$property]}" "$option" "$value"
1320 | 				return
1321 | 			fi
1322 | 		done
1323 | 		argsparse_set_option_without_value "$option"
1324 | 	fi
1325 | }
1326 | 
1327 | 
1328 | # Default behaviour is not to accept empty command lines.
1329 | __argsparse_allow_no_argument=no
1330 | 
1331 | 
1332 | ## @fn argsparse_allow_no_argument()
1333 | ## @brief Allow empty command lines to run.
1334 | ## @details Change argsparse behaviour for empty command
1335 | ## lines. Default says "no argument triggers usage".
1336 | ## @param string if (case-insensitive) "yes", "true" or "1", the value
1337 | ## is considered as affirmative. Anything else is a negative value.
1338 | ## @retval 0 unless there's more than one parameter (or none).
1339 | ## @ingroup ArgsparseParameter
1340 | argsparse_allow_no_argument() {
1341 | 	[[ $# -eq 1 ]] || return 1
1342 | 	local param=$1
1343 | 	case "${param,,}" in
1344 | 		yes|true|1)
1345 | 			__argsparse_allow_no_argument=yes
1346 | 			;;
1347 | 		*)
1348 | 			__argsparse_allow_no_argument=no
1349 | 			;;
1350 | 	esac
1351 | }
1352 | 
1353 | 
1354 | ## @brief Internal use only.
1355 | ## @details The default minimum parameters requirement for command line.
1356 | ## @ingroup ArgsparseParameter
1357 | declare -i __argsparse_minimum_parameters=0
1358 | 
1359 | 
1360 | ## @brief Internal use only.
1361 | ## @details The default maximum parameters requirement for command
1362 | ## line. "Should be enough for everyone".
1363 | ## @ingroup ArgsparseParameter
1364 | declare -i __argsparse_maximum_parameters=1000000
1365 | 
1366 | 
1367 | ## @fn argsparse_minimum_parameters()
1368 | ## @brief Set the minimum number of non-option parameters expected on
1369 | ## the command line.
1370 | ## @param unsigned_int a positive number.
1371 | ## @retval 0 if there is an unsigned integer is provided and is the
1372 | ## single parameter of this function.
1373 | ## @retval 1 in other cases.
1374 | ## @ingroup ArgsparseParameter
1375 | argsparse_minimum_parameters() {
1376 | 	[[ $# -eq 1 ]] || return 1
1377 | 	local min=$1
1378 | 	[[ "$min" = +([0-9]) ]] || return 1
1379 | 	__argsparse_minimum_parameters=$min
1380 | }
1381 | 
1382 | ## @fn argsparse_maximum_parameters()
1383 | ## @brief Set the maximum number of non-option parameters expected on
1384 | ## the command line.
1385 | ## @param unsigned_int a positive number.
1386 | ## @retval 0 if there is an unsigned integer is provided and is the
1387 | ## single parameter of this function.
1388 | ## @retval 1 in other cases.
1389 | ## @ingroup ArgsparseParameter
1390 | argsparse_maximum_parameters() {
1391 | 	[[ $# -eq 1 ]] || return 1
1392 | 	local max=$1
1393 | 	[[ "$max" = +([0-9]) ]] || return 1
1394 | 	__argsparse_maximum_parameters=$max
1395 | }
1396 | 
1397 | 
1398 | ## @var String __argsparse_environment_variable_prefix
1399 | ## @brief The prefix for option-setting environment variables
1400 | ## @private
1401 | ## @ingroup ArgsparseOptionSetter
1402 | declare __argsparse_environment_variable_prefix
1403 | 
1404 | 
1405 | ## @fn argsparse_use_environment_variables()
1406 | ## @brief Enable option setting through environment variables.
1407 | ## @details
1408 | ## Once enabled, it cannot be disabled.
1409 | ## @param prefix an environment variable prefix
1410 | ## @ingroup ArgsparseOptionSetter
1411 | argsparse_use_environment_variables() {
1412 | 	local prefix
1413 | 	case $# in
1414 | 		0)
1415 | 			prefix=$(argsparse_option_to_identifier "${argsparse_pgm%.sh}")
1416 | 			prefix=${prefix^^}
1417 | 			;;
1418 | 		1)
1419 | 			prefix=$1
1420 | 			;;
1421 | 		*)
1422 | 			return 1
1423 | 	esac
1424 | 	__argsparse_environment_variable_prefix=$prefix
1425 | }
1426 | 
1427 | 
1428 | ## @fn argsparse_are_environment_variables_enabled()
1429 | ## @brief Tell if option setting through environment variables is
1430 | ## enabled or not.
1431 | ## @details
1432 | ## @retval 0 if argsparse_parse_options would also retrieve option
1433 | ## values from environment variables.
1434 | ## @ingroup @ArgsparseOptionSetter
1435 | argsparse_are_environment_variables_enabled() {
1436 | 	[[ ${__argsparse_environment_variable_prefix:-} ]]
1437 | }
1438 | 
1439 | 
1440 | ## @fn argsparse_option_environment_variable_name()
1441 | ## @brief Give the environment variable name linked to an option
1442 | ## @details
1443 | ## Return the name of the environment variable name that can be used
1444 | ## to set a given option. Works whether option setting through
1445 | ## environment variables is enabled or not.
1446 | ## @param option an option name
1447 | ## @return the environment variable name linked to the option
1448 | argsparse_option_environment_variable_name() {
1449 | 	[[ $# -eq 1 ]] || return 1
1450 | 	local option=$1
1451 | 	local identifier=$(argsparse_option_to_identifier "$option")
1452 | 	printf %s_%s "$__argsparse_environment_variable_prefix" "${identifier^^}"
1453 | }
1454 | 
1455 | 
1456 | ## @fn argsparse_option_environment_variable()
1457 | ## @brief Give the content of the environment variable that can be
1458 | ## used to set a given option.
1459 | ## @details
1460 | ## Does not check if option setting through environment variable is
1461 | ## enabled or not.
1462 | ## @param option An option name
1463 | ## @return The content of the environment variable that matches the
1464 | ## given option.
1465 | ## @retval 0 if the variable that matches the given option actually
1466 | ## exists (even if its value is empty)
1467 | argsparse_option_environment_variable() {
1468 | 	[[ $# -eq 1 ]] || return 1
1469 | 	local option=$1
1470 | 	local var=$(argsparse_option_environment_variable_name "$option")
1471 | 	if [[ -v $var ]]; then
1472 | 		printf %s "${!var}"
1473 | 		return 0
1474 | 	fi
1475 | 	return 1
1476 | }
1477 | 
1478 | 
1479 | ## @fn argsparse_set_option_from_environment_value()
1480 | ## @brief Give a value to an option, from environment variable value.
1481 | ## @details
1482 | ## Options can be set from environment variables, and in some cases,
1483 | ## those values have special meanings:
1484 | ## - 0, "false", "no" and the empty string are explicit values to
1485 | ## disable a non-valued option
1486 | ## - (probably more to come)
1487 | ## .
1488 | ## @param option an option name
1489 | ## @param value the value, as found in the process environment, to set
1490 | ## the option to.
1491 | argsparse_set_option_from_environment_value() {
1492 | 	[[ $# -eq 2 ]] || return 1
1493 | 	local option=$1
1494 | 	local value=$2
1495 | 	if ! argsparse_has_option_property "$option" value
1496 | 	then
1497 | 		if [[ $value != +(0|false|no|"") ]]
1498 | 		then
1499 | 			argsparse_set_option "$option"
1500 | 		fi
1501 | 	# There should be an elif statement here, if we want to consider
1502 | 	# cumulated options differently.
1503 | 	else
1504 | 		argsparse_set_option "$option" "$value"
1505 | 	fi
1506 | }
1507 | 
1508 | 
1509 | ## @fn __argsparse_parse_options_env_and_defaults()
1510 | ## @brief set options from environment and from default values.
1511 | ## @details
1512 | ## For every option that have not been set from command line, look for
1513 | ## a matching environment variable (when
1514 | ## argsparse_are_environment_variables_enabled() is true) and apply
1515 | ## default values right after if still left unset.
1516 | ## @private
1517 | __argsparse_parse_options_env_and_defaults() {
1518 | 	local option value
1519 | 	for option in "${!__argsparse_options_descriptions[@]}"
1520 | 	do
1521 | 		if ! argsparse_is_option_set "$option"
1522 | 		then
1523 | 			if argsparse_are_environment_variables_enabled &&
1524 | 					value=$(argsparse_option_environment_variable "$option")
1525 | 			then
1526 | 				argsparse_set_option_from_environment_value "$option" "$value"
1527 | 			elif __argsparse_has_array_item \
1528 | 					 __argsparse_options_default_values "$option"
1529 | 			then
1530 | 				 argsparse_set_option "$option" \
1531 | 					"${__argsparse_options_default_values[$option]}"
1532 | 			fi
1533 | 		fi
1534 | 	done
1535 | }
1536 | 
1537 | 
1538 | ## @var AssociativeArray program_options
1539 | ## @brief Options values.
1540 | ## @details
1541 | ## After argsparse_parse_options(), it will contain (if no hook is set
1542 | ## for "optionname")
1543 | ## - "optionname" -> "value", if "optionname" accepts a value.
1544 | ## - "optionname" -> "how many times the option has been detected on
1545 | ## .
1546 | ## the command line", else.
1547 | declare -A program_options=()
1548 | 
1549 | 
1550 | ## @var Array program_params
1551 | ## @brief Positionnal parameters of the script
1552 | ## @details
1553 | ## After argsparse_parse_options(), it will contain all non-option
1554 | ## parameters. (Typically, everything found after the '--')
1555 | declare -a program_params=()
1556 | 
1557 | 
1558 | ## @var AssociativeArray __argsparse_tmp_identifiers
1559 | ## @private
1560 | ## @brief Internal use
1561 | ## @details
1562 | ## Used to verify declared options do not conflict. Is unset after
1563 | ## argsparse_parse_options() being called.
1564 | declare -A __argsparse_tmp_identifiers=()
1565 | 
1566 | 
1567 | __argsparse_check_requires() {
1568 | 	# @return the number of missing option detected, but this function
1569 | 	# actually stops are the first failing *list* of dependencies.
1570 | 	local option
1571 | 	local requirestring require count=0
1572 | 	local -a requires
1573 | 	for option in "${!program_options[@]}"
1574 | 	do
1575 | 		if ! requirestring="$(argsparse_has_option_property "$option" require)"
1576 | 		then
1577 | 			# No requirement for this option.
1578 | 			continue
1579 | 		fi
1580 | 		read -a requires <<<"$requirestring"
1581 | 		for require in "${requires[@]}"
1582 | 		do
1583 | 			if ! argsparse_is_option_set "$require"
1584 | 			then
1585 | 				printf >&2 "%s: --%s: requires option --%s.\n" \
1586 | 					"$argsparse_pgm" "$option" "$require"
1587 | 				: $((count++))
1588 | 			fi
1589 | 		done
1590 | 		[[ "$count" -ne 0 ]] && return "$count"
1591 | 	done
1592 | 	return 0
1593 | }
1594 | 
1595 | __argsparse_check_missing_options() {
1596 | 	# @retval 0 if all mandatory options have a value in
1597 | 	# program_options associative array.
1598 | 	local option count=0
1599 | 	for option in "${!__argsparse_options_descriptions[@]}"
1600 | 	do
1601 | 		argsparse_has_option_property "$option" mandatory || continue
1602 | 		# If option has been given, just iterate.
1603 | 		argsparse_is_option_set "$option" && continue
1604 | 		printf >&2 "%s: --%s: option is mandatory.\n" \
1605 | 			"$argsparse_pgm" "$option"
1606 | 		: $((count++))
1607 | 	done
1608 | 	[[ "$count" -eq 0 ]]
1609 | }
1610 | 
1611 | 
1612 | __argsparse_parse_options_prepare_exclude() {
1613 | 	# Check for all "exclude" properties, and fill "exclusions"
1614 | 	# associative array, which should have been declared in
1615 | 	# __argsparse_parse_options_no_usage.
1616 | 	local option exclude excludestring
1617 | 	local -a excludes
1618 | 	for option in "${!__argsparse_options_descriptions[@]}"
1619 | 	do
1620 | 		excludestring=$(argsparse_has_option_property "$option" exclude) || \
1621 | 			continue
1622 | 		exclusions["$option"]+="${exclusions["$option"]:+ }$excludestring"
1623 | 		# Re-split the string. (without involving anything else)
1624 | 		read -a excludes <<<"$excludestring"
1625 | 		for exclude in "${excludes[@]}"
1626 | 		do
1627 | 			exclusions["$exclude"]+="${exclusions["$exclude"]:+ }$option"
1628 | 		done
1629 | 	done
1630 | }
1631 | 
1632 | 
1633 | __argsparse_parse_options_check_exclusions() {
1634 | 	# Check if two options presents on the command line are mutually
1635 | 	# exclusive. Prints the "other" option if it's the case.
1636 | 	# @param an option
1637 | 	# @return 0 if the given option has actually excluded by annother
1638 | 	# already-given option.
1639 | 	[[ $# -eq 1 ]] || return 1
1640 | 	local new_option=$1
1641 | 	local option
1642 | 
1643 | 	for option in "${!program_options[@]}"
1644 | 	do
1645 | 		if [[ "${exclusions["$option"]-}" =~ ^(.* )?"$new_option"( .*)?$ ]]
1646 | 		then
1647 | 			printf %s "$option"
1648 | 			return 0
1649 | 		fi
1650 | 	done
1651 | 	return 1
1652 | }
1653 | 
1654 | 
1655 | ## @fn __argsparse_set_option()
1656 | ## @private
1657 | ## @brief Resolv option-specific setter function and invoke it.
1658 | ## @details Check if a user-defined option setting function
1659 | ## (set_option_<optionname>) has been defined or if the generic
1660 | ## argsparse_set_option() function is to be used. Then invoke the that
1661 | ## function with the option name as first parameter. If a value for
1662 | ## the option is involved, it is passed as a second parameter.
1663 | ## @param option an option name.
1664 | ## @return the setter function return code
1665 | ## @ingroup ArgsparseOptionSetter
1666 | __argsparse_set_option() {
1667 | 	[[ $# -eq 1 || $# -eq 2 ]] || return 1
1668 | 	local option=$1
1669 | 	local set_hook identifier
1670 | 	[[ $# -ne 2 ]] || local value=$2
1671 | 	# The "identifier string" matching next_param, suitable for
1672 | 	# variable or function names.
1673 | 	identifier="$(argsparse_option_to_identifier "$option")"
1674 | 	# If user has defined a specific setting hook for given the
1675 | 	# option, then use it, else use default standard
1676 | 	# option-setting function.
1677 | 	if declare -f "set_option_$identifier" >/dev/null 2>&1
1678 | 	then
1679 | 		set_hook="set_option_$identifier"
1680 | 	else
1681 | 		set_hook=argsparse_set_option
1682 | 	fi
1683 | 	# Invoke setting hook, and if it returns some non-zero status,
1684 | 	# send the user back to usage, if declared, and return with error.
1685 | 	# The specific $value substitution, here, is to distinguish an
1686 | 	# empty value from a no-value.
1687 | 	"$set_hook" "$option" ${value+"$value"}
1688 | }
1689 | 
1690 | 
1691 | ## @fn __argsparse_parse_options_valuecheck()
1692 | ## @private
1693 | ## @brief Check a value given to an option.
1694 | ## @details If an enumeration has been defined for the option, check
1695 | ## against that. If there's no enumeration, but option has a type
1696 | ## property, then check against the type. In the end, check against
1697 | ## check_value_of_<option> function, if it's been defined.
1698 | ## @param option an option name.
1699 | ## @param value anything.
1700 | ## @retval 0 if value is correct for given option.
1701 | ## @ingroup ArgsparseOptionTyping
1702 | __argsparse_parse_options_valuecheck() {
1703 | 	[[ $# -eq 2 ]] || return 1
1704 | 	local option=$1
1705 | 	local value=$2
1706 | 	local identifier possible_values option_type
1707 | 	identifier="$(argsparse_option_to_identifier "$option")"
1708 | 	if possible_values=$(__argsparse_values_array_identifier "$option")
1709 | 	then
1710 | 		__argsparse_index_of "$value" "${!possible_values}" >/dev/null || \
1711 | 			return 1
1712 | 	elif option_type=$(argsparse_has_option_property "$option" type)
1713 | 	then
1714 | 		argsparse_check_option_type "$option_type" "$value" || return 1
1715 | 	fi
1716 | 	if declare -f "check_value_of_$identifier" >/dev/null 2>&1
1717 | 	then
1718 | 		"check_value_of_$identifier" "$value" || return 1
1719 | 	fi
1720 | 	return 0
1721 | }
1722 | 
1723 | 
1724 | ## @fn __argsparse_parse_options_no_usage()
1725 | ## @brief Parse options without triggering usage
1726 | __argsparse_parse_options_no_usage() {
1727 | 	# This function re-set program_params array values. This function
1728 | 	# will also modify the program_options associative array.
1729 | 	# If any error happens, this function will return 1.
1730 | 
1731 | 	# Be careful, the function is (too) big.
1732 | 
1733 | 	local long short getopt_temp next_param set_hook option_type
1734 | 	local next_param_identifier exclude value char
1735 | 	local -a longs_array
1736 | 	local -A exclusions
1737 | 	# The getopt parameters.
1738 | 	local longs shorts option
1739 | 
1740 | 	# No argument sends back to usage, if defined.
1741 | 	if [[ $# -eq 0 && "$__argsparse_allow_no_argument" != yes ]]
1742 | 	then
1743 | 		return 1
1744 | 	fi
1745 | 
1746 | 	# 1. Analyze declared options to create getopt valid arguments.
1747 | 	for long in "${!__argsparse_options_descriptions[@]}"
1748 | 	do
1749 | 		if argsparse_has_option_property "$long" value
1750 | 		then
1751 | 			longs_array+=( "$long:" )
1752 | 		else
1753 | 			longs_array+=( "$long" )
1754 | 		fi
1755 | 	done
1756 | 
1757 | 	# 2. Create the long options string.
1758 | 	longs="$(__argsparse_join_array , "${longs_array[@]}")"
1759 | 
1760 | 	# 3. Create the short option string.
1761 | 	for short in "${!__argsparse_short_options[@]}"
1762 | 	do
1763 | 		if argsparse_has_option_property \
1764 | 			"${__argsparse_short_options[$short]}" value
1765 | 		then
1766 | 			shorts+="$short:"
1767 | 		else
1768 | 			shorts+=$short
1769 | 		fi
1770 | 	done
1771 | 
1772 | 	# 4. Invoke getopt and replace arguments.
1773 | 	if ! getopt_temp=$("${ARGSPARSE_GNU_GETOPT}" -s bash -n "$argsparse_pgm" \
1774 | 		--longoptions="$longs" "$shorts" "$@")
1775 | 	then
1776 | 		# Syntax error on the command implies returning with error.
1777 | 		return 1
1778 | 	fi
1779 | 	eval set -- "$getopt_temp"
1780 | 
1781 | 	# 5. Prepare exclusions stuff.
1782 | 	__argsparse_parse_options_prepare_exclude
1783 | 
1784 | 	# 6. Arguments parsing is really made here.
1785 | 	while [[ $# -ge 1 ]]
1786 | 	do
1787 | 		next_param=$1
1788 | 		shift
1789 | 		# The regular exit case.
1790 | 		if [[ "$next_param" = -- ]]
1791 | 		then
1792 | 			# Check how many parameters we have and if it's at least
1793 | 			# what we expects.
1794 | 			if [[ $# -lt "$__argsparse_minimum_parameters" ]]
1795 | 			then
1796 | 				printf >&2 \
1797 | 					"%s: not enough parameters (at least %d expected, %d provided)\n" \
1798 | 					"$argsparse_pgm" "$__argsparse_minimum_parameters" $#
1799 | 				return 1
1800 | 			elif [[ $# -gt "$__argsparse_maximum_parameters" ]]
1801 | 			then
1802 | 				printf >&2 \
1803 | 					"%s: too many parameters (maximum allowed is %d, %d provided)\n" \
1804 | 					"$argsparse_pgm" "$__argsparse_maximum_parameters" $#
1805 | 				return 1
1806 | 			fi
1807 | 			# Save program parameters in array
1808 | 			program_params=( "$@" )
1809 | 
1810 | 			# Retrieve values from environment and set matching options
1811 | 			__argsparse_parse_options_env_and_defaults
1812 | 
1813 | 			# If some mandatory option have been omited by the user, then
1814 | 			# print some error, and invoke usage.
1815 | 			# Also checks requires chains.
1816 | 			__argsparse_check_missing_options && __argsparse_check_requires
1817 | 			return
1818 | 		fi
1819 | 		# If a short option was given, then we first convert it to its
1820 | 		# matching long name.
1821 | 		if [[ "$next_param" = -[!-] ]]
1822 | 		then
1823 | 			char=${next_param#-}
1824 | 			if ! next_param=$(argsparse_short_to_long "$char")
1825 | 			then
1826 | 				# Short option without equivalent long. According to
1827 | 				# current implementation, this should be considered as
1828 | 				# a bug.
1829 | 				printf >&2 \
1830 | 					"%s: -%s: option doesnt have any matching long option." \
1831 | 					"$argsparse_pgm" "$char"
1832 | 				return 1
1833 | 			fi
1834 | 		else
1835 | 			# Wasnt a short option. Just strip the leading dash.
1836 | 			next_param=${next_param#--}
1837 | 		fi
1838 | 		if exclude=$(__argsparse_parse_options_check_exclusions "$next_param")
1839 | 		then
1840 | 			printf >&2 \
1841 | 				"%s: %s: option excluded by other option (%s).\n" \
1842 | 				"$argsparse_pgm" "$next_param" "$exclude"
1843 | 			return 1
1844 | 		fi
1845 | 		# Set option value, if there should be one.
1846 | 		if argsparse_has_option_property "$next_param" value
1847 | 		then
1848 | 			value=$1
1849 | 			shift
1850 | 			if ! __argsparse_parse_options_valuecheck "$next_param" "$value"
1851 | 			then
1852 | 				printf >&2 "%s: %s: Invalid value for option %s.\n" \
1853 | 					"$argsparse_pgm" "$value" "$next_param"
1854 | 				return 1
1855 | 			fi
1856 | 		fi
1857 | 		# Invoke setting hook, and if it returns returns some non-zero
1858 | 		# status, send the user back to usage, if declared, and return
1859 | 		# with error.
1860 | 		# The specific $value substitution, here, is to distinguish an
1861 | 		# empty value from a no-value.
1862 | 		if ! __argsparse_set_option "$next_param" ${value+"$value"}
1863 | 		then
1864 | 			printf >&2 "%s: %s: Invalid value for %s option.\n" \
1865 | 				"$argsparse_pgm" "$value" "$next_param"
1866 | 			return 1
1867 | 		fi
1868 | 		unset value
1869 | 	done
1870 | 	return 0
1871 | }
1872 | 
1873 | if [[ ${ARGSPARSE_COMPLETION_MODE-} ]]
1874 | then
1875 | 	shopt progcomp expand_aliases >/dev/null || exit 1
1876 | 	alias argsparse_parse_options='return 0 2>/dev/null || :'
1877 | else
1878 | ## @fn argsparse_parse_options()
1879 | ## @brief Parse program options.
1880 | ## @details This function will make option parsing happen, and if an error
1881 | ## is detected, the usage() function will be invoked, if it has been
1882 | ## defined. If it's not defined, the function will return 1.
1883 | ## Parse options, and return if everything went fine.
1884 | ## @param parameters... should be the program arguments.
1885 | ## @retval 0 if the whole option parsing process went fine.
1886 | ## @retval 1 if an error is encoutered and usage does not perform an exit.
1887 | argsparse_parse_options() {
1888 | 		unset __argsparse_tmp_identifiers || :
1889 | 		__argsparse_parse_options_no_usage "$@" && return
1890 | 		# Something went wrong, invoke usage function, if defined.
1891 | 		declare -f usage >/dev/null 2>&1 && usage
1892 | 		return 1
1893 | }
1894 | fi
1895 | 
1896 | 
1897 | ## @fn argsparse_is_option_set()
1898 | ## @brief Return True if an option has been set on the command line.
1899 | ## @param option an option name.
1900 | ## @retval 0 if given option has been set on the command line.
1901 | argsparse_is_option_set() {
1902 | 	[[ $# -eq 1 ]] || return 1
1903 | 	local option=$1
1904 | 	[[ -n "${program_options[$option]+yes}" ]]
1905 | }
1906 | 
1907 | ## @fn argsparse_report()
1908 | ## @brief Prints a basic report of all passed options
1909 | ## @details Kinda useful for a --debug, or a --verbose option,
1910 | ## this function will print options and their values.
1911 | ## @param option... A list of option name. If omitted all options
1912 | ## will be displayed.
1913 | ## @retval 0
1914 | argsparse_report() {
1915 | 	local option array_name value
1916 | 	local length=$(__argsparse_max_length "${!__argsparse_options_descriptions[@]}")
1917 | 	local -a array options
1918 | 
1919 | 	if __argsparse_is_array_declared __argsparse_tmp_identifiers
1920 | 	then
1921 | 		# The test is a bit hacky, but it avoids implementing another
1922 | 		# mechanism.
1923 | 		printf "argsparse_parse_option was not ran yet.\n"
1924 | 	fi
1925 | 
1926 | 	if [[ $# -eq 0 ]]
1927 | 	then
1928 | 		options=( "${!__argsparse_options_descriptions[@]}" )
1929 | 	else
1930 | 		options=( "$@" )
1931 | 	fi
1932 | 	for option in "${options[@]}"
1933 | 	do
1934 | 		argsparse_has_option_property "$option" hidden && continue
1935 | 		printf "%- ${length}s\t: " "$option"
1936 | 		if argsparse_is_option_set "$option"
1937 | 		then
1938 | 			printf "yes (%s" "${program_options[$option]}"
1939 | 			if argsparse_has_option_property "$option" cumulative || \
1940 | 				argsparse_has_option_property "$option" cumulativeset
1941 | 			then
1942 | 				array_name="$(argsparse_get_cumulative_array_name "$option")[@]"
1943 | 				array=( "${!array_name}" )
1944 | 				printf ' time(s):'
1945 | 				for value in "${array[@]}"
1946 | 				do
1947 | 					printf ' %q' "$value"
1948 | 				done
1949 | 			fi
1950 | 			printf ')\n'
1951 | 		else
1952 | 			printf 'no\n'
1953 | 		fi
1954 | 	done
1955 | }
1956 | 
1957 | 
1958 | ## @fn usage()
1959 | ## @brief Default usage function.
1960 | ## @details The default usage function. By default, it will be called
1961 | ## by argsparse_parse_options() on error or if --help option provided by
1962 | ## user on the command line. It can easily be overwritten if it does not
1963 | ## suits your needs.
1964 | ## @return This function makes an @b exit with code 1
1965 | ## @ingroup ArgsparseUsage
1966 | usage() {
1967 | 	argsparse_usage
1968 | 	exit 1
1969 | }
1970 | 
1971 | ## @fn set_option_help()
1972 | ## @brief Default trigger for --help option.
1973 | ## @details Will actually only call usage().
1974 | ## @return Whatever usage() returns.
1975 | ## @ingroup ArgsparseUsage
1976 | set_option_help() {
1977 | 	# This is the default hook for the --help option.
1978 | 	usage
1979 | }
1980 | 
1981 | # We do define a default --help option.
1982 | argsparse_use_option "=help" "Show this help message"
1983 | 
1984 | 
1985 | return 0 >/dev/null 2>&1 ||:
1986 | 
1987 | printf "The %s file is not a standalone program. It's a shell library.\n" \
1988 | 	"$argsparse_pgm"
1989 | printf "%s\n" \
1990 | 	"To use it, you have to load it in your own bash" \
1991 | 	"shell scripts using the following line:"
1992 | printf "\n. %q\n\n" "$0"
1993 | 


--------------------------------------------------------------------------------