What is a function?

A function in Bash is like a function in any programming languages. A function is a subroutine in a program, and though I wont go into detail on that here you can learn more about it at wikipedia.

How to

In bash the syntax to create a function is really simple, here is an example.

function sayHello() { echo hello; }

This creates a function called sayHello that, when called, will echo "hello" to the screen. To call this function inside a script is also simple, you treat sayHello as though it is a command that you would call just like any other in the script. For example:

#!/bin/bash
function sayHello() { echo hello; }
echo "about to call the function."
sayHello
echo "done"

This output of this script will be this.

about to call the function hello done

The sayHello function, when called, will just execute the code that is inside the function and move on.

What can you do with functions?

Functions can be handy for a lot of reasons.

Redirect Output

You can send the output from the function to a file instead of standard output. For example you could change the script to this:

#!/bin/bash
function sayHello() { echo hello; }
echo "about to call the function."
sayHello > file.txt
echo "done"

This will take the output from the sayHello function and send it to file.txt.

Replace Complicated Commands

You can take a command that is annoying to type over and over and put it into a function that makes it easier to call. For example:

#!/bin/bash
function toLower() {
     tr "[:upper:]" "[:lower:]"
}

This function can take in a string and return the string with only lowercase letters. To use this function in a script you would write it like this.

#!/bin/bash
function toLower() {
      tr "[:upper:]" "[:lower:]"
}

echo "ThIs SeNtEnCe Is TeRrIbLe To LoOk At!!" | toLower

The output from this script will be...

this sentence is terrible to look at!!

And as you can see it is no longer terrible to look at anymore :)

NOTE: The function must be created in the script before it is called in the script! Otherwise the script will say the command doesn't exist. To remedy this I make all of my functions at the top of the script.

Usage Statements

You can create on usage error in your script (the output you see when you call a program with the -h or --help switch normally). This can be helpful because you can call the function to print the usage for multiple reasons, such as calling it with the -h switch, or supplying an incorrect argument, etc.

#!/bin/bash
function printUsage() {
      echo "Usage: $0 [-v] [-d <directory>]"
} 
# this next line will check if the first argument is empty, if it is it will print the usage and exit
[[ -z $1 ]] && (printUsage; exit 1)

Passing Arguments

When a function gets called, it gets executed the exact same way a program or script would get executed. This means that you can pass command line arguments to the function the same way you would with a script, and you would read them the same way. For example.

#!/bin/bash
function isEmpty() {
     [[ -z $1 ]] && echo "empty" || echo "NOT empty"
}
VARIABLE="test"
isEmpty $VARIABLE

This script will set a the variable VARIABLE to "test", and will then pass it into the function isEmpty. This function can then reference that variable by using the variable $1, because it was passed to the function as an argument. If the variable is empty it will print "empty", otherwise it will print "NOT empty".

When to use functions

This rule is not set-in-stone, but more or less a rule of thumb. If you're going to use the same code more than once in a script, consider if it would be better to write the code once in a function, and call that function multiple times.