LIQUIDPROMPT(3)

NAME
liquidprompt - Liquid Prompt functions

Functions starting with lp or any other alphanumeric character are public functions designed to be used by users on the command line or in their config.

Functions starting with _lp are theme level functions, designed to be used by themes. These include data, theme, and utility functions.

Functions starting with __lp are internal functions, designed to be used only by Liquid Prompt internals. These functions should not be used by users or themes, as they are not guaranteed to not change between versions.

PUBLIC FUNCTIONS

These functions are designed to be used by users on the command line or in their config.

lp_activate()
    Reload the user config.

    This function is called when sourcing liquidprompt, unless the flag --no-activate is passed.

    The config is sourced, and the environment scanned again for programs needed for specific features.

    Lastly, prompt_on() is called to enabled the prompt.

    New in version 2.0.

lp_title([title_string])
    Not to be confused with _lp_title().

    Set title_string as the terminal title. This overrides any title set by the current theme.

    NOTE: The input string is not escaped in any way; if it contains characters that the shell will interpret, the user must escape them if that behavior is not desired.

    To unset the manual title, call lp_title() with no arguments.

    To set a blank title, call lp_title() with an empty string argument ('').

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

    New in version 2.0.

lp_theme(theme_id | --list)
    Load and activate the theme named theme_id. The theme functions must be loaded into memory before lp_theme() can be called, normally by sourcing the theme file.

    The optional flag --list will instead list all currently loaded themes.

    The variable LP_THEME can be set to a theme name, which is essentially equivalent to calling this function. LP_THEME will always hold the currently active theme; it is updated by this function. If LP_THEME is set to an invalid theme name, it will be reset to the previous value.

    This function supports shell autocompletion.

    New in version 2.0.

    Changed in version 2.2: LP_THEME reading and setting added.

lp_terminal_format(foreground_color[, background_color][, bold][, underline][, fallback_foreground_color][, fallback_background_color]) -> var:lp_terminal_format
    Generate a shell escaped terminal formatting string for use in PS1.

    The start of the formatting string always resets back to terminal defaults.

    foreground_color and background_color accept an ANSI escape color code integer to set the color of the foreground and background, respectively. The behavior depends on the integer:

•   >= 0 && < max_color - The color is used directly.

•   >= max_color - If the terminal reports that the number of colors it supports is less than the input color code, the fallback_foreground_color or fallback_background_color is used instead.

•   -1 - No color is set. This does not mean that the previous color will continue over, as all formatting is reset to default at the start of the sequence. This means the default coloring is effectively set.

•   -2 - The previous color of the field is set. If no color was previously set, no color will be set. Note that the output is a static formatting string; the string will not keep the same color as the terminal previously had, but the color that was last selected when lp_terminal_format() was last run.

•   -3 - Same as -2, except the opposite field color is copied. In other words, if foreground_color is set to -3, it will copy the color of background_color the last time lp_terminal_format() was run.

    bold and underline enable their respective formats when set to 1. If omitted or set to 0, they are not enabled. To use fallback colors, they will need to be set to be able to set the other options.

    fallback_foreground_color and fallback_background_color are used when the normal colors are higher than the terminal supported colors. The special negative inputs do not work for these options, and they are not checked for compatibility before being used, so it is recommended that they are in the range 0-7. When setting foreground_color or background_color to negative inputs, these options are never checked.

    For example, to set the error color to a bright, bold pink, with a fallback color of red:

    lp_terminal_format 204 -1 1 0 1
    LP_COLOR_ERR=$lp_terminal_format

    To set the prompt mark color to black on a white background:

    lp_terminal_format 0 7
    LP_COLOR_MARK=$lp_terminal_format

    New in version 2.0.

prompt_on()
    Enable the prompt generation and setting.

    This function is called when sourcing liquidprompt, unless the flag --no-activate is passed.

prompt_off()
    Disable the prompt generation and setting, and restore the old PS1.

    If the shell is Bash, also restore the old PROMPT_COMMAND.

    If the shell is Zsh, also restore the old prompt theme.

prompt_OFF()
    Same as prompt_off(), except instead of restoring the previous PS1, it is set to "$ " on Bash, "% " on Zsh.

prompt_tag([prefix_string])
    Sets a prefix that will be displayed before every prompt. Postpends a space to the input string.

    Internally, this function sets LP_PS1_PREFIX to prefix_string. If a trailing space is not wanted, set LP_PS1_PREFIX manually.

    To unset the prefix, call prompt_tag() with no arguments.

DATA FUNCTIONS

•   Battery

•   Development Environment

•   Disks and Memory

•   Environment

•   Jobs

•   Load

•   OS

•   Path

•   Runtime

•   Temperature

•   Time

•   Wireless

  Version Control Data Functions

•   Generic

•   Bazaar

•   Fossil

•   Git

•   Mercurial

•   Subversion

    These functions are designed to be used by themes.

  Generic

The generic interface functions are designed to provide a level of abstraction over the type of VCS that a user might be using. By using the generic interface, a theme can provide a common look for all VCS types. See the default theme function _lp_vcs_details_color() for an example of this.

_lp_find_vcs() -> var:lp_vcs_type, var:lp_vcs_root, var:lp_vcs_dir, var:lp_vcs_specific_dir, var:lp_vcs_subtype
    Returns true if the current directory is part of a version control repository. If not, returns 1. Returns the VCS type ID, subtype if one exists, the VCS data directory, and the repository root directory.

    If the current directory is disabled for version control using LP_DISABLED_VCS_PATHS (checked using _lp_are_vcs_enabled()), returns 2, and the returned type is set to "disabled".

    _lp_find_vcs() will only search for VCS types that are not disabled. If all VCS types are disabled in the config, _lp_find_vcs() will return 1, as no repository will be found.

    This function does a lightweight check for the existence of a version control repository, only looking for the existence of a database. It does not check if the database is valid or healthy. Use _lp_vcs_active() to test for that.

    Git worktrees have two Git directories: one is the main directory in lp_vcs_dir, which holds the DB and config. The other is the worktree specific directory in lp_vcs_specific_dir, which holds working directory specific information, like index and status like merge or rebase in progress.

    NOTE: lp_vcs_dir will not be set for Fossil repositories. Protect it with "${lp_vcs_dir-}".

    NOTE: lp_vcs_specific dir will only be set for Git repositories. Protect it with "${lp_vcs_specific_dir-}".

    NOTE: lp_vcs_subtype will not be set usually. The only currently supported subtypes are vcsh and svn, which are subtypes of git.

    New in version 2.0.

    Changed in version 2.1: Added the lp_vcs_dir and lp_vcs_subtype return values. Added support for checking the GIT_DIR environment variable.

    Changed in version 2.2: Added the lp_vcs_specific_dir return value.

_lp_are_vcs_enabled()
    Returns true if the current directory is not excluded by the config option LP_DISABLED_VCS_PATHS.

    NOTE: All following generic functions need _lp_find_vcs() to be run first, as they need lp_vcs_type to be set.

_lp_vcs_active()
    Returns true if the detected VCS is enabled in Liquid Prompt and the current directory is a valid repository of that type. This check should be done before running any other _lp_vcs_* data functions, but can be omitted for speed reasons if the checks done by _lp_find_vcs() are good enough.

    New in version 2.0.

    NOTE: Unless otherwise documented, the following functions return 0 for good data, 1 for no data, and 2 for unsupported function.

_lp_vcs_bookmark() -> var:lp_vcs_bookmark
    Returns true if a bookmark is active in the repository. Returns the bookmark name.

    Most VCS providers do not support bookmarks.

    New in version 2.0.

