Skip to content

Bash Functions

🛠️ Tools · ⬅ Top

User interaction

bashUserInput

Prompt the user properly honoring any attached console.

Usage

bashUserInput [ --help ] [ ... ]

Prompt the user properly honoring any attached console.

Arguments are the same as read, except:

-r is implied and does not need to be specified

Arguments

  • --help - Optional. Flag. Display this help.
  • ... - Arguments. Optional. Identical arguments to read (but includes -r)

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Loading

bashLibrary

Run or source a library

Usage

bashLibrary libraryRelativePath [ command ] [ --help ]

Run or source one or more bash scripts and load any defined functions into the current context. Has security implications - only load trusted code sources and prevent user injection of bash source code into your applications.

Arguments

  • libraryRelativePath - Path. Required. Path to library source file.
  • command - Callable. Optional. Command to run after loading the library.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashLibraryHome

Output the home for a library in the parent path

Usage

bashLibraryHome libraryRelativePath [ startDirectory ] [ --help ]

This function searches for a library located at the current path and searches upwards until it is found. A simple example is bin/build/tools.sh for this library which will generally give you an application root if this library is properly installed. You can use this for any application to find a library's home directory.

Note that the libraryRelativePath given must be both executable and a file.

Writes to standard output

Parent path where libraryRelativePath exists

Arguments

  • libraryRelativePath - RelativeFile. Required. Path of file to find from the home directory. Must also be executable.
  • startDirectory - Directory. Optional. Place to start searching. Uses pwd if not specified.
  • --help - Optional. Flag. Display this help.

Examples

libFound=$(bashLibraryHome "bin/watcher/server.py")

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashSourcePath

Load a directory of bash scripts

Usage

bashSourcePath [ --exclude pattern ] directory ... [ --help ]

