Skip to content

Text Functions

🛠️ Tools · ⬅ Top

Patterns

isPlain

Check if text contains plaintext only.

Usage

isPlain text

Check if text contains plaintext only. Without arguments, displays help. Return code: - 0 - Text is plain Return code: - 1 - Text contains non-plain characters

Arguments

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

Return codes

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

Filters

grepSafe

grep but returns 0 when nothing matches

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 Return Code: 0 - Normal operation

Arguments

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

Return codes

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

Requires

grep mapReturn

replaceFirstPattern

Replaces the first and only the first occurrence of a

Usage

replaceFirstPattern

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

  • none

Return codes

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

removeFields

Remove fields from left to right from a text file

Usage

removeFields fieldCount < input > output

Remove fields from left to right from a text file as a pipe Partial Credit: https://stackoverflow.com/questions/4198138/printing-everything-except-the-first-field-with-awk/31849899#31849899

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 - Optional. Integer. Number of field to remove. Default is just first 1.

Return codes

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

clampDigits

Clamp digits between two integers

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

Return codes

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

printfOutputPrefix

Pipe to output some text before any output, otherwise, nothing

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

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

Return codes

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

printfOutputSuffix

Pipe to output some text after any output, otherwise, nothing

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

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

Return codes

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

newlineHide

Hide newlines in text (to ensure single-line output or other

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

Cleanup ANSI text

stripAnsi

Strip ANSI console escape sequences from a file

Usage

stripAnsi [ None. ]

Strip ANSI console escape sequences from a file Write Environment: None. Short description: Remove ANSI escape codes from streams

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 .

plainLength

Length of an unformatted string

Usage

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

trimWords

Remove words from the end of a phrase

Usage

trimWords [ wordCount [ word0 ... ] ]

Remove words from the end of a phrase

Arguments

  • wordCount - Words to output
  • word0 - 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

trimSpace

Trim whitespace of a bash argument

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 - Optional. EmptyString. 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) .

trimHead

Removes any blank lines from the beginning of a stream

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

Return codes

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

trimTail

Removes any blank lines from the end of a stream

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

Return codes

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

trimBoth

Trim whitespace from beginning and end of a stream

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

Return codes

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

singleBlankLines

Ensures blank lines are singular

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

Return codes

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

Finding or Calculating

inArray

Check if an element exists in an array

Usage

inArray element [ arrayElement0 arrayElement1 ... ]

Check if an element exists in an array

Return Code: 0 - If element is found in array Return Code: 1 - If element is NOT found in array Without arguments, displays help.

Arguments

  • element - Thing to search for
  • arrayElement0 - One or more array elements to match

Examples

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

Return codes

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

isSubstring

Check if one string is a substring of another set

Usage

isSubstring needle [ haystack ... ]

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

Return Code: 0 - If element is a substring of any haystack Return Code: 1 - If element is NOT found as a substring of any haystack

Arguments

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

Return codes

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

isSubstringInsensitive

Check if one string is a substring of another set

Usage

isSubstringInsensitive needle [ haystack ... ]

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

Return Code: 0 - If element is a substring of any haystack Return Code: 1 - If element is NOT found as a substring of any haystack

Arguments

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

Return codes

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

stringBegins

Find whether a substring exists as teh beginning of one or more strings

Usage

stringBegins haystack [ needle ... ]

Return Code: 0 - IFF ANY needle matches as a substring of haystack Return Code: 1 - No needles found in haystack Does needle exist as a substring of haystack?

Arguments

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

Return codes

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

stringBeginsInsensitive

Find whether a substring exists as teh beginning of one or more strings

Usage

stringBeginsInsensitive haystack [ needle ... ]

Return Code: 0 - IFF ANY needle matches as a substring of haystack (case-insensitive) Return Code: 1 - No needles found in haystack (case-insensitive) Does needle exist as a substring of haystack? (case-insensitive)

Arguments

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

Return codes

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

stringContains

Find whether a substring exists in one or more strings

Usage

stringContains haystack needle ...