_lp_vcs_branch() -> var:lp_vcs_branch
    Returns true if a branch is active in the repository. Returns the branch name.

    For some VCS providers, a branch is always active.

    New in version 2.0.

_lp_vcs_commit_id() -> var:lp_vcs_commit_id
    Returns the full commit ID of the current commit. The return code is not defined.

    Some VCS providers use hashes, while others use incrementing revision numbers. All VCS providers support some form of ID. The returned string should be unique enough that a user can identify the commit.

    New in version 2.0.

_lp_vcs_commits_off_remote() -> var:lp_vcs_commit_ahead, var:lp_vcs_commit_behind
    Returns true if there are commits on the current branch that are not on the remote tracking branch, or commits on the remote tracking branch that are not on this branch. Returns 1 if there are no differing commits. Returns 2 if there is no matching remote tracking branch. Returns 3 or higher if the VCS provider does not support remote tracking branches.

    Returns the number of commits behind and ahead.

    Most VCS providers do not support remote tracking branches.

    New in version 2.0.

_lp_vcs_head_status() -> var:lp_vcs_head_status, var:lp_vcs_head_details
    Return true if the repository is in a special or unusual state. Return the special status, and any extra details (like progress in a rebase) if applicable.

    Many VCS providers do not have such information. This info is unlikely to be similar across VCSs, and should probably be displayed to a user without manipulation.

    NOTE: The details are optional, and might not be set. Protect it with "${lp_vcs_head_details-}".

    New in version 2.0.

_lp_vcs_remote() -> var:lp_vcs_remote
    Return true if the current branch is a remote tracking branch. The remote name is returned in lp_vcs_remote.

    Many VCS providers do not have such information. Currently this is only implemented for Git.

    Can be enabled by LP_ENABLE_VCS_REMOTE.

    New in version 2.2.

_lp_vcs_staged_files() -> var:lp_vcs_staged_files
    Returns true if any staged files exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged files.

    Many VCS providers do not support staging.

    New in version 2.0.

_lp_vcs_staged_lines() -> var:lp_vcs_staged_i_lines, var:lp_vcs_staged_d_lines
    Returns true if any staged lines exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged lines.

    Many VCS providers do not support staging.

    New in version 2.0.

_lp_vcs_stash_count() -> var:lp_vcs_stash_count
    Returns true if there are stashes the repository. Returns the number of stashes.

    Some VCS providers refer to stashes as "shelves".

    Some VCS providers do not support stashes.

    New in version 2.0.

_lp_vcs_tag() -> var:lp_vcs_tag
    Returns true if a tag is active in the repository. Returns the tag name.

    A tag will only be returned if it is a unique ID that points only to the current commit.

    If multiple tags match, only one is returned. Which tag is selected is not defined.

    Some VCS providers do not support unique tags.

    New in version 2.0.

_lp_vcs_uncommitted_files() -> var:lp_vcs_uncommitted_files
    Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

    Some VCS providers refer to uncommitted files as "modified" files.

    New in version 2.0.

_lp_vcs_uncommitted_lines() -> var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines
    Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

    Some VCS providers refer to uncommitted lines as "modified" or "changed" lines.

    New in version 2.0.

_lp_vcs_unstaged_files() -> var:lp_vcs_unstaged_files
    Returns true if any unstaged files exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged files.

    Many VCS providers do not support staging.

    New in version 2.0.

_lp_vcs_unstaged_lines() -> var:lp_vcs_unstaged_i_lines, var:lp_vcs_unstaged_d_lines
    Returns true if any unstaged lines exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged lines.

    Many VCS providers do not support staging.

    New in version 2.0.

_lp_vcs_untracked_files() -> var:lp_vcs_untracked_files
    Returns true if any untracked files exist in the repository. Returns the number of untracked files.

    Some VCS providers refer to untracked files as "extra" files.

    New in version 2.0.

  Bazaar

WARNING: Bazaar is no longer being actively developed, and depends on Python 2, which is no longer supported. Breezy is a fork that can work with Bazaar repositories. To use Breezy in place of Bazaar, set a wrapper function:

bzr() { brz "$@"; }

NOTE: Bazaar does not support bookmarks. A nick is somewhat like a bookmark, but there is no command to view a naked branch name, so the nick command is used for branches.

NOTE: Bazaar does not support a staging area.

NOTE: Bazaar does not support getting details of remote tracking branches. Bazaar does not keep a local copy of the remote state, so checking this would be impossible anyway.

NOTE: Bazaar does not have extra head statuses. A Bazaar merge can be partially complete, but there is no command to test for it.

_lp_bzr_active()
    Returns true if Bazaar is enabled in Liquid Prompt and the current directory is a valid Bazaar repository. This check should be done before running any other _lp_bzr_* data functions if accessing the Bazaar data functions directly instead of through the generic interface.

    Can be disabled by LP_ENABLE_BZR.

    New in version 2.0.

_lp_bzr_branch() -> var:lp_vcs_branch
    Returns true if a branch is active in the repository. Returns the branch name.

    Changed in version 2.0: Return method changed from stdout. No branch now returns false.

_lp_bzr_commit_id() -> var:lp_vcs_commit_id
    Returns the revision number of the current commit. The return code is not defined.

    New in version 2.0.

_lp_bzr_stash_count() -> var:lp_vcs_stash_count
    Returns true if there are shelves the repository. Returns the number of shelves.

    New in version 2.0.

_lp_bzr_tag() -> var:lp_vcs_tag
    Returns true if a tag is active in the repository. Returns the tag name.

    If multiple tags match, only one is returned. Which tag is selected is not defined.

    New in version 2.0.

_lp_bzr_uncommitted_files() -> var:lp_vcs_uncommitted_files
    Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

    New in version 2.0.

_lp_bzr_uncommitted_lines() -> var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines
    Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

    New in version 2.0.

_lp_bzr_untracked_files() -> var:lp_vcs_untracked_files
    Returns true if any untracked files exist in the repository. Returns the number of untracked files.

    New in version 2.0.

  Fossil

NOTE: Fossil does not support bookmarks.

NOTE: Fossil does not support a staging area.

NOTE: Fossil does not support unique tags. Fossil tags can refer to multiple check-in IDs, so a matching tag is not a useful unique ID.

NOTE: Fossil does not support remote tracking branches. Fossil by default keeps the local repository in sync with the remote. Even if a user disables that, it is not possible to have a local and remote branch named the same not in sync.

_lp_fossil_active()
    Returns true if Fossil is enabled in Liquid Prompt and the current directory is a valid Fossil repository. This check should be done before running any other _lp_fossil_* data functions if accessing the Fossil data functions directly instead of through the generic interface.

    Can be disabled by LP_ENABLE_FOSSIL.

    New in version 2.0.

_lp_fossil_branch() -> var:lp_vcs_branch
    Returns true if a branch is active in the repository. Returns the branch name.

    Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of "no-branch".

_lp_fossil_commit_id() -> var:lp_vcs_commit_id
    Returns the full commit hash of the current commit. The return code is not defined.

    New in version 2.0.

_lp_fossil_head_status() -> var:lp_vcs_head_status
    Return true if the repository is in a special or unusual state. Return the special status.

    Does not return any extra details.

    New in version 2.0.

_lp_fossil_stash_count() -> var:lp_vcs_stash_count
    Returns true if there are stashes the repository. Returns the number of stashes.

    New in version 2.0.

_lp_fossil_uncommitted_files() -> var:lp_vcs_uncommitted_files
    Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

    New in version 2.0.

_lp_fossil_uncommitted_lines() -> var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines
    Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

    New in version 2.0.

_lp_fossil_untracked_files() -> var:lp_vcs_untracked_files
    Returns true if any untracked files exist in the repository. Returns the number of untracked files.

    New in version 2.0.

  Git