Load a directory of bash scripts, excluding any dot directories (*/.*/*), and optionally any additional files if you use --exclude. But recursively loads scripts in sorted alphabetic order within the directory until one fails. All files must be executable. Load a directory of .sh files using source to make the code available. Has security implications. Use with caution and ensure your directory is protected.

Arguments

  • --exclude pattern - Optional. String. String passed to ! -path pattern in find
  • directory ... - Required. Directory. Directory to source all .sh files used.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Code analysis

bashFileComment

Extract a bash comment from a file. Excludes lines containing

Usage

bashFileComment source lineNumber [ --help ]

Extract a bash comment from a file. Excludes lines containing the following tokens:

Arguments

  • source - File. Required. File where the function is defined.
  • lineNumber - String. Required. Previously computed line number of the function.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

head bashFinalComment __help usageDocument

bashFinalComment

Extracts the final comment from a stream

Usage

bashFinalComment [ --help ]

Extracts the final comment from a stream

Arguments

  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

fileReverseLines sed cut grep convertValue

bashFunctionDefined

Is a function defined in a bash source file?

Usage

bashFunctionDefined functionName file ... [ --help ]

Is a function defined in a bash source file?

Arguments

  • functionName - String. Required. Name of function to check.
  • file ... - File. Required. One or more files to check if a function is defined within.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashGetRequires

Gets a list of the Requires: comments in a bash

Usage

bashGetRequires script ...

Gets a list of the Requires: comments in a bash file Returns a unique list of tokens

Arguments

  • script - File. Required. Bash script to fetch requires tokens from.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashCheckRequires

Checks a bash script to ensure all requirements are met,

Usage

bashCheckRequires script

Checks a bash script to ensure all requirements are met, outputs a list of unmet requirements Scans a bash script for lines which look like:

Each requirement token is:

  • a bash function which MUST be defined
  • a shell script (executable) which must be present

If all requirements are met, exit status of 0. If any requirements are not met, exit status of 1 and a list of unmet requirements are listed

Arguments

  • --help - Optional. Flag. Display this help. --ignore prefix. String. Optional. Ignore exact function names. --ignore-prefix prefix. String. Optional. Ignore function names which match the prefix and do not check them.
  • --report - Flag. Optional. Output a report of various functions and handler after processing is complete.
  • --require - Flag. Optional. Requires at least one or more requirements to be listed and met to pass
  • --unused - Flag. Optional. Check for unused functions and report on them.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

token1 token2

bashStripComments

Pipe to strip comments from a bash file

Usage

bashStripComments [ --help ]

Removes literally any line which begins with zero or more whitespace characters and then a #.

Arguments

  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashShowUsage

Show function handler in files

Usage

bashShowUsage functionName file [ --help ]

Show function handler in files Return Code: 0 - Function is used within the file Return Code: 1 - Function is not used within the file This check is simplistic and does not verify actual coverage or code paths.

Arguments

  • functionName - String. Required. Function which should be called somewhere within a file.
  • file - File. Required. File to search for function handler.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

throwArgument decorate usageArgumentString usageArgumentFile quoteGrepPattern bashStripComments cat grep

bashListFunctions

List functions in a given shell file

Usage

bashListFunctions [ --help ] [ file ] [ --help ]

List functions in a given shell file

Arguments

  • --help - Optional. Flag. Display this help.
  • file - File. Optional. File(s) to list bash functions defined within.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

__bashListFunctions throwArgument decorate usageArgumentFile

bashFunctionComment

Extract a bash comment from a file. Excludes lines containing

Usage

bashFunctionComment source functionName [ --help ]

Extract a bash comment from a file. Excludes lines containing the following tokens:

Arguments

  • source - File. Required. File where the function is defined.
  • functionName - String. Required. The name of the bash function to extract the documentation for.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

grep cut fileReverseLines __help usageDocument

bashFunctionCommentVariable

Gets a list of the variable values from a bash

Usage

bashFunctionCommentVariable source functionName variableName [ --prefix ] [ --help ]

Gets a list of the variable values from a bash function comment

Arguments

  • source - File. Required. File where the function is defined.
  • functionName - String. Required. The name of the bash function to extract the documentation for.
  • variableName - string. Required. Get this variable value
  • --prefix - flag. Optional. Find variables with the prefix variableName
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashCommentFilter

Filter comments from a bash stream

Usage

bashCommentFilter [ --help ] [ --only ] [ file ]

Filter comments from a bash stream

Reads standard input

a bash file

Writes to standard output

bash file without line-comments #

Arguments

  • --help - Optional. Flag. Display this help.
  • --only - Optional. Flag. Show ONLY comment lines. (Reverse of lines when not specified.)
  • file - Optional. File. File(s) to filter.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Builtins

isBashBuiltin

Return Code: 0 - Yes, this string is a bash

Usage

isBashBuiltin builtin

Return Code: 0 - Yes, this string is a bash builtin command. Return Code: 1 - No, this is not a bash builtin command

Arguments

  • builtin - String. Required. String to check if it's a bash builtin.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashBuiltins

List bash buildin functions, one per line

Usage

bashBuiltins

List bash buildin functions, one per line

Writes to standard output

line:function

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Linting

bashSanitize

Sanitize bash files for code quality.

Usage

bashSanitize [ --help ] [ --interactive ] [ --check checkDirectory ] ...

Sanitize bash files for code quality.

Configuration File: bashSanitize.conf (file containing patterns of files to skip, one per line, e.g. etc/docker)

Arguments

  • --help - Optional. Flag. Display this help.
  • -- - Flag. Optional. Interactive mode on fixing errors.
  • --home home - Optional. Directory. Sanitize files starting here. (Defaults to buildHome)
  • --interactive - Flag. Optional. Interactive mode on fixing errors.
  • --check checkDirectory - Optional. Directory. Check shell scripts in this directory for common errors.
  • ... - Additional arguments are passed to bashLintFiles validateFileContents

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashLintFiles

Check files for the existence of a string

Usage

bashLintFiles [ --exec binary ] [ file0 ... ]

Run bashLint on a set of bash files.

Side-effect: shellcheck is installed Side-effect: Status written to stdout, errors written to stderr Return Code: 0 - All found files pass shellcheck and bash -n Return Code: 1 - One or more files did not pass

Arguments

  • --verbose - Flag. Optional. Verbose mode.
  • --fix - Flag. Optional. Fix errors when possible.
  • --interactive - Flag. Optional. Interactive mode on fixing errors.
  • --exec binary - Run binary with files as an argument for any failed files. Only works if you pass in item names.
  • --delay - Optional. Integer. Delay between checks in interactive mode.
  • findArgs - Additional find arguments for .sh files (or exclude directories).

Examples

if bashLintFiles; then git commit -m "saving things" -a; fi

Sample Output

This outputs statusMessages to stdout and errors to stderr.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • This operates in the current working directory

bashLintFilesInteractive

Run checks interactively until errors are all fixed.

Usage

[ fileToCheck ... ]

Run checks interactively until errors are all fixed.

Arguments

  • --exec binary - Optional. Callable. Run binary with files as an argument for any failed files. Only works if you pass in item names.
  • --delay delaySeconds - Optional. Integer. Delay in seconds between checks in interactive mode.
  • fileToCheck ... - Optional. File. Shell file to validate.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashLint

Run shellcheck and bash -n on a set of bash

Usage

bashLint [ --help ] [ --fix ] [ script ] [ verbose ] [ script ]

Run shellcheck and bash -n on a set of bash files.

This can be run on any directory tree to test scripts in any application.

Shell comments must not be immediately after a function end, e.g. this is invalid:

myFunc() {
}
# Hey

Side-effect: shellcheck is installed Side-effect: Status written to stdout, errors written to stderr Return Code: 0 - All found files pass shellcheck and bash -n and shell comment syntax Return Code: 1 - One or more files did not pass

Arguments

  • --help - Optional. Flag. Display this help.
  • --fix - Optional. Flag. Fix files when possible.
  • script - File. Optional. Shell script to validate
  • verbose - Flag. Optional. Be verbose.
  • script - File. Optional. Shell script to validate

Examples

bashLint goo.sh

Sample Output

This outputs statusMessages to stdout and errors to stderr.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Debug

bashDebugInterruptFile

Adds a trap to capture the debugging stack on interrupt

Usage

bashDebugInterruptFile [ --help ] [ --error ] [ --interrupt ]

Adds a trap to capture the debugging stack on interrupt Use this in a bash script which runs forever or runs in an infinite loop to determine where the problem or loop exists.

Arguments

  • --help - Optional. Flag. Display this help.
  • --error - Flag. Add ERR trap.
  • --interrupt - Flag. Add INT trap.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

trap

bashRecursionDebug

Place this in code where you suspect an infinite loop

Usage

bashRecursionDebug [ --end ]

Place this in code where you suspect an infinite loop occurs It will fail upon a second call; to reset call with --end When called twice, fails on the second invocation and dumps a call stack to stderr.

Arguments

  • --end - Flag. Optional. Stop testing for recursion.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • __BUILD_RECURSION

Requires

printf unset export debuggingStack exit