Skip to content

Bash Functions

🛠️ Tools · ⬅ Home

User interaction

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.

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

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

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 - 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

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

Return codes

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

Requires

grep cut fileReverseLines __help usageDocument

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

Reads standard input

Comment source (# removed)

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.

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

Reads standard input

a bash file

Writes to standard output

bash file without line-comments #

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.

Return codes

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

Builtins

isBashBuiltin

undocumented

Usage

isBashBuiltin builtin

No documentation for isBashBuiltin.

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 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 ] [ -- ] [ --home home ] [ --interactive ] [ --check checkDirectory ] [ ... ]

Sanitize bash files for code quality. used in find find ... ! -path '*LINE*' and in grep -e 'LINE' TODO - use one mechanism for bashSanitize.conf format

Arguments

  • --help - Flag. Optional. Display this help.
  • -- - Flag. Optional. Interactive mode on fixing errors.
  • --home home - Directory. Optional. Sanitize files starting here. (Defaults to buildHome)
  • --interactive - Flag. Optional. Interactive mode on fixing errors.
  • --check checkDirectory - Directory. Optional. 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 [ --verbose ] [ --fix ] [ --interactive ] [ --exec binary ] [ --delay ] [ findArgs ]

Run bashLint on a set of bash files.

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 - Integer. Optional. 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 - All found files pass shellcheck and bash -n
  • 1 - One or more files did not pass

Environment

  • This operates in the current working directory

bashLintFilesInteractive

Run checks interactively until errors are all fixed.

Usage

bashLintFilesInteractive [ --exec binary ] [ --delay delaySeconds ] [ fileToCheck ... ]

Run checks interactively until errors are all fixed.

Arguments

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

Return codes

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

bashLint

Check bash files for common errors

Usage

bashLint [ --help ] [ --fix ] [ --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

Arguments

  • --help - Flag. Optional. Display this help.
  • --fix - Flag. Optional. Fix files when possible.
  • --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 - All found files pass shellcheck and bash -n and shell comment syntax
  • 1 - One or more files did not pass