NOTE: Git does not support bookmarks.

_lp_git_active()
    Returns true if Git is enabled in Liquid Prompt and the current directory is a valid Git repository. This check should be done before running any other _lp_git_* data functions if accessing the Git data functions directly instead of through the generic interface.

    Can be disabled by LP_ENABLE_GIT.

    New in version 2.0.

_lp_git_branch() -> var:lp_vcs_branch
    Returns true if a branch is active in the repository. Returns the branch name.

    Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of commit ID.

_lp_git_commit_id() -> var:lp_vcs_commit_id
    Returns the full commit hash of the current commit. The return code is not defined.

    New in version 2.0.

_lp_git_commits_off_remote() -> var:lp_vcs_commit_ahead, var:lp_vcs_commit_behind
    Returns true if there are commits on the current branch that are not on the remote tracking branch, or commits on the remote tracking branch that are not on this branch. Returns 1 if there are no differing commits. Returns 2 if there is no matching remote tracking branch.

    Returns the number of commits behind and ahead.

    New in version 2.0.

_lp_git_head_status() -> var:lp_vcs_head_status, var:lp_vcs_head_details
    Return true if the repository is in a special or unusual state. Return the special status, and any extra details (like progress in a rebase) if applicable.

    New in version 2.0.

_lp_git_staged_files() -> var:lp_vcs_staged_files
    Returns true if any staged files exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged files.

    New in version 2.0.

_lp_git_staged_lines() -> var:lp_vcs_staged_i_lines, var:lp_vcs_staged_d_lines
    Returns true if any staged lines exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged lines.

    New in version 2.0.

_lp_git_stash_count() -> var:lp_vcs_stash_count
    Returns true if there are stashes the repository. Returns the number of stashes.

    New in version 2.0.

_lp_git_tag() -> var:lp_vcs_tag
    Returns true if a tag is active in the repository. Returns the tag name.

    If multiple tags match, only one is returned. Which tag is selected is not defined.

    New in version 2.0.

_lp_git_uncommitted_files() -> var:lp_vcs_uncommitted_files
    Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

    New in version 2.0.

_lp_git_uncommitted_lines() -> var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines
    Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

    New in version 2.0.

_lp_git_unstaged_files() -> var:lp_vcs_unstaged_files
    Returns true if any unstaged files exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged files.

    New in version 2.0.

_lp_git_unstaged_lines() -> var:lp_vcs_unstaged_i_lines, var:lp_vcs_unstaged_d_lines
    Returns true if any unstaged lines exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged lines.

    New in version 2.0.

_lp_git_untracked_files() -> var:lp_vcs_untracked_files
    Returns true if any untracked files exist in the repository. Returns the number of untracked files.

    New in version 2.0.

  Mercurial

NOTE: Mercurial does not support a staging area.

NOTE: Mercurial remote tracking branches are disabled (see _lp_hg_commits_off_remote()).

_lp_hg_active()
    Returns true if Mercurial is enabled in Liquid Prompt and the current directory is a valid Mercurial repository. This check should be done before running any other _lp_hg_* data functions if accessing the Mercurial data functions directly instead of through the generic interface.

    Can be disabled by LP_ENABLE_HG.

    New in version 2.0.

_lp_hg_bookmark() -> var:lp_vcs_bookmark
    Returns true if a bookmark is active in the repository. Returns the bookmark name.

    Mercurial bookmarks work more like Git branches.

    New in version 2.0.

_lp_hg_branch() -> var:lp_vcs_branch
    Returns true if a branch is active in the repository. Returns the branch name.

    All Mercurial commits have a branch, so this function should always return true. A closer analog to Git branches are Mercurial bookmarks (see _lp_hg_bookmark()).

    Changed in version 2.0: Return method changed from stdout. No branch now returns false.

_lp_hg_commit_id() -> var:lp_vcs_commit_id
    Returns the full global revision ID of the current commit. The return code is not defined.

    New in version 2.0.

_lp_hg_commits_off_remote()
    Returns 2 (disabled).

    Mercurial does not keep a local copy of the remote state, so checking this will require a connection to the remote server. This means it is often prohibitively time expensive, and therefore should not be used in a prompt. See issue #217.

    New in version 2.0.

_lp_hg_head_status() -> var:lp_vcs_head_status
    Return true if the repository is in a special or unusual state. Return the special status.

    Does not return any extra details.

    This function depends on _lp_find_vcs() being run first to set lp_vcs_root.

    New in version 2.0.

_lp_hg_stash_count() -> var:lp_vcs_stash_count
    Returns true if there are shelves the repository. Returns the number of shelves.

    New in version 2.0.

_lp_hg_tag() -> var:lp_vcs_tag
    Returns true if a tag is active in the repository. Returns the tag name.

    If multiple tags match, only one is returned. Which tag is selected is not defined.

    New in version 2.0.

_lp_hg_uncommitted_files() -> var:lp_vcs_uncommitted_files
    Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

    New in version 2.0.

_lp_hg_uncommitted_lines() -> var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines
    Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

    New in version 2.0.

_lp_hg_untracked_files() -> var:lp_vcs_untracked_files
    Returns true if any untracked files exist in the repository. Returns the number of untracked files.

    New in version 2.0.

  Subversion

NOTE: Subversion does not support bookmarks.

NOTE: Subversion does not support a staging area.

NOTE: Subversion does not support stashes.

NOTE: Subversion does not have extra head statuses. A Subversion merge is no different than a manual file change, so the repository has no extra state to track.

NOTE: Subversion does not support remote tracking branches (as it is not a distributed version control system).

NOTE: Subversion does not support tags. What are generally agreed upon as being tags are internally branches. These are returned by _lp_svn_branch().

_lp_svn_active()
    Returns true if Subversion is enabled in Liquid Prompt and the current directory is a valid Subversion repository. This check should be done before running any other _lp_svn_* data functions if accessing the Subversion data functions directly instead of through the generic interface.

    Can be disabled by LP_ENABLE_SVN.

    New in version 2.0.

_lp_svn_branch() -> var:lp_vcs_branch
    Returns true if a branch is active in the repository. Returns the branch name.

    Subversion "tags" are really branches under a "tag" directory. Tags are returned as their directory name, prefixed with "tag/".

    Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of the current directory.

_lp_svn_commit_id() -> var:lp_vcs_commit_id
    Returns the revision number of the current commit. The return code is not defined.

    New in version 2.0.

_lp_svn_uncommitted_files() -> var:lp_vcs_uncommitted_files
    Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

    New in version 2.0.

_lp_svn_uncommitted_lines() -> var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines
    Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

    New in version 2.0.

_lp_svn_untracked_files() -> var:lp_vcs_untracked_files
    Returns true if any untracked files exist in the repository. Returns the number of untracked files.

    New in version 2.0.

    These functions are designed to be used by themes.

    All data functions will return true (meaning return code 0) when they are both enabled and have data. They will return false (meaning return code 1) when they do not have data. Most will return 2 when they are disabled, either through the config or because the tool they depend on is not installed. Such disable config options will be documented. Exceptions to this rule are explicitly documented.

    When a function returns false, any return variables are not guaranteed to be set. If running with set -u (or when building a theme to be distributed), guard any return variable accesses with a check of the return code, or use ${var-} syntax.

  Battery

_lp_battery() -> var:lp_battery
    Returns a return code depending on the status of the battery:

•   5 if the battery feature is disabled or not available

•   4 if no battery level is found

•   3 if charging and the level is above the threshold

•   2 if charging and the level is under the threshold

•   1 if discharging and the level is above the threshold

•   0 if discharging and the level is under the threshold

    Returns an integer percentage of the current battery level.

    If the threshold is not surpassed, the battery level is still returned.

    The threshold is configured with LP_BATTERY_THRESHOLD.

    Can be disabled by LP_ENABLE_BATT.

    Changed in version 2.1: Implemented sysfs method as the default way of getting battery status.

  Development Environment

_lp_cmake() -> var:lp_cmake_compiler, var:lp_cmake_generator, var:lp_cmake_buildtype
    Returns true if a CMake context is found. Parse the data in CMakeCache.txt and returns the basename of the configured compiler, generator (e.g. "Unix Makefiles"), and build type ("Debug", "Release", etc.). Some generator names are shorten: "Makefiles" becomes "Make" and "Visual Studio" becomes "VS".

    Can be disabled by LP_ENABLE_CMAKE.

    New in version 2.2.

_lp_kubernetes_context() -> var:lp_kubernetes_context, var:lp_kubernetes_namespace
    Returns true if a Kubernetes context is found. Returns the Kubernetes context name or the first name component.

    Splitting long context names into components is defined by LP_DELIMITER_KUBECONTEXT_SUFFIX and LP_DELIMITER_KUBECONTEXT_PREFIX. Both use greedy matches - see Config Options for examples.

    If enabled by LP_ENABLE_KUBE_NAMESPACE, will also return the default namespace for the current context, if one is set.

    Can be disabled by LP_ENABLE_KUBECONTEXT.

    New in version 2.1.

_lp_node_env() -> var:lp_node_env
    Returns true if a Node.js environment is detected. Returns the virtual environment name.

    Can be enabled by LP_ENABLE_NODE_VENV.

    New in version 2.1.

_lp_perl_env() -> var:lp_perl_env
    Returns true if a Perlbrew or PLENV Perl environment is detected. Returns the virtual environment name.

    Can be disabled by LP_ENABLE_PERL_VENV.

    New in version 2.2.

_lp_python_env() -> var:lp_python_env
    Returns true if a Python or Conda environment is detected. Returns the virtual environment name.

    If the environment name contains a forward slash (/), only the substring after the last forward slash is returned.

    Can be disabled by LP_ENABLE_VIRTUALENV.

    New in version 2.0.

    Changed in version 2.1: Displays the "prompt string" first (the --prompt argument when setting up the virtualenv).

_lp_ruby_env() -> var:lp_ruby_env
    Returns true if a RVM or RBENV ruby environment is detected. Returns the virtual environment name.

    In the case of a RVM environment, the label displayed can be customized with the LP_RUBY_RVM_PROMPT_OPTIONS.

    Can be disabled by LP_ENABLE_RUBY_VENV.

    New in version 2.1.

_lp_software_collections() -> var:lp_software_collections
    Returns true if a Red Hat Software Collection is enabled. Returns the software collection name.

    If the software collection name has trailing whitespace, it is removed.

    Can be disabled by LP_ENABLE_SCLS.

    New in version 2.0.

_lp_terraform_env() -> var:lp_terraform_env
    Returns true if a Terraform workspace is detected. Returns the workspace name.

    Can be enabled by LP_ENABLE_TERRAFORM.

    New in version 2.1.

  Disks and Memory

_lp_disk -> var:lp_disk, var:lp_disk_human, var:lp_disk_perc
    Gather information about the current state of the hard drive hosting the current directory:

•   available space in kibi-bytes (lp_disk, that is, 1024 bytes),

•   available space in human-readable form, using binary unit prefixes (lp_disk_human, see also __lp_bytes_to_human()).

•   available space as a percentage of total (lp_disk_perc).

    Returns true if the used space is below at least one of the user-defined thresholds:

•   LP_DISK_THRESHOLD

•   LP_DISK_THRESHOLD_PERC

    Can be disabled by LP_ENABLE_DISK.

    New in version 2.2.

_lp_ram -> var:lp_ram, var:lp_ram_human, var:lp_ram_perc
    Gather information about the current state of the RAM:

•   available space in kibi-bytes (lp_ram, that is, 1024 bytes),

•   available space in human-readable form, using binary unit prefixes (lp_ram_human, see also __lp_bytes_to_human()).

•   available space as a percentage of total (lp_ram_perc).

    Returns true if the used space is below at least one of the user-defined thresholds:

•   LP_RAM_THRESHOLD

•   LP_RAM_THRESHOLD_PERC

    Can be disabled by LP_ENABLE_RAM.

    New in version 2.2.

  Environment

_lp_aws_profile() -> var:lp_aws_profile
    Returns true if the AWS_PROFILE, AWS_DEFAULT_PROFILE, or AWS_VAULT variables are found in the environment (in that order of preference). Returns the contents of the variable.

    Can be disabled by LP_ENABLE_AWS_PROFILE.

    New in version 2.1.

_lp_connected_display()
    Returns true if there is a connected X11 display.

    New in version 2.0.

    Changed in version 2.2: Can be disabled by LP_ENABLE_DISPLAY.

_lp_connection() -> var:lp_connection
    Returns a string matching the connection context of the shell. Valid values:

•   ssh - connected over OpenSSH

•   tel - connected over Telnet

•   su - running in a su or sudo shell

•   lcl - running in a local terminal

    It is not possible for more than one context to be returned. The contexts are checked in the order listed above, and the first one found will be returned.

    It is not possible for no context to be returned.

    Changed in version 2.0: Return method changed from stdout.

_lp_container() -> var:lp_container
    Returns true if the shell is running in a container. In that case, the return variable is set to a string matching the container type. Possible values include (but are not limited to):

•   Singlrty - running in a Singularity container

•   Toolbox - running in a Toolbox container

•   Podman - running in a Podman container

•   Docker - running in a Docker container

•   LXC - running in an LXC container

•   nspawn - running in a systemd-nspawn container

    It is not possible to detect more than one containerization type to be returned. The containers are checked in the order listed above, and the first one found will be returned. Can be enabled by LP_ENABLE_CONTAINER.

    New in version 2.1.

_lp_dirstack() -> var:lp_dirstack
    Returns true if directory stack support is enabled and the directory stack contains more than one directory. In that case, the return variable is set to the number of directories on the stack.

    Can be enabled by LP_ENABLE_DIRSTACK.

    New in version 2.0.

_lp_env_vars([color_if_set[, color_if_unset[, end_color]]]) -> var:lp_env_vars
    Gather the states of the environment variables indicated in the LP_ENV_VARS array, and put them in the lp_env_vars array.

    LP_ENV_VARS should be a list of environment variable names to look for, along with the string to be displayed if the variable is set, and an optional string to be displayed if the variable is not set. The string to be displayed may contain a %s marker, which will be replaced by the variable's content.

    If color_if_set is passed, it will be used to color the set variables string. If color_if_unset is passed, it will be used to color the unset variables string.

    end_color is added at the end of each variable string. It defaults to "$NO_COL" (color reset).

    Returns true if at least one variable representation is added to the result array. Returns 1 if the no variable representation is set. Returns 2 if the user disabled the feature with LP_ENABLE_ENV_VARS.

    New in version 2.2.

_lp_error() -> var:lp_error
    Returns true if the last user shell command returned a non-zero exit code. Returns (in the return variable) the exit code of that command.

    Can be disabled by LP_ENABLE_ERROR.

    NOTE: The return variable lp_error will always be set with the last command return code, as it must be the first thing done by the prompt. This function should still be used, as it checks for the feature being disabled by the user.

    New in version 2.0.

_lp_error_meaning() -> var:lp_error_meaning
    Returns true if the last user shell command returned a non-zero exit code. Returns (in the return variable) a guess of the meaning of that error.

    Can be disabled by LP_ENABLE_ERROR_MEANING.

    New in version 2.2.

