Utility Functions

These functions are designed to be used by themes.

_lp_as_text(string) → stdout: Deprecated since version 2.1: Use __lp_strip_escapes() instead.

Return string with all shell escaped substrings removed.

_lp_bool(variable[, code]): Deprecated since version 2.0.

Stores the code in a variable named variable. If code is not set, uses the last return code instead.

__lp_bytes_to_human(bytes[, precision]) → var:lp_bytes, var:lp_bytes_units

Convert the given bytes into a human readable format, using binary multiple-byte units. E.g.: KiB instead of KB, 1024 instead of 1000.

Precision can be 0, 1 or 2 digits. If not given, precision is two digits.

Converted value goes into lp_bytes and its unit in lp_bytes_units.

Note that after petabytes (PiB) of data, Bash and Zsh will start failing at integer computations.

New in version 2.2.

_lp_color_map(value, scale=100) → var:ret

Returns a color from the configured or default color map based on value and optional scale.

Values below 0 or above scale will be capped.

The returned string is a fully escaped terminal formatting sequence.

_lp_create_link(url, text) → var:lp_link

Adds the url link to the given text.

See LP_ENABLE_HYPERLINKS.

_lp_create_link_path(path) → lp_link_path

Adds a link on the given path, with the protocol scheme depending on the current connection type.

If the current connection is SSH, adds an SFTP:// URL, if it is su or lcl (see _lp_connection()), adds a file:// one.

_lp_fill(left, right[, fillstring[, splitends]]) → var:lp_fill

Adds as much fillstring (e.g. spaces) between left and right, so as to make the resulting string the same width as the current terminal.

If fillstring is omitted, it defaults to one space.

If fillstring is a string with several characters and splitends is 1 (the default), then the final occurrence of fillstring will have its end cut, so as to fit the terminal width.

If fillstring has multiple characters and splitends is 0, some spaces will be inserted after the last occurrence of fillstring, so as to match the exact width of the terminal.

Note

Any escaped sequence in fillstring will be removed automatically.: The end of left and the beginning of right may be used to add escaped sequences at the beginning and, respectively, the end of the filling sequence.

If the available number of columns in the terminal is smaller than the width of left and right combined, then the function will return code 1 and set lp_fill to left and right, concatenated.

For example, _lp_fill "Left part·" "·right part" "⣀⠔⠉⠢" 1 will render (in a terminal being 32 characters large):

Left part·⣀⠔⠉⠢⣀⠔⠉⠢⣀⠔⠉·right part

New in version 2.2.

_lp_formatted_title(title)

Sets the theme generated title to title. The input is escaped using __lp_strip_escapes() to strip terminal formatting from being added to the title.

This function will do nothing and return 2 if LP_ENABLE_TITLE is disabled.

New in version 2.0.

_lp_grep_fields(filename, delimiter, keys...) → var:lp_grep_fields

Parse the given filename for one key/value pairs of the form “<key><delimiter><value>” (e.g. “this=that”) on each line. Sets an array containing the parsed values, for each key in the same order the function was called.

Example of use

_lp_grep_fields "CMakeCache.txt" "=" "CMAKE_C_COMPILER:FILEPATH" "CMAKE_CXX_COMPILER:FILEPATH"
cmake_c_compiler=${lp_grep_fields[_LP_FIRST_INDEX+0]-}
cmake_cxx_compiler=${lp_grep_fields[_LP_FIRST_INDEX+1]-}

Note

Bash and Zsh are using different array indexing schemes. To write portable code, you should use _LP_FIRST_INDEX.

Warning

It is strongly advised not to loop over the items in lp_grep_fields. If a searched key is missing in the file, its corresponding entry in the array will be silently skipped, and thus the indices you would expect may lead to unset variables. Just use explicit indexing to access the parsed values.

Returns 1 if the file does not exists.

New in version 2.2.

_lp_hash_color(str) → var:lp_hash_color: Colorize the given string with a color depending on its hash. The color is chosen among: (green, yellow, blue, purple, cyan). Note that the red color is not a candidate, as it should be reserved for alerts.

New in version 2.2.

_lp_join(delimiter, items...) → var:lp_join: Join all strings in items with the given delimiter. Example: _lp_join ", " "a" "b" "c" will render lp_join="a, b, c"

New in version 2.2.

_lp_raw_title(title)

Sets the theme generated title to title. The input is not escaped in any way: if the input contains terminal formatting, use _lp_formatted_title() instead.

This function will do nothing and return 2 if LP_ENABLE_TITLE is disabled.

New in version 2.0.

_lp_sb(string) → stdout: Deprecated since version 2.0: Use the return code of the source data function to determine if any string was returned.

If string is set and not empty, returns string padded with an extra space on the right and the left.

_lp_sl(string) → stdout: Deprecated since version 2.0: Use the return code of the source data function to determine if any string was returned.

If string is set and not empty, returns string padded with an extra space on the left.

_lp_sr(string) → stdout: Deprecated since version 2.0: Use the return code of the source data function to determine if any string was returned.

If string is set and not empty, returns string padded with an extra space on the right.

_lp_smart_mark([vcs_type][, vcs_subtype]) → var:lp_smart_mark

Returns a string set to the configured mark matching vcs_type. If vcs_type is not set, uses the value of lp_vcs_type instead.

If the type is “git”, matches vcs_subtype to see if the repository is of type VCSH or git-svn instead, and return their marks if so. If vcs_subtype is not set, uses the value of lp_vcs_subtype instead.

Changed in version 2.1: Added vcs_subtype argument.

_lp_substitute(string, pairs_array) → var:lp_substitute

If the given string is found in the given array of pairs, return the second element of the pair for which the first element matches the string.

For instance:

pairs=(
    "A" "B" # Replace A by B.
    "something" "dead pixels"
    "I see" "nothing"
)
_lp_substitute "something" "${pairs[@]}"
# "$lp_substitute" == "dead pixels"

New in version 2.2.

_lp_title(title) → stdout

Not to be confused with lp_title().

Deprecated since version 2.0: Use _lp_formatted_title instead.

Formats title with title escape codes. The input is escaped using __lp_strip_escapes() to strip terminal formatting from being added to the title. The output should be added to PS1 to be printed as a title.

This function will do nothing if LP_ENABLE_TITLE is disabled.

_lp_version_greatereq(major, minor[, patch[, string[, number]]])

Returns true (0) if Liquid Prompt version is greater than or equal to the the given version. Returns 1 (false) if there is a minor or less version difference, and 2 (false) if it is a major difference.