Commit 753f7ed6 authored by Emeric Verschuur's avatar Emeric Verschuur

add documentation and example

parent 2269b70d
# BashOpts
BashOpts is a helper to manage easily options, command line arguments and settings in a bash sell script.
## Global usage
There are mainly 5 steps:
- Load the library with ```source bashopts.sh```
- Setup bashopts with ```bashopts_setup``` function
- Declare options/arguments with ```bashopts_declare``` (one call per option)
- Parse arguments with ```bashopts_parse_args```
- Process arguments with ```bashopts_process_args```
### Load the library
Load all the function from the ```bashopts.sh``` file and you can add the line ```trap 'bashopts_exit_handle' ERR``` to display backtrace on error
Code example:
```bash
$ . bashopts.sh #load the BashOpts environment
```
### Setup BashOpts
Setup BashOpts environment with ```bashopts_setup```
bashopts_setup option list:
- ```-n <val>```: Tool name
- ```-d <val>```: Tool description
- ```-u <val>```: Tool usage (optional)
- ```-s <val>```: Define a setting file path (optional)
- ```-f```: Force edition for interactive options (default: a prompt is displayed only if not given via the command line)
Code example:
```bash
$ bashopts_setup -n "myapp" -d "This is myapp tool description displayed on help message"
```
### Option declarations
Declare each options and associated settings like name, arguments, etc. with ```bashopts_declare```
bashopts_declare option list:
- ```-n <val>```: Option/variable name (all option value will be stored into $<variable name>)
- ```-v <val>```: Default value
- ```-e <val>```: Bash expression: like default but this expression is computed on time and can contain variables and other bash expression
- ```-o <val>```: Short option name (one character, e.g.: 'h' for -h argument)
- ```-l <val>```: Long option (several characters, e.g.: 'my-opt' for --my-opt argument)
- ```-d <val>```: Option description
- ```-t <val>```: Value type: string, number, boolean (default)
- ```-m <val>```: Method: set (DEFAULT: simple value where $<variable name> will be a simple value), add (list with several values where $<variable name> will be a bash array)
- ```-r```: Value required
- ```-i```: Enable interactive edition
- ```-s```: Store this in setting"
Code example:
```bash
$ bashopts_declare -n base_path -l base -o b -d "Base path" -t string -v "/opt/test" -i -s
$ bashopts_declare -n config_path -l config -o c -d "Configuration path" -t string -e "\$base_path/myconf.cfg" -i -s
```
### Argument parsing
Parse command line arguments with ```bashopts_parse_args```
This function will only extract and check arguments given by the command line.
bashopts_parse_args usage:
```bash
bashopts_parse_args <arguments...>
```
Code example:
```bash
bashopts_parse_args $@
```
### Argument processing
Process all the options with ```bashopts_process_args```
This function will fill all options values using the following order:
- Value from the command line
- Value from the settings file (if the ```bashopts_declare -s``` is specified)
- Value from the input prompt (if the ```bashopts_declare -i``` is specified)
- Value from the bash expression (if the ```bashopts_declare -e``` is specified)
- The default option value (may be defined with the ```bashopts_declare -v```)
bashopts_process_args usage:
```bash
bashopts_process_args
```
## Example
```bash
#!/bin/bash -e
# load the library
. bashopts.sh
# Enable backtrace dusplay on error
trap 'bashopts_exit_handle' ERR
# Initialize the library
bashopts_setup -n "$0" -d "This is myapp tool description displayed on help message" -s "$HOME/.config/myapprc"
# Declare the options
bashopts_declare -n first_name -l first -o f -d "First name" -t string -i -s -r
bashopts_declare -n last_name -l last -o l -d "Last name" -t string -i -s -r
bashopts_declare -n display_name -l display-name -t string -d "Display name" -e "\$first_name \$last_name"
bashopts_declare -n age -l number -d "Age" -t number
bashopts_declare -n email_list -t string -m add -l email -d "Email adress"
# Parse arguments
bashopts_parse_args $@
# Process argument
bashopts_process_args
# Display the values
echo
echo "First name: $first_name"
echo "Last name: $last_name"
echo "Display name: $display_name"
echo "Age: $age"
for email in ${email_list[@]}; do
echo "Email: $email"
done
```
Display the help:
```bash
$ ./example.sh --help
```
Output:
```
NAME:
./example.sh - This is myapp tool description displayed on help message
USAGE:
[options and commands] [-- [extra args]]
OPTIONS:
-h,--help Display this help
-n,--non-interactive Non interactive mode - boolean bashopts_non_interactive=true (default:false)
-f,--first First name - string first_name="John" (default:"")
-l,--last Last name - string last_name="Smith" (default:"")
--display-name Display name - string display_name="John Smith" (default:"$first_name $last_name")
--number Age - number age=0 (default:0)
--email Email adress - string email_list="" (default:"")
```
Test with arguments:
```bash
$ ./example.sh --first "John" --email john@example.com --email john.smith@example.com
```
Output:
```
* Last name
[]: Smith
First name: John
Last name: Smith
Display name: John Smith
Age: 0
Email: john@example.com
Email: john.smith@example.com
```
......@@ -19,7 +19,7 @@
set -e
function errexit() {
function bashopts_exit_handle() {
local err=$?
set +o xtrace
local code="${1:-1}"
......@@ -39,7 +39,7 @@ function errexit() {
# trap ERR to provide an error handler whenever a command exits nonzero
# this is a more verbose version of set -o errexit
trap 'errexit' ERR
trap 'bashopts_exit_handle' ERR
# setting errtrace allows our ERR trap handler to be propagated to functions,
# expansions and subshells
set -o errtrace
......@@ -138,16 +138,16 @@ bashopts_setup() {
fi
bashopts_tool_usage=${bashopts_tool_usage:-"[options and commands] [-- [extra args]]"}
if [ "$no_default_opts" != "true" ]; then
bashopts_add -n __bashopts_display_help__ -l help -o h -d "Display this help"
bashopts_add -n bashopts_non_interactive -l non-interactive -o n -d "Non interactive mode"
bashopts_declare -n __bashopts_display_help__ -l help -o h -d "Display this help"
bashopts_declare -n bashopts_non_interactive -l non-interactive -o n -d "Non interactive mode"
fi
}
# STEP 2: add options
bashopts_add() {
bashopts_declare() {
local arg arglist options
if ! arglist=$(getopt -o "n:v:e:o:l:d:t:m:rsi" -n "$0 " -- "$@"); then
bashopts_error "Usage bashopts_add:" \
bashopts_error "Usage bashopts_declare:" \
" -n <val> Name" \
" -v <val> Default value" \
" -e <val> Bash expression: like default but this expression is computed and can contain variables and other bash expression" \
......@@ -156,7 +156,7 @@ bashopts_add() {
" -d <val> Description" \
" -t <val> Value type: string (default), number, boolean" \
" -m <val> Method: set (DEFAULT: simple value), add (list with several values)" \
" -r Value required required" \
" -r Value required" \
" -i Enable interactive edition" \
" -s Store in setting"
return 1
......@@ -372,7 +372,7 @@ bashopts_process_args() {
for op in "${bashopts_optlist[@]}"; do
# eval or get default value
if [[ -v bashopts_optprop_expression[$op] ]]; then
eval "dval=${bashopts_optprop_expression[$op]}"
dval="$(eval "echo \"${bashopts_optprop_expression[$op]}\"")"
else
dval=${bashopts_optprop_default[$op]}
fi
......
#!/bin/bash -e
# load the library
. bashopts.sh
# Enable backtrace dusplay on error
trap 'bashopts_exit_handle' ERR
# Initialize the library
bashopts_setup -n "$0" -d "This is myapp tool description displayed on help message" -s "$HOME/.config/myapprc"
# Declare the options
bashopts_declare -n first_name -l first -o f -d "First name" -t string -i -s -r
bashopts_declare -n last_name -l last -o l -d "Last name" -t string -i -s -r
bashopts_declare -n display_name -l display-name -t string -d "Display name" -e "\$first_name \$last_name"
bashopts_declare -n age -l number -d "Age" -t number
bashopts_declare -n email_list -t string -m add -l email -d "Email adress"
# Parse arguments
bashopts_parse_args $@
# Process argument
bashopts_process_args
# Display the values
echo
echo "First name: $first_name"
echo "Last name: $last_name"
echo "Display name: $display_name"
echo "Age: $age"
for email in ${email_list[@]}; do
echo "Email: $email"
done
......@@ -18,8 +18,8 @@
# specific language governing permissions and limitations
# under the License.
. opts.sh
trap 'errexit' ERR
. bashopts.sh
trap 'bashopts_exit_handle' ERR
req_test_eq() {
echo -n "\"$1\"" == "\"$2\""
......@@ -35,8 +35,8 @@ _test_case_1() {
local dest1="This is a simple desc"
local dest2="This is a desc with a '\"' and a \$test"
bashopts_add -n foo -l foo -o t -d "$dest1"
bashopts_add -n bar -l bar -o u -d "$dest2"
bashopts_declare -n foo -l foo -o t -d "$dest1"
bashopts_declare -n bar -l bar -o u -d "$dest2"
req_test_eq "${bashopts_optprop_description[foo]}" "$dest1"
req_test_eq "${bashopts_optprop_description[bar]}" "$dest2"
......@@ -47,8 +47,8 @@ _test_case_2() {
bashopts_setup -n "myapp_case3" -d "Test case 3" -s /tmp/myapp_case2rc
bashopts_add -n base_path -l base -o b -d "Base path" -t string -v "/opt/test" -i -s
bashopts_add -n config_path -l config -o c -d "Configuration path" -t string -e "\$base_path/myconf.cfg" -i -s
bashopts_declare -n base_path -l base -o b -d "Base path" -t string -v "/opt/test" -i -s
bashopts_declare -n config_path -l config -o c -d "Configuration path" -t string -e "\$base_path/myconf.cfg" -i -s
bashopts_parse_args --base /tmp -n
bashopts_process_args
......@@ -61,7 +61,7 @@ _test_case_3() {
rm -f /tmp/myapp_case3rc
bashopts_setup -n "myapp_case3" -d "Test case 3" -s /tmp/myapp_case3rc
bashopts_add -n process_file_list -l input-file -o f -d "Input file" -t string -m add -s
bashopts_declare -n process_file_list -l input-file -o f -d "Input file" -t string -m add -s
bashopts_parse_args --input-file foobar --input-file=/foo/bar
bashopts_process_args
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment