Developing Restsh functions

You can place custom scripts in the restsh/modules/custom/bin or restsh/modules/custom/lib folders.

Add a .shortdesc file into the folder for a short description (read by the restsh.help command).

Scripts in the bin folder

Scripts in the bin folder are treated as standard scripts.

Use the following header for each script file:

#!/usr/bin/env bash

# Shortdesc: This line is displayed in the help.
# Desc:
# More detailed description.

# Strict error handling
set -eEu -o pipefail

# Debug mode
[ -n "${RESTSH_DEBUG+x}" ] && set -x

if [ -z "${RESTSH_PATH+x}" ]
then
    echo "Script must be run in the restsh environment." 1>&2
    exit 1
fi

# Get options
while getopts ':h' OPTION
do
    case "$OPTION" in
        *) OPTION="invalid"; break ;;
    esac
done
shift "$((OPTIND -1))"

# Usage info on invalid options
if [ "$OPTION" = "invalid" ] || [ $# -ne 2 ]
then
    exec 1>&2
    _restsh.help.shortdesc.get "$0"
    echo "Usage: $(basename "$0") [options...] <argument1> <argument2>"
    echo ""
    echo "Options:"
    echo "    -a  Description"
    echo "    -b  Description"
    echo ""
    _restsh.help.desc.get "$0"
    exit 2
fi

# Check arguments
restsh.util.check.string "argument1" "$1"; ARG1=$1
restsh.util.check.filename "argument2" "$2"; ARG2=$2
#restsh.util.check.bool "argument2" "$2"; ARG2=$2
#restsh.util.check.uint "argument2" "$2"; ARG2=$2

# Main

Scripts in the lib folder

Scripts in the lib folder are sourced from restsh.init. Use this method only for central functions that must manipulate the environment or called by many scripts.

Use the following header for each script file:

#!/usr/bin/env bash

# Shortdesc: Short description
# Desc:
# More detailed description.

# Strict error handling
set -uo pipefail

# Debug mode
[ -n "${RESTSH_DEBUG+x}" ] && set -x

Define functions in this file and export these functions.

# Description - this line is displayed in the help.
sample.func() {
    if [ $# -ne 1 ] || [ "$1" = "-h" ]
    then
        {
            echo "Short description"
            echo "Usage: sample.func <argument1>"
         } 1>&2
         return 2
    fi
    # Function body
    return 0
}
export -f sample.func

Temporary files

Create temporary files always in $RESTSH_TMP. This is a uniq temporary directory created at startup and cleaned up on exit.

Each script should clean up its own temporary files. Use a cleanup trap to do this.

# Cleanup tmp files on exit
_cleanup() {
    rm -f "$RESTSH_TMP/existing.json"
    rm -f "$RESTSH_TMP/new.json"
}
trap _cleanup EXIT

Some further hints

• The header enables strict error checking. Handle each command that can fail and return an appropriated error code: 0 for success, else 1

• Use echo_err or echo_warn to print errors and warnings to STDERR.

• Use echo_verbose to print verbose messages. They are only printed if RESTSH_VERBOSE is set to 1.

• Provide usage information for all functions.

• Check your functions with shellcheck, the lint.sh script does it for you.