_lp_http_proxy() -> var:lp_http_proxy
    Returns true if an HTTP or HTTPS proxy is enabled through environment variables in the shell. Returns the first found proxy string.

    Can be disabled by LP_ENABLE_PROXY.

    New in version 2.0.

_lp_multiplexer() -> var:lp_multiplexer
    Returns true if the current shell context is inside a terminal multiplexer. Returns a string matching the multiplexer:

•   tmux

•   screen

    New in version 2.0.

    Changed in version 2.2: Can be disabled by LP_ENABLE_MULTIPLEXER, except if --internal is passed (i.e. for internal use only). Return variable renamed from lp_mulitplexer to lp_multiplexer.

_lp_shell_level() -> var:lp_shell_level
    Returns true if the shell is a nested shell inside another shell.

    Can be disabled by LP_ENABLE_SHLVL.

    New in version 2.1.

_lp_terminal_device() -> var:lp_terminal_device
    Returns the basename of the terminal device connected to the shell's standard input.

    NOTE: This value should never change during the life of the shell.

    NOTE: This data source is unlikely to be wanted by the user, and should not be included in themes by default.

    New in version 2.0.

  Jobs

_lp_detached_sessions() -> var:lp_detached_sessions
    Returns true if any detached multiplexer sessions are found. Returns an integer count of how many sessions were found.

    Can be disabled by LP_ENABLE_DETACHED_SESSIONS.

    New in version 2.0.

_lp_jobcount() -> var:lp_running_jobs, var:lp_stopped_jobs
    Returns true if any shell background jobs are found. Returns an integer count of how many jobs are running and how many are stopped.

    Stopped jobs are jobs suspended with Ctrl-Z.

    Running jobs are jobs started with the command & syntax, or stopped jobs started again with the bg command.

    Can be disabled by LP_ENABLE_JOBS.

    New in version 2.0.

  Load

_lp_cpu_load() -> var:lp_cpu_load
    Returns a string of the system load average smallest increment, usually 1 minute. The return code is not defined.

_lp_load() -> var:lp_load, var:lp_load_adjusted
    Returns true if the system load average scaled by CPU count is greater than the threshold. Returns the system load average in lp_load, and the average scaled by CPU count, multiplied by 100 in lp_load_adjusted. In other words, the load average is multiplied by 100, then divided by the number of CPU cores.

    lp_load should be displayed to the user, while lp_load_adjusted should be used to compare values between machines using LP_LOAD_CAP. The default theme uses this to generate a color scale.

    NOTE: LP_LOAD_CAP is a raw floating point configuration value that is difficult to do math on. _LP_LOAD_CAP contains the same value, but multiplied by 100 to make comparisons to lp_load_adjusted simple. Use it along with lp_load_adjusted as arguments to _lp_color_map().

    If the threshold is not surpassed, the load average is still returned.

    The threshold is configured with LP_LOAD_THRESHOLD.

    Can be disabled by LP_ENABLE_LOAD.

    New in version 2.0.

  OS

_lp_chroot() -> var:lp_chroot
    Returns true if a chroot environment is detected. Returns a string matching the chroot string if one is found.

    New in version 2.0.

    Changed in version 2.2: Can be disabled by LP_ENABLE_CHROOT.

_lp_hostname() -> var:lp_hostname
    Returns true if a hostname should be displayed. Returns 1 if the connection type is local and LP_HOSTNAME_ALWAYS is not 1.

    Returns the hostname string in lp_hostname.

    Can be disabled by LP_HOSTNAME_ALWAYS set to -1.

    New in version 2.0.

    Changed in version 2.1: Returns the actual hostname instead of a shell prompt escape code. No longer sets LP_HOST_SYMBOL to the same return string. Added LP_HOSTNAME_METHOD to configure display method.

_lp_os() -> var:lp_os_arch, var:lp_os_family, var:lp_os_kernel, var:lp_os_distrib, var:lp_os_version
    Gather data about the current Operating System.

    Returns true if it was able to gather all possible data. Returns 1 if some expected information was missing. Returns 2 if the user disabled the feature with LP_ENABLE_OS.

    Returns data in lp_os_* variables:

•   processor architecture (e.g. x86_64, i686, etc.),

•   OS family (BSD, UNIX, GNU or Windows),

•   OS kernel (Linux, Darwin, Cygwin, etc.),

•   Linux distribution (e.g. ubuntu, arch, mandrake, etc.),

•   Linux distribution version codename (e.g. focal, ada, buzz, etc.)

    Each data source can be disabled via its corresponding configuration variable:

•   LP_ENABLE_OS_ARCH

•   LP_ENABLE_OS_FAMILY

•   LP_ENABLE_OS_KERNEL

•   LP_ENABLE_OS_DISTRIB

•   LP_ENABLE_OS_VERSION

    New in version 2.2.

_lp_sudo_active()
    Returns true if sudo is currently activated with valid credentials. If sudo is configured to always allow a user to run commands with no password, this will always return true.

    Can be disabled by LP_ENABLE_SUDO.

    New in version 2.0.

    Changed in version 2.1: If the user has NOPASSWD powers, that is cached on startup to prevent multiple sudo calls.

_lp_user()
    Returns a return code depending on the logged in user:

•   2 - the user is root

•   1 - the user is a user other than the original login user

•   0 - the user is the login user

    New in version 2.0.

_lp_username() -> var:lp_username
    Returns true if a username should be displayed. Returns 1 if the user is the login user and LP_USER_ALWAYS is not 1.

    Returns the current user ID in lp_username.

    Can be disabled by LP_USER_ALWAYS set to -1.

    New in version 2.0.

    Changed in version 2.1: Returns the actual username instead of a shell prompt escape code.

  Path

_lp_path_format(path_format=$LP_COLOR_PATH, last_directory_format=$path_format, vcs_root_format=$last_directory_format, shortened_directory_format=$path_format, separator="/"[, separator_format]) -> var:lp_path, var:lp_path_format
    Returns a shortened and formatted string indicating the current working directory path. lp_path contains the path without any formatting, custom separators, or shell escapes, intended for use in the terminal title. lp_path_format contains the complete formatted path, to be inserted into the prompt.

    The behavior of the shortening is controlled by LP_ENABLE_SHORTEN_PATH, LP_PATH_METHOD, LP_PATH_LENGTH, LP_PATH_KEEP, LP_PATH_CHARACTER_KEEP, and LP_PATH_VCS_ROOT. See their descriptions for details on how they change the output of this function.

    The last directory in the displayed path will be shown with the last_directory_format.

    If a VCS repository is detected with _lp_find_vcs(), the root of the VCS repository is formatted with vcs_root_format. The detection method is the same as for all other VCS display, so if a VCS type or directory is disabled, it will not be detected.

    If the path shortening shortens a directory (or multiple consecutive directories), they will be formatted with shortened_directory_format.

    A custom separator will only be substituted in the lp_path_format output. Note that this will cut into maximum path length if the separator is longer than one character.

    With no specified separator_format, each separator will take the format of the directory section preceding it. Otherwise every separator will be formatted with separator_format. Note that the root directory is treated as a directory, and is formatted as such.

    New in version 2.0.

    Changed in version 2.1: Changed lp_path to no longer contain shell escapes.

  Runtime

_lp_runtime_format() -> var:lp_runtime_format
    Returns true if the last command runtime was greater than the threshold. Returns a formatted string of the total runtime, split into days, hours, minutes, and seconds. Ex: 3h27m6s.

    The threshold is configured with LP_RUNTIME_THRESHOLD.

    Can be disabled by LP_ENABLE_RUNTIME.

    New in version 2.0.

  Temperature

