README.md 6.34 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
# 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```
11
- Process arguments with ```bashopts_process_opts```
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

### 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)
29 30 31
 - ```-y```: Set non interactive mode as the default mode (optional)
 - ```-x```: Disable entirely interactive mode (optional)
 - ```-p```: Force value storage even if the value is equal to the default one (optional)
32 33 34 35 36 37 38 39 40 41 42 43
 
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
Emeric Verschuur's avatar
Emeric Verschuur committed
44
 - ```-x <val>```: Bash expression: like default but this expression is computed on time and can contain variables and other bash expression
45 46 47
 - ```-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
Emeric Verschuur's avatar
Emeric Verschuur committed
48 49
 - ```-t <val>```: Value type: string, enumeration, number, boolean (default)
 - ```-e <val>```: Enum element: restrict possible values with a list of '-e <element>' options (you have to set one '-e <val>' by elements)
50
 - ```-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)
51
 - ```-k <val>```: Custom check method (bash function like bashopts_check_number in bashopts.sh file)
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
 - ```-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
Emeric Verschuur's avatar
Emeric Verschuur committed
74
bashopts_parse_args "$@"
75 76 77
```

### Argument processing
78
Process all the options with ```bashopts_process_opts```
79 80 81 82 83 84 85 86 87

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```)


88
bashopts_process_opts usage:
89
```bash
90
bashopts_process_opts
91
```
Emeric Verschuur's avatar
Emeric Verschuur committed
92 93 94 95 96

### Option exploitation
- All the options are stored on bash variable (e.g.: option name first_name on the following example give $first_name bash variable)
- All other command (other than argument beginning by '-' or '--') are stored into the ```bashopts_commands``` bash array. You can iterate by ```for command in ${bashopts_commands[@]}; do ...; done```
- All extra arguments (```mytool --arg1 --arg2 cmd1 cmd2 -- --extra-arg1 --extra-arg2 ...```) are stored into the ```bashopts_extra_args``` bash array.
97
- If the argument value is empty (e.g.: --long-arg "") the value is unset (also usefull to clear an array)
Emeric Verschuur's avatar
Emeric Verschuur committed
98
- To add several default values for an array, add: bashopts_declare -e '("value 1" "value 2" "... etc.")'
Emeric Verschuur's avatar
Emeric Verschuur committed
99

100 101 102
## Example

```bash
103
#!/bin/bash -e
104 105 106 107 108 109 110 111

# load the library
. bashopts.sh

# Enable backtrace dusplay on error
trap 'bashopts_exit_handle' ERR

# Initialize the library
112
bashopts_setup -n "example.sh" -d "This is myapp tool description displayed on help message" -s "$HOME/.config/myapprc"
113 114 115 116

# 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
117
bashopts_declare -n display_name -l display-name -t string -d "Display name" -e "\"\$first_name \$last_name\""
118 119 120 121
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
Emeric Verschuur's avatar
Emeric Verschuur committed
122
bashopts_parse_args "$@"
123

124 125
# Process options
bashopts_process_opts
126 127 128 129 130 131 132

# Display the values
echo
echo "First name: $first_name"
echo "Last name: $last_name"
echo "Display name: $display_name"
echo "Age: $age"
Emeric Verschuur's avatar
Emeric Verschuur committed
133
for email in "${email_list[@]}"; do
134 135 136 137 138 139 140 141 142 143 144 145
    echo "Email: $email"
done
```

Display the help:
```bash
$ ./example.sh --help
```

Output:
```
NAME:
146
    example.sh - This is myapp tool description displayed on help message
147 148

USAGE:
149
    example.sh [options and commands] [-- [extra args]]
150 151

OPTIONS:
Emeric Verschuur's avatar
Emeric Verschuur committed
152
    -h,--help                          Display this help
153
    -n,--non-interactive false         Non interactive mode - [$bashopts_non_interactive] (type:boolean, default:false)
Emeric Verschuur's avatar
Emeric Verschuur committed
154 155
    -f,--first "John"                  First name - [$first_name] (type:string, default:"")
    -l,--last "Smith"                  Last name - [$last_name] (type:string, default:"")
156
    --display-name "John Smith"        Display name - [$display_name] (type:string, default:"\"$first_name $last_name\"")
Emeric Verschuur's avatar
Emeric Verschuur committed
157
    --number 0                         Age - [$age] (type:number, default:0)
Emeric Verschuur's avatar
Emeric Verschuur committed
158
    --email                            Email adress - [$email_list] (type:string, default:"")
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
```

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
```