Some functions follow the processor archetype: they take input, do something with it, and return the result back to the caller. This is something of a classic function: depending on the input, different output is generated. We'll show this with an example that reverses the input the user specifies to the script. This is normally done with the rev command (and will actually be accomplished with rev in our function as well), but we're creating a wrapper function around this with a little extra functionality:

reader@ubuntu:~/scripts/chapter_13$ vim reverser.sh 
reader@ubuntu:~/scripts/chapter_13$ cat reverser.sh 
#!/bin/bash

#####################################
# Author: Sebastiaan Tammer
# Version: v1.0.0
# Date: 2018-11-17
# Description: Reverse the input for the user.
# Usage: ./reverser.sh <input-to-be-reversed>
#####################################

# Check if the user supplied one argument.
if [[ $# -ne 1 ]]; then
  echo "Incorrect number of arguments!"
  echo "Usage: $0 <input-to-be-reversed>"
  exit 1
fi

# Capture the user input in a variable.
user_input="_${1}_" # Add _ for readability.

# Define the reverser function.
reverser() {
  # Check if input is correctly passed.
  if [[ $# -ne 1 ]]; then
    echo "Supply one argument to reverser()!" && exit 1
  fi

  # Return the reversed input to stdout (default for rev).
  rev <<< ${1}
}

# Capture the function output via command substitution.
reversed_input=$(reverser ${user_input})

# Show the reversed input to the user.
echo "Your reversed input is: ${reversed_input}"

As this is again a longer, more complex script, we're going to look at it bit by bit to make sure you understand it all. We even sneaked a little surprise in there that proves one of our earlier statements, but we'll get to that in a bit. We'll skip the header and input check and move to capturing the variable:

# Capture the user input in a variable.
user_input="_${1}_" # Add _ for readability.

In most of the earlier examples, we've always directly mapped input to a variable. However, this time we're showing that you can actually also add some extra text. In this case, we're taking the input by the user and we add an underscore before and after. If the user inputs rain, the variable will actually contain _rain_. This will prove insightful later. Now, for the function definition, we use the following code:

# Define the reverser function.
reverser() {
  # Check if input is correctly passed.
  if [[ $# -ne 1 ]]; then
    echo "Supply one argument to reverser()!" && exit 1
  fi

  # Return the reversed input to stdout (default for rev).
  rev <<< ${1}
}

The reverser function requires a single argument: the input to be reversed. As always, we first check if the input is correct, before we actually do anything. Next, we use rev to reverse the input. However, rev normally expects input from a file or stdin, not a variable as an argument. Because we do not want to add an extra echo and pipe, we use a here string (as explained in Chapter 12, Using Pipes and Redirection in Scripts), which allows us to directly use the variable content as stdin. Since rev already outputs the result to stdout, we do not need to provide anything, such as an echo, at that point.

We told you we'd prove a previous statement, which in this case relates to $1 in the previous snippet. If $1 within the function related to the first argument of the script and not the first argument of the function, we would not see the underscores we added when we wrote the user_input variable. For the script, $1 could equal rain, where in the function, $1 equals _rain_. When you run the script, you'll definitely see the underscores, which means that each function really has its own set of arguments!

Tying it all together is the final piece of the script:

# Capture the function output via command substitution.
reversed_input=$(reverser ${user_input})

# Show the reversed input to the user.
echo "Your reversed input is: ${reversed_input}"

Since the reverser function sends the reversed input to stdout, we'll use command substitution to capture it in a variable. Finally, we print some clarifying text and the reversed input to the user with echo. The result will look like this:

reader@ubuntu:~/scripts/chapter_13$ bash reverser.sh rain
Your reversed input is: _niar_

Underscores and all, we get the reverse of rain: _nair_. Nice!