_lp_temperature() -> var:lp_temperature
    Returns true if the highest system temperature is greater than the threshold. Returns the highest temperature integer.

    If the threshold is not surpassed, the highest temperature is still returned.

    If no temperature data is found, returns false and lp_temperature will not be set.

    The threshold is configured with LP_TEMP_THRESHOLD.

    Can be disabled by LP_ENABLE_TEMP.

    New in version 2.0: Note that a function by this name was renamed to _lp_temperature_color.

  Time

_lp_time() -> var:lp_time
    Returns true if digital time is enabled. Returns the current digital time string, formatting set by LP_TIME_FORMAT.

    Can be disabled by LP_ENABLE_TIME, or LP_TIME_ANALOG set to 1.

    New in version 2.0.

    Changed in version 2.1: Returns the actual time instead of a shell prompt escape code.

_lp_analog_time() -> var:lp_analog_time
    Returns true if analog time is enabled. Returns the current analog time as a single Unicode character, accurate to the closest 30 minutes.

    Can be disabled by LP_ENABLE_TIME, or LP_TIME_ANALOG set to 0.

    New in version 2.0.

  Wireless

_lp_wifi_signal_strength() -> var:lp_wifi_signal_strength
    Returns true if the lowest wireless signal strength is lower than the threshold. Returns the lowest strength percentage.

    If the threshold is not surpassed, the lowest signal strength is still returned.

    If no wireless signal data is found, returns false and lp_wifi_signal_strength will not be set.

    The threshold is configured with LP_WIFI_STRENGTH_THRESHOLD.

    Can be disabled by LP_ENABLE_WIFI_STRENGTH.

    New in version 2.1.

DEFAULT THEME FUNCTIONS

•   Theme Functions

•   Theme Data Functions

    These functions are designed to be used by the default theme, but are documented here so that other themes can use these functions to reduce duplication if sections from the default theme are wanted.

  Theme Functions

_lp_default_theme_activate()
    Setup the defaults and static pieces of the default theme.

    Uses colors:

•   LP_COLOR_IN_MULTIPLEXER

•   LP_COLOR_MARK

•   LP_COLOR_MARK_ROOT

•   LP_COLOR_PATH_ROOT

•   LP_COLOR_USER_ALT

•   LP_COLOR_USER_LOGGED

•   LP_COLOR_USER_ROOT

    And marks:

•   LP_MARK_BRACKET_OPEN

•   LP_MARK_BRACKET_CLOSE

•   LP_MARK_DEFAULT

    New in version 2.0.

_lp_default_theme_directory()
    Setup the colors for the directory when the current working directory changes.

    Uses colors:

•   LP_COLOR_NOWRITE

•   LP_COLOR_PATH

•   LP_COLOR_WRITE

    And mark LP_MARK_PERM.

    New in version 2.0.

_lp_default_theme_prompt()
    Runs _lp_default_theme_prompt_data() then _lp_default_theme_prompt_template().

    New in version 2.0.

_lp_default_theme_prompt_data()
    Runs all of the below theme data functions, and writes values to the Default Theme variables. Can be used to generate all the default theme sections, then modify them before running a user template.

    New in version 2.0.

_lp_default_theme_prompt_template()
    If LP_PS1_FILE is set, sources it.

    Then, if LP_PS1 is set, uses it as PS1. Otherwise, uses the default theme layout to construct PS1. Can be used to set different template sections than the default theme, but still use the same template engine.

    New in version 2.0.

  Theme Data Functions

These functions wrap Data Functions with color and/or other formatting. Their return codes are the same as the data functions they wrap unless otherwise documented.

The interface of the functions will not change between minor versions, but the specific text and formatting may change.

_lp_analog_time_color() -> var:lp_analog_time_color
    Returns _lp_analog_time() with color from LP_COLOR_TIME.

    New in version 2.0.

_lp_aws_profile_color() -> var:lp_aws_profile_color
    Returns _lp_aws_profile() with color from LP_COLOR_AWS_PROFILE.

    New in version 2.1.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_battery_color() -> var:lp_battery_color
    Returns data from _lp_battery(), colored with:

•   LP_COLOR_CHARGING_ABOVE

•   LP_COLOR_CHARGING_UNDER

•   LP_COLOR_DISCHARGING_ABOVE

•   LP_COLOR_DISCHARGING_UNDER

•   LP_COLORMAP

    And using marks:

•   LP_MARK_ADAPTER

•   LP_MARK_BATTERY

    Adds battery value if LP_PERCENTS_ALWAYS is 1.

    Changed in version 2.0: Return code matches data function. Return method changed from stdout.

_lp_cmake_color() -> var:lp_cmake_color
    Returns data from _lp_cmake(). lp_cmake_compiler and lp_cmake_generator are colored according to their hash (see _lp_hash_color()). lp_cmake_buildtype has as configurable color, depending on its value:

•   Debug, colored with LP_COLOR_CMAKE_DEBUG (magenta, by default),

•   RelWithDebInfo, colored with LP_COLOR_CMAKE_RWDI (blue, by default),

•   Release, colored with LP_COLOR_CMAKE_RELEASE (cyan, by default),

•   any other value would be colored according to its hash.

    New in version 2.2.

_lp_container_color() -> var:_lp_container_color
    Returns _lp_container(), surrounded by « and » colored with LP_COLOR_CONTAINER if the value is true. Returns no data if the value is false.

    New in version 2.1.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_dev_env_color() -> var:lp_dev_env_color
    Assemble data related to development environment and returns a single string. The returned string starts with LP_MARK_DEV_OPEN and ends with LP_MARK_DEV_CLOSE, with each section separated by LP_MARK_DEV_MID.

    Data are collected from:

•   LP_SCLS

•   LP_AWS_PROFILE

•   LP_CONTAINER

•   LP_VENV

•   LP_NODE_VENV

•   LP_PERL_VENV

•   LP_RUBY_VENV

•   LP_TFSPACE

•   LP_KUBECONTEXT

•   LP_CMAKE

    New in version 2.2.

_lp_dirstack_color() -> var:lp_dirstack_color
    Returns _lp_dirstack(), prefixed with LP_MARK_DIRSTACK, all colored with LP_COLOR_DIRSTACK.

    New in version 2.0.

_lp_disk_color() -> var:lp_disk_color
    Returns information about available space of the hard drive hosting the current directory.

    If LP_ALWAYS_DISPLAY_VALUES is false, displays a colored mark (using LP_MARK_DISK), if the available disk space goes below LP_DISK_THRESHOLD or LP_DISK_THRESHOLD_PERC. If it is true, displays the corresponding value, either as a percentage (if LP_DISPLAY_VALUES_AS_PERCENTS is true) or as a human-readable quantity (if LP_DISPLAY_VALUES_AS_PERCENTS is false).

    The mark and the value itself are colored with LP_COLOR_DISK, while the unit is colored with LP_COLOR_DISK_UNITS.

    New in version 2.2.

_lp_env_vars_color() -> var:lp_env_vars_color
    Returns the elements of the array set by _lp_env_vars(), joined with the LP_MARK_ENV_VARS_SEP marker, and surrounded by LP_MARK_ENV_VARS_OPEN and LP_MARK_ENV_VARS_CLOSE.

    If a matching environment variable is set, it is colored with LP_COLOR_ENV_VARS_SET, if it is unset, it is colored with LP_COLOR_ENV_VARS_UNSET.

    See also LP_ENV_VARS.

    New in version 2.2.

_lp_error_color() -> var:lp_error_color
    Returns _lp_error() with color from LP_COLOR_ERR.

    New in version 2.0.

_lp_error_meaning_color() -> var:lp_error_meaning_color
    Returns _lp_error_meaning() with color from LP_COLOR_ERR and surrounded by parentheses.

    New in version 2.2.

