Skip to content

Text Functions

🛠️ Tools · ⬅ Home

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

Arguments

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

Return codes

  • 0 - Normal operation

textReplaceFirst

Replaces the first and only the first occurrence of a

Usage

textReplaceFirst [ searchString ] [ replaceString ]

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

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Return codes

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

textRemoveFields

Remove fields from left to right from a text file

Usage

textRemoveFields [ fieldCount ]

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

Arguments

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

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.

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.

Arguments

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

Reads standard input

text (Optional)

Writes to standard output

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

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.

Arguments

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

Reads standard input

text (Optional)

Writes to standard output

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

Return codes

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

printfOutputEmpty

printf when output is blank

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.

Arguments

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

Reads standard input

text (Optional)

Writes to standard output

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

Examples

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

Return codes

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

Formatting

textAlignLeft

align text left

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

textAlignRight

align text right

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

ANSI text

isPlain

Check if text contains plain text only (no ANSI escape

Usage

isPlain text

Check if text contains plain text only (no ANSI escape codes, etc.) 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

consoleToPlain

Strip ANSI console escape sequences from a file

Usage

consoleToPlain [ None. ]

Strip ANSI console escape sequences from a file

Arguments

  • None.

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

Return codes

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

Environment

  • None.

Credits

Thanks to commandlinefu tripleee .

consoleTrimWidth

Truncate console output width

Usage

consoleTrimWidth width [ text ]

Truncate console output width

Arguments

  • width - UnsignedInteger. Required. Width to maintain.
  • text - String. Optional. Text to trim to a console 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.

Return codes

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

consolePlainLength

Length of an unformatted string

Usage

consolePlainLength [ text ]

Length of an unformatted string

Arguments

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

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.

Return codes

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

Space

stringTrimWords

Remove words from the end of a phrase

Usage

stringTrimWords [ 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:" "$(stringTrimWords 10 $description)"

Return codes

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

textTrim

Trim whitespace of a bash argument

Usage

textTrim [ text ]

Trim spaces and only spaces from arguments or a pipe

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs trimmed lines

Examples

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

Return codes

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

Credits

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

textTrimLeft

Trim whitespace of a bash argument

Usage

textTrimLeft [ text ]

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

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs trimmed lines

Examples

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

Return codes

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

textTrimRight

Trim whitespace of a bash argument

Usage

textTrimRight [ text ]

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

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs trimmed lines

Examples

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

Return codes

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

textTrimHead

Removes any blank lines from the beginning of a stream

Usage

textTrimHead [ --help ]

Removes any blank lines from the beginning of a stream

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Return codes

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

textTrimTail

Removes any blank lines from the end of a stream

Usage

textTrimTail [ --help ]

Removes any blank lines from the end of a stream

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Return codes

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

textTrimBoth

Trim whitespace from beginning and end of a stream

Usage

textTrimBoth [ --help ]

Trim whitespace from beginning and end of a stream

Arguments

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

Reads standard input

Reads lines from stdin until EOF

Writes to standard output

Outputs modified lines

Return codes

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

textSingleBlankLines

Ensures blank lines are singular

Usage

textSingleBlankLines [ --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.

Arguments

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

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.

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

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

stringFound

Check if one string is a substring of another set

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

stringFoundInsensitive

Check if one string is a substring of another set

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

stringBegins

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

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

stringBeginsInsensitive

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

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)

stringContains

Find whether a substring exists in one or more strings

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

stringContainsInsensitive

Find whether a substring exists in one or more strings

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

stringBegins

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

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

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

Arguments

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

Writes to standard output

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

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

Arguments

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

Writes to standard output

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

Return codes

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

fileFieldMaximum

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

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 )

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.

Reads standard input

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

Writes to standard output

UnsignedInteger

Return codes

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

fileLineMaximum

Outputs the maximum line length passed into stdin

Usage

fileLineMaximum

Outputs the maximum line length passed into stdin

Arguments

  • none

Reads standard input

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

Writes to standard output

UnsignedInteger

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.

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

localePlural

Outputs the singular value to standard out when the value

Usage

localePlural number singular [ localePlural ]

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

Arguments

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

Writes to standard output

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

Examples

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

Return codes

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

localePluralWord

Plural word which includes the numeric prefix and the noun.

Usage

localePluralWord number singular [ localePlural ]

Plural word which includes the numeric prefix and the noun.

Arguments

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

Writes to standard output

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

Examples

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

Return codes

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

booleanParse

Parses text and determines if it's true-ish

Usage

booleanParse

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

Transformation

stringLowercase

Convert text to stringLowercase

Usage

stringLowercase [ -- ] [ --help ] text

Convert text to stringLowercase

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 stringLowercase

Writes to standard output

String. The stringLowercase version of the text.

Return codes

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

Requires

  • tr

stringUppercase

Convert text to uppercase

Usage

stringUppercase [ -- ] [ --help ] text

Convert text to uppercase

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

Writes to standard output

String. The stringUppercase version of the text.

Return codes

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

Requires

  • tr

stringUnquote

Unquote a string

Usage

stringUnquote quote value

Unquote a string

Arguments

  • quote - String. Required. Must match beginning and end of string.
  • value - String. Required. Value to unquote.

Return codes

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

stringHideNewlines

Replace newlines in text with a replacement token for single-line output

Usage

stringHideNewlines [ --help ] text [ replace ]

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

Arguments

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

Writes to standard output

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

Return codes

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

textSHA

SHA1 checksum of standard input

Usage

textSHA [ 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.

Arguments

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

Reads standard input

any file

Writes to standard output

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

Debugging settings

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

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

Examples

textSHA < "$fileName"
textSHA "$fileName0" "$fileName1"

Sample Output

cf7861b50054e8c680a9552917b43ec2b9edae2b

Return codes

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

textCannon

Replace text fromText with toText in files

Usage

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

textCannon 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

textReplace

Replace all occurrences of a string within another string

Usage

textReplace needle [ replacement ] [ haystack ]

Replace all occurrences of a string within another string

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.

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

Return codes

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

Random

stringRandom

Outputs 40 random hexadecimal characters, stringLowercase.

Usage

stringRandom

Outputs 40 random hexadecimal characters, stringLowercase.

Arguments

  • none

Writes to standard output

String. A random hexadecimal string.

Examples

testPassword="$(stringRandom)"

Sample Output

cf7861b50054e8c680a9552917b43ec2b9edae2b

Return codes

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

Numeric

textVersionSort

Sort versions in the format v0.0.0

Usage

textVersionSort [ -r | --reverse ] [ --help ]

Sorts semantic versions prefixed with a v character; intended to be used as a pipe. vXXX.XXX.XXX for sort - -k 1.c,1 - the c is the 1-based character index, so 2 means skip the 1st character Odd you can't globally flip sort order with -r - that only works with non-keyed entries I assume

Arguments

-r |- --reverse - Reverse the sort order (optional) - --help - Flag. Optional. Display this help.

Examples

git tag | grep -e '^v[0-9.]*$' | textVersionSort

Return codes

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

integerClamp

Clamp digits between two integers

Usage

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

sedReplacePattern

Quote a sed command for search and replace

Usage

sedReplacePattern searchPattern replacePattern

Quote a sed command for search and replace Without arguments, displays help.

Arguments

  • searchPattern - String. Required. The string to search for.
  • replacePattern - String. Required. The replacement to replace with.

Return codes

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

quoteSedPattern

Quote sed search strings for shell use

Usage

quoteSedPattern text

Quote a string to be used in a sed pattern on the command line.

Arguments

  • text - EmptyString. Required. Text to quote

Examples

sed "s/$(quoteSedPattern "$1")/$(quoteSedPattern "$2")/g"
needSlash=$(quoteSedPattern '$.*/[\]^')

Sample Output

string quoted and appropriate to insert in a sed search or replacement phrase

Return codes

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

quoteSedReplacement

Quote sed replacement strings for shell use

Usage

quoteSedReplacement text [ separatorChar ]

Quote sed replacement strings for shell use

Arguments

  • text - EmptyString. Required. Text to quote
  • separatorChar - The character used to separate the sed pattern and replacement. Defaults to /.

Examples

sed "s/$(quoteSedPattern "$1")/$(quoteSedReplacement "$2")/g"
needSlash=$(quoteSedPattern '$.*/[\]^')

Sample Output

string quoted and appropriate to insert in a sed replacement phrase

Return codes

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

🛠️ Tools · ⬅ Top