Return Code: 0 - IFF ANY needle matches as a substring of haystack Return Code: 1 - No needles found in haystack Does needle exist as a substring of haystack?

Arguments

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

Return codes

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

stringContainsInsensitive

Find whether a substring exists in one or more strings

Usage

stringContainsInsensitive haystack needle ...

Return Code: 0 - IFF ANY needle matches as a substring of haystack Return Code: 1 - No needles found in haystack Does needle exist as a substring of haystack?

Arguments

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

Return codes

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

beginsWith

Return Code: 0 - If text has any prefix

Usage

beginsWith text prefixText ...

Return Code: 0 - If text has any prefix Does text have one or more prefixes?

Arguments

  • text - Optional. String. String to match.
  • prefixText - Required. String. One or more. Does this prefix exist in our text?

Return codes

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

stringOffset

Outputs the integer offset of needle if found as substring

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

stringOffsetInsensitive

Outputs the integer offset of needle if found as substring

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

maximumFieldLength

Given an input file, determine the maximum length of fieldIndex,

Usage

maximumFieldLength 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

maximumLineLength

Outputs the maximum line length passed into stdin

Usage

maximumLineLength

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

fileEndsWithNewline

Does a file end with a newline or is empty?

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.

Return Code: 0 - All files ends with a newline Return Code: 1 - One or more files ends with a non-newline

Arguments

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

Return codes

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

plural

Outputs the singular value to standard out when the value

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.

Short description: Output numeric messages which are grammatically accurate

Return Code: 1 - If count is non-numeric Return Code: 0 - If count is numeric Example:

Writes to standard output

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

Arguments

  • number - Required. An integer or floating point number
  • singular - Required. The singular form of a noun
  • plural - 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

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

pluralWord

Plural word which includes the numeric prefix and the noun.

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 - Required. An integer or floating point number
  • singular - Required. The singular form of a noun
  • plural - 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

parseBoolean

Parses text and determines if it's true-ish

Usage

parseBoolean

Parses text and determines if it's true-ish

Return Code: 0 - true Return Code: 1 - false Return Code: 2 - Neither Without arguments, displays help. Return code: - 0 - Text is plain Return code: - 1 - Text contains non-plain characters

Arguments

  • none

Return codes

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

Requires

lowercase __help

Transformation

lowercase

Convert text to lowercase

Usage

lowercase [ -- ] [ --help ] text

Convert text to lowercase

Writes to standard output

String. The lowercase version of the text.

Arguments

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

Return codes

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

Requires

tr

uppercase

Convert text to uppercase

Usage

uppercase [ -- ] [ --help ] text

Convert text to uppercase

Writes to standard output

String. The uppercase version of the text.

Arguments

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

Return codes

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

Requires

tr

shaPipe

SHA1 checksum of standard input

Usage

shaPipe [ filename ... ]

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 - One or more filenames to generate a checksum for

Examples

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

Sample Output

cf7861b50054e8c680a9552917b43ec2b9edae2b

Return codes

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

Environment

  • DEBUG_SHAPIPE - When set to a truthy value, will output all requested shaPipe calls to log called shaPipe.log.

cachedShaPipe

SHA1 checksum of standard input

Usage

cachedShaPipe cacheDirectory [ filename ]

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.

Speeds up shaPipe using modification dates of the files instead.

The cacheDirectory

Reads standard input

any file

Writes to standard output

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

Arguments

  • cacheDirectory - Optional. Directory. The directory where cache files can be stored exclusively for this function. Supports a blank value to disable caching, otherwise, it must be a valid directory.

Examples

cachedShaPipe "$cacheDirectory" < "$fileName"
cachedShaPipe "$cacheDirectory" "$fileName0" "$fileName1"

Sample Output

cf7861b50054e8c680a9552917b43ec2b9edae2b

Return codes

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

cannon

Replace text fromText with toText in files, using findArgs to

Usage

cannon [ --path directory ] [ --help ] 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.

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

Arguments

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

Examples

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

Return codes

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

stringReplace

Replace all occurrences of a string within another string

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

randomString

Outputs 40 random hexadecimal characters, lowercase.

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