_lp_hostname_color() -> var:lp_hostname_color
    Returns _lp_hostname(), with added data from _lp_chroot(). Color from LP_COLOR_HOST, LP_COLOR_SSH, LP_COLOR_HOST_HASH, and LP_COLOR_TELNET, depending on the output of _lp_connection().

    Added color from _lp_connected_display(): either LP_COLOR_X11_ON or LP_COLOR_X11_OFF.

    Return code is _lp_hostname() ORed with _lp_chroot(): both must return no data for _lp_hostname_color() to return no data.

    New in version 2.0.

_lp_http_proxy_color() -> var:lp_http_proxy_color
    Returns _lp_http_proxy() with color from LP_COLOR_PROXY.

    New in version 2.0.

_lp_jobcount_color() -> var:lp_jobcount_color
    Returns _lp_detached_sessions() with color from LP_COLOR_JOB_D and _lp_jobcount() with colors from LP_COLOR_JOB_R and LP_COLOR_JOB_Z.

    Return code is _lp_detached_sessions() ORed with _lp_jobcount(): both must return no data for _lp_jobcount_color() to return no data.

    Changed in version 2.0: Return code matches data function. Return method changed from stdout.

_lp_kubernetes_context_color() -> var:lp_kubernetes_context_color
    Returns data from _lp_kubernetes_context(), colored with LP_COLOR_KUBECONTEXT and using mark LP_MARK_KUBECONTEXT.

    New in version 2.1.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_load_color() -> var:lp_load_color
    Returns _lp_load() with color from LP_COLORMAP and mark from LP_MARK_LOAD.

    Adds load value if LP_PERCENTS_ALWAYS is 1.

    Changed in version 2.0: Return code matches data function. Return method changed from stdout.

_lp_node_env_color() -> var:lp_node_env_color
    Returns _lp_node_env() with color from LP_COLOR_NODE_VENV.

    New in version 2.1.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_os_color() -> var:lp_os_color
    Gather information about the Operating System.

    Any string encountered in the process may be replaced by a user-defined counterpart, using the LP_MARK_OS configuration array.

    If the string was not replaced, it is colored with a random color depending on its hash (see _lp_hash_color()).

    All fields gathered via the _lp_os() function are joined with the LP_MARK_OS_SEP string, in the following order: arch, family, kernel, distribution, codename. The corresponding data are returned as a single string via the lp_os_color variable.

    The function returns 2 if the user disabled the feature with LP_ENABLE_OS, 1 if no field was filled in with data, and true otherwise.

    New in version 2.2.

_lp_python_env_color() -> var:lp_python_env_color
    Returns _lp_python_env() with color from LP_COLOR_VIRTUALENV.

    New in version 2.0.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_ram_color() -> var:lp_ram_color
    Returns information about available RAM.

    If LP_ALWAYS_DISPLAY_VALUES is false, displays a colored mark (using LP_MARK_RAM), if the available ram goes below LP_RAM_THRESHOLD or LP_RAM_THRESHOLD_PERC. If it is true, displays the corresponding value, either as a percentage (if LP_DISPLAY_VALUES_AS_PERCENTS is true) or as a human-readable quantity (if LP_DISPLAY_VALUES_AS_PERCENTS is false).

    The mark and the value itself are colored with LP_COLOR_RAM, while the unit is colored with LP_COLOR_RAM_UNITS.

    New in version 2.2.

_lp_perl_env_color() -> var:lp_perl_env_color
    Returns _lp_perl_env() with color from LP_COLOR_PERL_VENV.

    New in version 2.2.

_lp_ruby_env_color() -> var:lp_ruby_env_color
    Returns _lp_ruby_env() with color from LP_COLOR_RUBY_VENV.

    New in version 2.1.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_runtime_color() -> var:lp_runtime_color
    Returns _lp_runtime_format() with color from LP_COLOR_RUNTIME.

    Changed in version 2.0: Renamed from _lp_runtime. Return code matches data function. Return method changed from stdout.

_lp_shell_level_color() -> var:lp_shell_level_color
    Returns _lp_shell_level(), prefixed with LP_MARK_SHLVL, all colored with LP_COLOR_SHLVL.

    New in version 2.1.

_lp_software_collections_color() -> var:lp_software_collections_color
    Returns _lp_software_collections() with color from LP_COLOR_VIRTUALENV.

    New in version 2.0.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_sudo_active_color() -> var:lp_sudo_active_color
    Returns _lp_sudo_active() with color and marks from LP_COLOR_MARK_SUDO if sudo is active, or LP_COLOR_MARK_NO_SUDO if not.

    Does not return 1 if sudo is not active, as the return string is still needed.

    Changed in version 2.0: Renamed from _lp_sudo_check. Always defined instead of only when LP_ENABLE_SUDO is enabled. Return variable changed from LP_COLOR_MARK.

_lp_temperature_color() -> var:lp_temperature_color
    Returns _lp_temperature() with color from LP_COLORMAP and mark from LP_MARK_TEMP.

    Changed in version 2.0: Renamed from _lp_temperature. Return code matches data function. Return method changed from stdout.

_lp_terraform_env_color() -> var:lp_terraform_env_color
    Returns _lp_terraform_env() with color from LP_COLOR_TERRAFORM.

    New in version 2.1.

    Changed in version 2.2: No longer include squared brackets, superseded by LP_MARK_DEV_OPEN, LP_MARK_DEV_MID and LP_MARK_DEV_CLOSE.

_lp_time_color() -> var:lp_time_color
    Returns _lp_time() with color from LP_COLOR_TIME.

    New in version 2.0.

_lp_vcs_details_color() -> var:lp_vcs_details_color
    Returns data from all generic Version Control Data Functions, colored with:

•   LP_COLOR_CHANGES

•   LP_COLOR_COMMITS

•   LP_COLOR_COMMITS_BEHIND

•   LP_COLOR_DIFF

•   LP_COLOR_UP

    And using marks:

•   LP_MARK_STASH

•   LP_MARK_UNTRACKED

    This function should only be called when in a VCS repository; use _lp_find_vcs() or _lp_vcs_active() before.

    The return code is undefined; a string should always be returned.

    New in version 2.0.

_lp_wifi_signal_strength_color() -> var:lp_wifi_signal_strength_color
    Returns _lp_wifi_signal_strength() with color from LP_COLORMAP and mark from LP_MARK_WIFI.

    New in version 2.1.

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.

    See also LP_ENABLE_HYPERLINKS and _lp_create_link().

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

    See also _lp_version_string().

    WARNING: This only supports the following input values for strings: "alpha", "beta" and "rc".

    New in version 2.2.

_lp_version_string([major[, minor[, patch[, string[, number]]]]]) -> var:lp_version
    Formats the given version number in a version string of the form: "${major}.${minor}.${patch}-${string}.${number}"

    If no version is given, formats the current version number of Liquid Prompt. If a version number is given, major and minor are both mandatory.

    See also _lp_version_greatereq().

    New in version 2.2.

INTERNAL FUNCTIONS

•   Config

•   Formatting

•   Battery

•   Git

•   Load

•   OS

•   Path

•   Prompt

•   Runtime

•   Theme

•   Title

•   Temperature

•   Utility

•   Wireless

    These functions are designed to be used only by Liquid Prompt internals and data functions. These functions should not be used by users or themes, as they are not guaranteed to be stable between versions. There are documented here for information for those developing Liquid Prompt.

  Config

__lp_source_config([--no-config])
    Load the user config and default config values. This function is called by lp_activate().

    Also setup color variables that can be used by the user for their color config. Those variables are local to this function.

    If the --no-config flag is passed, defaults are set, but no config file is sourced.

    Changed in version 2.0: Renamed from _lp_source_config. Added --no-config flag.

  Formatting

