Bash: scripts with parameters, a straightforward approach

A straightforward way to use parameters in a Bash script is to execute the script with the parameters values listed after the script file name and to use these values in the script via ${1}..${n} variables, where n is the number of the parameters.

Script with parameters basic example

An example of a basic script following this approach:

#!/bin/bash

echo "Arguments values: first=${1}, second=${2}, third=${3}"

The script outputs the values of the first three supplied parameters values.

Executing the script with all three arguments supplied gives the following:

./scriptWithOptions.sh firstValue secondValue thirdValue
Output:
Arguments values: first=firstValue, second=secondValue, third=thirdValue

Executing the same script with only the first parameter value provided gives the following:

./scriptWithOptions.sh firstValue
Output:
Arguments values: first=firstValue, second=, third=

If we want to provide only the second parameter value, we need to execute the script like in the example below. As the second parameter position is after the first one, we have to explicitly specify an empty value of the first parameter:

./scriptWithOptions.sh "" secondValue
Output:
Arguments values: first=, second=secondValue, third=

If we want to provide only the second parameter value, we need to execute the script like in the example below. As the second parameter position is after the first one, we have to explicitly specify an empty value of the first parameter:

./scriptWithOptions.sh "" secondValue
Output:
Arguments values: first=, second=secondValue, third=

In the rest of this post, I will show how to add some logic to using the script parameters.

Script with required parameters

If at least one of the script parameters is required, a good practice is to have a simple check of the number of the provided parameters at the beginning of the script.

if [ $# -lt 1 ]; then echo "Please provide the script required parameters values"; exit 1; fi

The line above checks if the number of the script parameters is less than one. If it is the case, an error message is displayed and the script exits with the code 1. Here were use a $# variable which stores the number of the provided script parameters. We are using the exit code 1 after detecting an error, as exit code 1 is usually an exit code of an error.

Calling the script without parameters produces the expected error:

./scriptWithOptions.sh 
Output: 
Please provide the script parameters values

The script exit code is 1, as expected:

echo $?
Output:
1

We proceed by extending our example. Now, we have the first and the third parameters as required. We can check their availability as shown below:

if [[ ${#} -lt 1 || -z ${1} || -z ${3} ]]; then
echo "Please provide the script required parameters values. The first and the third parameters must be non-empty"
exit 1
fi

The condition which is being evaluated is the following:

  • if ‘${#} -lt 1’ => ‘the number of the provided script parameters is less than one’,
  • ‘||’ => ‘or’,
  • ‘-z ${1}’ => ‘the first script parameter value is empty’,
  • ‘||’ => ‘or’,
  • ‘-z ${3}’ => ‘the third script parameter value is empty’

showUsage function

Sometimes, in addition to non-emptiness, we may need to perform some additional checks. For example, check if the first parameter value consists only of numeric characters, or the second parameter value matches a value from a list of constants. In these cases, it is a good practice to generalize the script parameters values requirements in a separate function and call it if any of the above mentioned check fails.

An example of the showUsage function:

function showUsage {
echo "$( basename ${0} ) - display script parameters values."
echo "The first and the third parameters are required, the second one is optional."
echo "The first parameter value must consist of only the numeric characters."
echo "The second parameter can have one of the following values: ONE, TWO, THREE."
exit 1
}

Note the use of the basename command in a subshell, aimed to get the name of the script from the $0 variable, holding the called script filename.

The required checks can be implemented in the following way:

  • the first and the second script parameters are required:
if [[ ${#} -lt 1 || -z ${1} || -z ${3} ]]; then showUsage; fi

Note that we reuse the check which we have defined already. The error message is replaced by the showUsage function call.

  • the first parameter value must consist of only the numeric characters:
if [[ ! ${1} =~ ^[0-9]+$ ]]; then showUsage; fi

A regular expression is used to check that. The condition says: if the first parameter value does not match a line consisting of one or more numeric characters, call the showUsage function.

  • the second parameter can have one of the following values: ONE, TWO, THREE:
if [[ ! -z ${2} && ${2} != "ONE" && ${2} != "TWO" && ${2} != "THREE" ]]; then showUsage; fi

Here, if the second parameter value is non-empty, we consecutively check if it does not matches any of the required constant values. If it does not match any constant value, the showUsage function is called. If it matches at least any of the constant value, the condition is evaluated as false and we continue the script execution.

The script with the showUsage function and the checks:

#!/bin/bash
  
function showUsage {
echo "$( basename ${0} ) - display script parameters values."
echo "The first and the third parameters are required, the second one is optional."
echo "The first parameter value must consist of only the numeric characters."
echo "The second parameter can have one of the following values: ONE, TWO, THREE."
exit 1
}

if [[ ${#} -lt 1 || -z ${1} || -z ${3} ]]; then showUsage; fi
if [[ ! ${1} =~ ^[0-9]+$ ]]; then showUsage; fi
if [[ ! -z ${2} && ${2} != "ONE" && ${2} != "TWO" && ${2} != "THREE" ]]; then showUsage; fi

echo "Arguments values: first=${1}, second=${2}, third=${3}"

Incorrect script calls:

./scriptWithOptions.sh 1 ff dd
./scriptWithOptions.sh aa "" dd 
./scriptWithOptions.sh
Output:
scriptWithOptions.sh - display script parameters values.
The first and the third parameters are required, the second one is optional.
The first parameter value must consist of only the numeric characters.
The second parameter can have one of the following values: ONE, TWO, THREE.

And correct script calls:

./scriptWithOptions.sh 1 "" a
Output:
Arguments values: first=1, second=, third=a
./scriptWithOptions.sh 1 TWO a
Output:
Arguments values: first=1, second=TWO, third=a

In the next post, I will show examples of how to use getopts command to parse the script parameters.