Skip to content

Text Functions

🛠️ Tools · ⬅ Home

Patterns

Usage

isPlain text

Check if text contains plaintext only. Without arguments, displays help.

Arguments

  • text - String. Required. Text to search for mapping tokens.

Return codes

  • 0 - Text is plain
  • 1 - Text contains non-plain characters

Filters

Usage

grepSafe [ --help ] [ ... ]

grep but returns 0 when nothing matches Allow blank files or no matches - - grep - returns 1 - no lines selected - grep - returns 0 - lines selected

Arguments

  • --help - Flag. Optional. Display this help.
  • ... - Arguments. Passed directly to grep.

Return codes

  • 0 - Normal operation

Requires

grep returnMap

Usage

replaceFirstPattern [ searchString ] [ replaceString ]

Replaces the first and only the first occurrence of a pattern in a line with a replacement string. Without arguments, displays help.

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Arguments

  • searchString - String. Thing to search for.
  • replaceString - String. Thing to replace search string with.

Return codes

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

Usage

removeFields [ fieldCount ]

Remove fields from left to right from a text file as a pipe

Reads standard input

A file with fields separated by spaces

Writes to standard output

The same file with the first fieldCount fields removed from each line.

Arguments

  • fieldCount - Integer. Optional. Number of field to remove. Default is just first 1.

Return codes

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

Usage

clampDigits [ minimum ] [ maximum ] [ --help ]

Clamp digits between two integers Reads stdin digits, one per line, and outputs only integer values between $min and $max

Arguments

  • minimum - Integer|Empty. Minimum integer value to output.
  • maximum - Integer|Empty. Maximum integer value to output.
  • --help - Flag. Optional. Display this help.

Return codes

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

Usage

printfOutputPrefix ...

Pipe to output some text before any output, otherwise, nothing is output. Without arguments, displays help.

Reads standard input

text (Optional)

Writes to standard output

printf output and then the stdin text IFF stdin text is non-blank

Arguments

  • ... - Arguments. Required. printf arguments.

Return codes

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

Usage

printfOutputSuffix ...

Pipe to output some text after any output, otherwise, nothing is output. Without arguments, displays help.

Reads standard input

text (Optional)

Writes to standard output

stdin text and then printf output IFF stdin text is non-blank

Arguments

  • ... - Arguments. Required. printf arguments.

Return codes

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

Usage

printfOutputEmpty ...

Pipes all input to output, if any input exists behaves like cat. If input is empty then runs and outputs the printf statement result. Without arguments, displays help.

Reads standard input

text (Optional)

Writes to standard output

printf output and then the stdin text IFF stdin text is blank

Arguments

  • ... - Arguments. Required. printf arguments.

Examples

cat "$failedFunctions" | decorate wrap -- "- " | printfOutputEmpty "%s\n" "No functions failed."

Return codes

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

Usage

newlineHide [ --help ] text [ replace ]

Hide newlines in text (to ensure single-line output or other manipulation) Without arguments, displays help.

Writes to standard output

The text with the newline replaced with another character, suitable typically for single-line output

Arguments

  • --help - Flag. Optional. Display this help.
  • text - String. Required. Text to replace.
  • replace - String. Optional. Replacement string for newlines.

Return codes

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

Formatting

Usage

textAlignLeft [ --help ] characterWidth [ text ... ]

Format text and align it left using spaces.

Arguments

  • --help - Flag. Optional. Display this help.
  • characterWidth - UnsignedInteger. Required. Number of characters to align left
  • text ... - Text to align left.

Examples

printf "%s: %s\n" "$(textAlignLeft 14 Name)" "$name"
printf "%s: %s\n" "$(textAlignLeft 14 Profession)" "$occupation"
Name          : Tyrone
Profession    : Engineer

Return codes

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

Usage

textAlignRight [ characterWidth ] [ text ... ] [ --help ]

Format text and align it right using spaces.

Arguments

  • characterWidth - Characters to align right
  • text ... - Text to align right
  • --help - Flag. Optional. Display this help.

Examples

printf "%s: %s\n" "$(textAlignRight 20 Name)" "$name"
printf "%s: %s\n" "$(textAlignRight 20 Profession)" "$occupation"
            Name: Juanita
      Profession: Engineer

Return codes

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

Cleanup ANSI text

Usage

consoleToPlain [ None. ]