__lp_background_color(color) -> var:ab_color
    Returns the terminal escape code to set the background color to the ANSI escape color code integer color. No checking is done for invalid color codes.

    New in version 1.12.

    Changed in version 2.0: Renamed from background_color.

__lp_foreground_color(color) -> var:af_color
    Returns the terminal escape code to set the foreground color to the ANSI escape color code integer color. No checking is done for invalid color codes.

    New in version 1.12.

    Changed in version 2.0: Renamed from foreground_color.

  Battery

__lp_battery_acpi() -> var:lp_battery, var:lp_battery_status
    Returns the status and remaining capacity of the battery, as reported by the acpi tool. This function is available only on Linux, and requires acpi to be installed.

    New in version 2.1.

__lp_battery_sysfs() -> var:lp_battery, var:lp_battery_status
    Returns the status and remaining capacity of the battery, using sysfs. This is the default method. If multiple batteries are present, returns the status of the first battery found. This function is available only on Linux systems.

    New in version 2.1.

  Git

__lp_git_diff_shortstat_files(diff_shortstat) -> var:lp_git_diff_shortstat_files
    Processes the input diff_shortstat as the output of a git diff --shortstat command, returning the number of changed files. This allows for the comparison of any two states, as __lp_git_diff_shortstat_files() does not run any specific git diff command.

    New in version 2.0.

__lp_git_diff_shortstat_lines(diff_shortstat) -> var:lp_git_diff_shortstat_lines
    Processes the input diff_shortstat as the output of a git diff --shortstat command, returning the number of changed lines. This allows for the comparison of any two states, as __lp_git_diff_shortstat_files() does not run any specific git diff command.

    New in version 2.0.

__lp_git_diff_shortstat_staged() -> var:_lp_git_diff_shortstat_staged
    Returns the output of a git diff --shortstat command, comparing the staging area to the HEAD commit.

    The return variable is supposed to be a cache, set as local in __lp_set_prompt(), preventing duplicate calls to git.

    New in version 2.0.

__lp_git_diff_shortstat_uncommitted() -> var:_lp_git_diff_shortstat_uncommitted
    Returns the output of a git diff --shortstat command, comparing the working directory to the HEAD commit.

    The return variable is supposed to be a cache, set as local in __lp_set_prompt(), preventing duplicate calls to git.

    New in version 2.0.

__lp_git_diff_shortstat_unstaged() -> var:_lp_git_diff_shortstat_unstaged
    Returns the output of a git diff --shortstat command, comparing the working directory to the staging area.

    The return variable is supposed to be a cache, set as local in __lp_set_prompt(), preventing duplicate calls to git.

    New in version 2.0.

  Load

__lp_cpu_count() -> var:_lp_CPUNUM
    Returns the number of CPUs on the machine. The implementation depends on the operating system.

    New in version 2.0.

  OS

__lp_hostname_hash() -> var:lp_hostname_hash
    Returns the hash of the hostname as computed by cksum.

    New in version 2.0.

  Path

__lp_end_path_left_shortening()
    Terminate a multi-directory shortening, checking if the shortening actually made a shorter path, and if so, adding the shortened mark. If not, adds the real path to the output. Only used internally by _lp_path_format().

    New in version 2.0.

__lp_get_unique_directory(path) -> var:lp_unique_directory
    Returns the shortest unique directory prefix matching the real directory input. Only used internally by _lp_path_format().

    New in version 2.0.

__lp_pwd_tilde([path]) -> var:lp_pwd_tilde
    Returns path, or PWD if path is not set, with the user's home directory replaced with a tilde ("~").

    Changed in version 2.0: Renamed from _lp_get_home_tilde_collapsed. Return method changed from stdout. Optional parameter path added.

  Prompt

__lp_before_command()
    Used only by Bash to hack the DEBUG trap to run functions before the user command executes.

    Changed in version 2.1: Renamed from the Bash version of __lp_runtime_before.

__lp_set_prompt()
    Setup features that need to be handled outside of the themes, like _lp_error() (since last return code must be recorded first), non printing features like LP_ENABLE_RUNTIME_BELL and LP_ENABLE_TITLE, track current directory changes, and initialize data source cache variables. This function also calls the current theme functions.

    Changed in version 2.0: Renamed from _lp_set_prompt.

  Runtime

__lp_runtime_before()
    Hooks into the shell to run directly after the user hits return on a command, to record the current time before the command runs.

    Changed in version 2.0: Renamed from _lp_runtime_before.

__lp_runtime_after()
    Called by __lp_set_prompt() to run directly after the user command returns, to record the current time and calculate how long the command ran for.

    Changed in version 2.0: Renamed from _lp_runtime_after.

  Theme

__lp_theme_list() -> var:lp_theme_list
    Returns an array of Liquid Prompt themes currently loaded in memory. Looks for functions matching _lp_*_theme_prompt.

    New in version 2.0.

__lp_theme_bash_complete() -> var:COMPREPLY
    Uses __lp_theme_list() to provide Bash autocompletion for lp_theme().

    New in version 2.0.

__lp_theme_zsh_complete()
    Uses __lp_theme_list() to provide Zsh autocompletion for lp_theme().

    New in version 2.0.

  Title

__lp_get_last_command_line() -> var:command
    Returns the whole command line most recently submitted by the user.

    New in version 2.1.

__lp_print_title_command()
    Sets the terminal title to the normal set title, postpended with the currently running command.

    New in version 2.1.

  Temperature

__lp_temp_detect() -> var:_LP_TEMP_FUNCTION
    Attempts to run the possible temperature backend functions below to find one that works correctly. When one correctly returns a value, it is saved to _LP_TEMP_FUNCTION for use by _lp_temperature().

    Changed in version 2.0: Renamed from _lp_temp_detect.

    Changed in version 2.1: No longer takes arguments of what backends to try.

__lp_temp_acpi() -> var:lp_temperature
    A temperature backend using acpi.

    Changed in version 2.0: Renamed from _lp_temp_acpi. Return variable changed from temperature.

__lp_temp_sensors() -> var:lp_temperature
    A temperature backend using lm-sensors provided sensors.

    Changed in version 2.0: Renamed from _lp_temp_sensors. Return variable changed from temperature.

__lp_temp_sysfs() -> var:lp_temperature
    A temperature backend reading directly from the Linux sysfs file system.

    New in version 2.1.

  Utility

__lp_escape(string) -> var:ret
    Escape shell escape characters so they print correctly in PS1.

    In Bash, backslashes (\) are used to escape codes, so backslashes are replaced by two backslashes.

    In Zsh, percents (%) are used to escape codes, so percents are replaced by two percents.

    Changed in version 2.0: Renamed from _lp_escape. Return method changed from stdout.

__lp_floating_scale(number, scale) -> var:ret
    Returns the input floating point number multiplied by the input scale. The input scale must be a power of 10.

    Shells do not support floating point math, so this is used to scale up floating point numbers to integers with the needed precision.

    New in version 2.0.

__lp_is_function(function)
    Returns true if function is the name of a function.

    New in version 2.0.

__lp_line_count(string) -> var:count
    Count the number of newline characters (\n) in string. A faster drop-in replacement for wc -l.

    New in version 2.0.

__lp_strip_escapes(string) -> var:ret
    Remove shell escape characters so string prints correctly in a terminal title, or can be measured for printing character length.

    New in version 2.1.

  Wireless

__lp_wifi_signal_strength_raw() -> var:level
    Returns the lowest raw wireless signal strength in dBm. Return 2 if no data is found.

    Implementation depends on operating system. This function does not exist on all operating systems.

    New in version 2.1.

COPYRIGHT
2011-2024, Liquid Prompt team