configs/home/.zsh-distrobox/themes/spaceship-prompt/docs/api/utils.md

# General utilities

Below you can find a list of general purpose utilities.

## `spaceship::exists`

``` title="Signature"
spaceship::exists <command>
```

This command validates that given program is available for execution. It checks for PATH binaries, functions, and builtins. It returns zero exit code if a `command` exists and non-zero code otherwise.

You can use this utility to check if some program is installed and perform actions conditionally. For example, you can either return an error and exit or continue script's execution. For example:

```zsh
# Check multiple commands for existing
if spaceship::exists nvm; then
  # extract nvm version
elif spaceship::exists node; then
  # extract node version
else
  return
fi

# Do nothing if docker is not installed
spaceship::exists docker || return
```

## `spaceship::defined`

``` title="Signature"
spaceship::defined <function>
```

The same as [`spaceship::exists`](#spaceshipexists), but for functions. It returns zero exit code if a `function` has been defined previously and non-zero if `function` hasn't.

You can use this utility to check if a user has previously defined a function or not. For example:

```zsh
# Check if section has been defined
if spaceship::defined spaceship_section; then
  spaceship_section
else
  # section is not found
fi
```

## `spaceship::is_git`

This utility returns zero exit code if a current working directory is a Git repository and non-zero if it's not. For example:

```zsh
# Return if current directory is not a git repository
spaceship::is_git || return
```

## `spaceship::is_hg`

The same as [`spaceship::is_git`](#spaceshipisgit), but for Mercurial repositories. This utility returns zero exit code if a current working directory is a Mercurial repository and non-zero if it's not.

```zsh
# Return if current directory is not a Mercurial repository
spaceship::is_hg || return
```

## `spaceship::is_section_async`

Checks if a section is asynchronous or not by checking `SPACESHIP_<SECTION>_ASYNC` option. This utility returns zero exit code if a section is asynchronous and non-zero if it's not.

If `SPACESHIP_PROMPT_ASYNC` is set to `false`, then all sections are considered to be synchronous.

``` title="Signature"
spaceship::is_section_async <section>
```

1. `section` _Required_ — a section to be checked.

Some sections are always synchronous, not matter what, to ensure correct work of the prompt. Those are: `user`, `dir`, `host`, `exec_time`, `async`, `line_sep`, `jobs`, `exit_code` and `char`.

## `spaceship::is_prompt_async`

Checks if the prompt works in asynchronous mode or not. This utility returns zero exit code if the prompt works in asynchronous mode and non-zero if it's not.

Check if `SPACESHIP_PROMPT_ASYNC` is set to `true` and [`zsh-async` is loaded](/api/environment/#asynchronous-runtime).

## `spaceship::deprecated`

This utility checks if `option` variable is set and if it is, prints the `message`. The `message` supports escapes to set foreground color, background color and other visual effects.

``` title="Signature"
spaceship::deprecated <option> [message]
```

1. `option` _Required_ — the name of a deprecated variable. If this variable is set (contains any value), then `"%B$deprecated%b is deprecated.` will be printed. `%B` and `%b` is escapes to set the bold style for text.
2. `message` _Optional_ — a string for additional deprecation message. Can contain prompt expansions.

Read more about escapes in [Prompt Expansion](http://zsh.sourceforge.net/Doc/Release/Prompt-Expansion.html) section of Zsh documentation.

Here's an example of usage:

```zsh
# Check if SPACESHIP_BATTERY_ALWAYS_SHOW is set
spaceship::deprecated SPACESHIP_BATTERY_ALWAYS_SHOW "Use %BSPACESHIP_BATTERY_SHOW='always'%b instead."
#> SPACESHIP_BATTERY_ALWAYS_SHOW is deprecated. Use SPACESHIP_BATTERY_SHOW='always' instead.
```

## `spaceship::displaytime`

This utility converts `seconds` into a human-readable format. It splits `seconds` into days (`d`), hours (`h`), minutes (`m`) and seconds (`s`).

``` title="Signature"
spaceship::displaytime <seconds> [precision]
```

1. `seconds` _Required_ — seconds for conversion into the readable format.
1. `precision` _Optional_ — precision of the output. Default value is `1`.

The usage example looks like this:

```zsh
spaceship::displaytime 123456
#> 1d 10h 17m 36.0s

paceship::displaytime 123.45 2
#> 2m 3.45s
```

## `spaceship::union`

A utility for performing a union (intersection) of arrays. It lists the contents found in two or more arrays.

Spaceship uses this utility internally for resolution of sections that need to be sourced.

``` title="Signature"
spaceship::union <arr1[ arr2[ ...]]>
```

1. `arr...` — a list of arrays.

Here is an example:

```zsh
arr1=('a' 'b' 'c')
arr2=('b' 'c' 'd')
arr3=('c' 'd' 'e')
spaceship::union $arr1 $arr2 $arr3
#> a b c d e
```

## `spaceship::upsearch`

Performs an upward search for a specific file or directory. Returns the path of the first found file or directory. Goes upwards up to the repository or system root directory. Useful for understanding the context of a current directory.

``` title="Signature"
spaceship::upsearch [--silent] <paths...>
```

1. `paths...` _Required_ — a list of paths to search.
2. `--silent` or `-s` _Optional_ — if set, then the utility will return zero exit code, if at least one of `paths` is found and non-zero, if not.

This can be used for detecting project context or finding a specific file upwards.

```zsh
# Understanding the project context
spaceship::upsearch -s package.json node_modules && echo "Node project detected."

# Finding a specific file upwards
spaceship::upsearch package.json
#> /path/to/project/package.json
```

## `spaceship::datafile`

This utility queries data files for a specific key. It returns the value of the key. Exits with non-zero code when the file type is unknown, data cannot be read, or the key is not found.

``` title="Signature"
spaceship::datafile --<type> <file> [key]
```

1. `--type` _Required_ — a type of the data file. Can be `json`, `yaml`, `toml` or `xml`.
2. `file` _Required_ — a path to the data file.
3. `key` _Optional_ — a key to query within a data file.

You can use this utility to query data from a data file:

```zsh
spaceship::datafile --json package.json "author.name"
#> "John Doe"
```

It needs the following tools for reading data files:

* JSON — [`jq`](https://stedolan.github.io/jq/), [`yq`](https://mikefarah.gitbook.io/yq/) or [`python-yq`](https://kislyuk.github.io/yq/), [`python`](https://www.python.org/), [`node`](https://nodejs.org/)
* YAML — [`yq`](https://mikefarah.gitbook.io/yq/) or [`python-yq`](https://kislyuk.github.io/yq/), [`python`](https://www.python.org/)
* TOML — `tomlq` (comes with [`python-yq`](https://kislyuk.github.io/yq/))
* XML — `xq` (comes with [`python-yq`](https://kislyuk.github.io/yq/))

!!! tip
    The most universal solution for reading data files is to use [`python-yq`](https://kislyuk.github.io/yq/).