Strip ANSI console escape sequences from a file

Reads standard input

arbitrary text which may contain ANSI escape sequences for the terminal

Writes to standard output

the same text with those ANSI escape sequences removed

Arguments

  • None.

Return codes

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

Environment

  • None.

Credits

Thanks to commandlinefu tripleee .

Usage

consoleTrimWidth width [ text ]

Truncate console output width

Reads standard input

String. Optional. Text to trim to a console width.

Writes to standard output

String. Console string trimmed to the width requested.

Arguments

  • width - UnsignedInteger. Required. Width to maintain.
  • text - String. Optional. Text to trim to a console width.

Return codes

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

Usage

consolePlainLength [ text ]

Length of an unformatted string

Reads standard input

A file to determine the plain-text length

Writes to standard output

UnsignedInteger. Length of the plain characters in the input arguments.

Arguments

  • text - EmptyString. Optional. text to determine the plaintext length of. If not supplied reads from standard input.

Return codes

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

Space trimming

Usage

trimWords [ wordCount ] [ word0 ... ]

Remove words from the end of a phrase

Arguments

  • wordCount - PositiveInteger. Words to output
  • word0 ... - EmptyString. One or more words to output

Examples

printf "%s: %s\n" "Summary:" "$(trimWords 10 $description)"

Return codes

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

Usage

trimSpace [ text ]

Trim spaces and only spaces from arguments or a pipe

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs trimmed lines

Arguments

  • text - EmptyString. Optional. Text to remove spaces. If no arguments are supplied it is assumed that input should be read from standard input.

Examples

trimSpace "$token"
grep "$tokenPattern" | trimSpace > "$tokensFound"

Return codes

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

Credits

Thanks to Chris F.A. Johnson (2008) .

Usage

trimLeftSpace [ text ]

Trim spaces and only spaces from the left side of a string passed as arguments or a pipe

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs trimmed lines

Arguments

  • text - EmptyString. Optional. Text to remove spaces. If no arguments are supplied it is assumed that input should be read from standard input.

Examples

trimLeftSpace "$token"
grep "$tokenPattern" | trimLeftSpace > "$tokensFound"

Return codes

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

Usage

trimRightSpace [ text ]

Trim spaces and only spaces from the right side of a string passed as arguments or a pipe

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs trimmed lines

Arguments

  • text - EmptyString. Optional. Text to remove spaces. If no arguments are supplied it is assumed that input should be read from standard input.

Examples

trimRightSpace "$token"
grep "$tokenPattern" | trimRightSpace > "$tokensFound"

Return codes

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

Usage

trimHead [ --help ]

Removes any blank lines from the beginning of a stream

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Arguments

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

Return codes

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

Usage

trimTail [ --help ]

Removes any blank lines from the end of a stream

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Arguments

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

Return codes

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

Usage

trimBoth [ --help ]

Trim whitespace from beginning and end of a stream

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Arguments

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

Return codes

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

Usage

singleBlankLines [ --help ]

Ensures blank lines are singular Used often to clean up markdown .md files, but can be used for any line-based configuration file which allows blank lines.

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines where any blank lines are replaced with a single blank line.

Arguments

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

Return codes

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

Finding or Calculating

Usage

inArray [ element ] [ arrayElement0 ... ]

Check if an element exists in an array Without arguments, displays help.

Arguments

  • element - EmptyString. Thing to search for
  • arrayElement0 ... - Array. Optional. One or more array elements to match

Examples

if inArray "$thing" "${things[@]+"${things[@]}"}"; then
    things+=("$thing")
fi

Return codes

  • 0 - If element is found in array
  • 1 - If element is NOT found in array

Usage

stringFound needle [ haystack ... ]

Check if one string is a substring of another set of strings (case-sensitive)

Arguments

  • needle - String. Required. Thing to search for, not blank.
  • haystack ... - EmptyString. Optional. One or more array elements to match

Return codes

  • 0 - If element is a substring of any haystack
  • 1 - If element is NOT found as a substring of any haystack

Usage

stringFoundInsensitive needle [ haystack ... ]

Check if one string is a substring of another set of strings (case-insensitive)

Arguments

  • needle - String. Required. Thing to search for, not blank.
  • haystack ... - EmptyString. Optional. One or more array elements to match

Return codes

  • 0 - If element is a substring of any haystack
  • 1 - If element is NOT found as a substring of any haystack

