Skip to content

Bash Functions

🛠️ Tools · ⬅ Home

Execution

executableExists

Does a binary exist in the PATH?

Usage

executableExists [ --any ] binary ... [ --help ]

Does a binary exist in the PATH?

Arguments

  • --any - Flag. Optional. If any binary exists then return 0 (success). Otherwise, all binaries must exist.
  • binary ... - String. Required. One or more Binaries to find in the system PATH.
  • --help - Flag. Optional. Display this help.

Examples

executableExists cp date aws ls mv stat || throwEnvironment "$handler" "Need basic environment to work" || return $?
executableExists --any terraform tofu || throwEnvironment "$handler" "No available infrastructure providers" || return $?
executableExists --any curl wget || throwEnvironment "$handler" "No way to download URLs easily" || return $?

Return codes

  • 0 - If all values are found (without the --any flag), or if any binary is found with the --any flag
  • 1 - If any value is not found (without the --any flag), or if all binaries are NOT found with the --any flag.

executeCount

Run a binary count times

Usage

executeCount [ count ] [ binary ] [ args ... ]

Run a binary count times

Arguments

  • count - The number of times to run the binary
  • binary - The binary to run
  • args ... - Any arguments to pass to the binary each run

Return codes

  • 0 - success
  • 2 - count is not an unsigned number
  • Any - If binary fails, the exit code is returned

bashMakeExecutable

Makes all *.sh files executable

Usage

bashMakeExecutable [ --find findArguments ] [ path ... ]

Makes all *.sh files executable

Arguments

  • --find findArguments - String. Optional. Add arguments to exclude files or paths. SPACE-delimited for multiple options.
  • path ... - Directory. Optional. One or more paths to scan for shell files. Uses PWD if not specified.

Return codes

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

Environment

  • Works from the current directory

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 - Flag. Optional. 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 - Flag. Optional. 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.

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 - Flag. Optional. Display this help.

Writes to standard output

Parent path where libraryRelativePath exists

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 - String. Optional. String passed to ! -path pattern in find
  • directory ... - Directory. Required. Directory to source all .sh files used.
  • --help - Flag. Optional. 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 - Flag. Optional. Display this help.

Return codes

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

bashFinalComment

Extracts the final comment from a stream

Usage

bashFinalComment [ --help ]

Extracts the final comment from a stream

Arguments

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

Return codes

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

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 - Flag. Optional. 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 [ --help ] [ --ignore prefix. String. Optional. Ignore exact function names. ] [ --ignore-prefix prefix ] [ --report ] [ --require ] [ --unused ]

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 - Flag. Optional. 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 - Flag. Optional. 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 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 - Flag. Optional. Display this help.

Return codes

  • 0 - Function is used within the file
  • 1 - Function is not used within the file

bashListFunctions

List functions in a given shell file

Usage

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

List functions in a given shell file

Arguments

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

Return codes

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

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 - Flag. Optional. Display this help.

Return codes

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

bashCommentVariable

Gets a list of the variable values from a bash

Usage

bashCommentVariable variableName [ --prefix ] [ --insensitive | -i ] [ --help ]

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

Arguments

  • variableName - String. Required. Get this variable value.
  • --prefix - Flag. Optional. Find variables with the prefix variableName --insensitive |- -i - Flag. Optional. Match case insensitive.
  • --help - Flag. Optional. Display this help.

Reads standard input

Comment source (# removed)

Return codes

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

bashFunctionCommentVariable

Gets a list of the variable values from a bash

Usage

bashFunctionCommentVariable source functionName variableName [ --prefix ] [ --i | --insensitive ] [ --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 --i |- --insensitive - Flag. Optional. Case-insensitive match.
  • --help - Flag. Optional. 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

Arguments

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

Reads standard input

a bash file

Writes to standard output

bash file without line-comments #

Return codes

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

Builtins

isBashBuiltin

Is a token a bash builtin?

Usage

isBashBuiltin builtin

Useful for introspection or validation - checks if a token is a bash built-in (e.g. cd) vs. a binary on the system (/bin/cd). Implementation taken directly from the Bash man page.

Arguments

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

Return codes

  • 0 - Yes, this string is a bash builtin command.
  • 1 - No, this is not a bash builtin command

bashBuiltins

List bash builtin functions, one per line

Usage

bashBuiltins

List bash builtin functions, one per line

Arguments

  • none

Writes to standard output

line:function

Return codes

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

🛠️ Tools · ⬅ Top