Usage

stringBegins haystack [ needle ... ]

Does needle exist as a substring of haystack?

Arguments

  • haystack - String. Required. String to search.
  • needle ... - String. Optional. One or more strings to find as the "start" of haystack.

Return codes

  • 0 - IFF ANY needle matches as a substring of haystack
  • 1 - No needles found in haystack

Usage

stringBeginsInsensitive haystack [ needle ... ]

Does needle exist as a substring of haystack? (case-insensitive)

Arguments

  • haystack - String. Required. String to search. (case-insensitive)
  • needle ... - String. Optional. One or more strings to find as the "start" of haystack (case-insensitive)

Return codes

  • 0 - IFF ANY needle matches as a substring of haystack (case-insensitive)
  • 1 - No needles found in haystack (case-insensitive)

Usage

stringContains haystack [ needle ... ]

Does needle exist as a substring of haystack?

Arguments

  • haystack - String. Required. String to search.
  • needle ... - String. Optional. One or more strings to find as a substring of haystack.

Return codes

  • 0 - IFF ANY needle matches as a substring of haystack
  • 1 - No needles found in haystack

Usage

stringContainsInsensitive haystack [ needle ... ]

Does needle exist as a substring of haystack?

Arguments

  • haystack - String. Required. String to search.
  • needle ... - String. Optional. One or more strings to find as a case-insensitive substring of haystack.

Return codes

  • 0 - IFF ANY needle matches as a substring of haystack
  • 1 - No needles found in haystack

Usage

stringBegins haystack [ needle ... ]

Does needle exist as a substring of haystack?

Arguments

  • haystack - String. Required. String to search.
  • needle ... - String. Optional. One or more strings to find as the "start" of haystack.

Return codes

  • 0 - IFF ANY needle matches as a substring of haystack
  • 1 - No needles found in haystack

Usage

stringOffset needle haystack

Outputs the integer offset of needle if found as substring in haystack If haystack is not found, -1 is output

Writes to standard output

Integer. The offset at which the needle was found in haystack. Outputs -1 if not found.

Arguments

  • needle - String. Required.
  • haystack - String. Required.

Return codes

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

Usage

stringOffsetInsensitive needle haystack

Outputs the integer offset of needle if found as substring in haystack (case-insensitive) If haystack is not found, -1 is output

Writes to standard output

Integer. The offset at which the needle was found in haystack. Outputs -1 if not found.

Arguments

  • needle - String. Required.
  • haystack - String. Required.

Return codes

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

Usage

fileFieldMaximum fieldIndex [ separatorChar ]

Given an input file, determine the maximum length of fieldIndex, using separatorChar as a delimiter between fields Defaults to first field (fieldIndex of 1), space separator (separatorChar is )

Reads standard input

Lines are read from standard in and line length is computed for each line

Writes to standard output

UnsignedInteger

Arguments

  • fieldIndex - UnsignedInteger. Required. The field to compute the maximum length for
  • separatorChar - String. Optional. The separator character to delineate fields. Uses space if not supplied.

Return codes

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

Usage

fileLineMaximum

Outputs the maximum line length passed into stdin

Reads standard input

Lines are read from standard in and line length is computed for each line

Writes to standard output

UnsignedInteger

Arguments

  • none

Return codes

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

Usage

fileEndsWithNewline file ...

Does a file end with a newline or is empty? Typically used to determine if a newline is needed before appending a file.

Arguments

  • file ... - File. Required. File to check if the last character is a newline.

Return codes

  • 0 - All files ends with a newline
  • 1 - One or more files ends with a non-newline

Usage

plural number singular [ plural ]

Outputs the singular value to standard out when the value of number is one. Otherwise, outputs the plural value to standard out. Example:

Writes to standard output

String. The plural form for non-1 values. e.g. $(plural 2 potato potatoes) = potatoes

Arguments

  • number - Number. Required. An integer or floating point number
  • singular - String. Required. The singular form of a noun
  • plural - String. Optional. The plural form of a noun. If not specified uses singular plus an ess.

Examples

count=$(fileLineCount "$foxSightings") || return $?
printf "We saw %d %s.\n" "$count" "$(plural "$count" fox foxes)"
n=$(($(date +%s)) - start))
printf "That took %d %s" "$n" "$(plural "$n" second seconds)"

Return codes

  • 1 - If count is non-numeric
  • 0 - If count is numeric

Usage

pluralWord number singular [ plural ]

Plural word which includes the numeric prefix and the noun.

Writes to standard output

String. The number (direct) and the plural form for non-1 values. e.g. $(pluralWord 2 potato potatoes) = 2 potatoes

Arguments

  • number - Number. Required. An integer or floating point number
  • singular - String. Required. The singular form of a noun
  • plural - String. Optional. The plural form of a noun. If not specified uses singular plus an ess.

Examples

count=$(fileLineCount "$foxSightings") || return $?
printf "We saw %s.\n" "$(pluralWord "$count" fox foxes)"

Return codes

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

Usage

parseBoolean

Parses text and determines if it's true-ish Without arguments, displays help.

Arguments

  • none

Return codes

  • 0 - true
  • 1 - false
  • 2 - Neither
  • 0 - Text is plain
  • 1 - Text contains non-plain characters

Requires

lowercase __help

Transformation

Usage

lowercase [ -- ] [ --help ] text

Convert text to lowercase

Writes to standard output

String. The lowercase version of the text.

Arguments

  • -- - Flag. Optional. Stops command processing to enable arbitrary text to be passed as additional arguments without special meaning.
  • --help - Flag. Optional. Display this help.
  • text - EmptyString. Required. Text to convert to lowercase

Return codes

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

Requires

tr

Usage

uppercase [ -- ] [ --help ] text

Convert text to uppercase

Writes to standard output

String. The uppercase version of the text.

Arguments

  • -- - Flag. Optional. Stops command processing to enable arbitrary text to be passed as additional arguments without special meaning.
  • --help - Flag. Optional. Display this help.
  • text - EmptyString. Required. text to convert to uppercase

Return codes

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

Requires

tr

Usage

shaPipe [ filename ... ] [ --cache cacheDirectory ]

Generates a checksum of standard input and outputs a SHA1 checksum in hexadecimal without any extra stuff You can use this as a pipe or pass in arguments which are files to be hashed.

Reads standard input

any file

Writes to standard output

String. A hexadecimal string which uniquely represents the data in stdin.

Arguments

  • filename ... - File. One or more filenames to generate a checksum for
  • --cache cacheDirectory - Directory. Cache file cache values here for speed optimization.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • shaPipe - Outputs all requested shaPipe calls to log called shaPipe.log.

Examples

shaPipe < "$fileName"
shaPipe "$fileName0" "$fileName1"

Sample Output

cf7861b50054e8c680a9552917b43ec2b9edae2b

Return codes

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

Usage

cannon [ --help ] [ --handler handler ] [ --path cannonPath ] fromText toText [ findArgs ... ]

Replace text fromText with toText in files, using findArgs to filter files if needed. This can break your files so use with caution. Blank searchText is not allowed. The term cannon is not a mistake - it will break something at some point.

Arguments

  • --help - Flag. Optional. Display this help.
  • --handler handler - Function. Optional. Use this error handler instead of the default error handler.
  • --path cannonPath - Directory. Optional. Run cannon operation starting in this directory.
  • fromText - Required. String of text to search for.
  • toText - Required. String of text to replace.
  • findArgs ... - Arguments. Optional. Any additional arguments are meant to filter files.

Examples

cannon master main ! -path '*/old-version/*')

Return codes

  • 0 - Success, no files changed
  • 3 - At least one or more files were modified successfully
  • 1 - --path is not a directory
  • 1 - searchText is not blank
  • 1 - fileTemporaryName failed
  • 2 - Arguments are identical

Usage

stringReplace needle [ replacement ] [ haystack ]

Replace all occurrences of a string within another string

Reads standard input

If no haystack supplied reads from standard input and replaces the string on each line read.

Writes to standard output

New string with needle replaced

Arguments

  • needle - String. Required. String to replace.
  • replacement - EmptyString. String to replace needle with.
  • haystack - EmptyString. Optional. String to modify. If not supplied, reads from standard input.

Return codes

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

Random

Usage

randomString

Outputs 40 random hexadecimal characters, lowercase.

Writes to standard output

String. A random hexadecimal string.

Arguments

  • none

Examples

testPassword="$(randomString)"

Sample Output

cf7861b50054e8c680a9552917b43ec2b9edae2b

Return codes

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