107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# Sections
|
|
|
|
Sections are defined using `spaceship::section` function. This section takes the content of the section parameters for displaying, like prefix, suffix, color and symbol for the section. These values will be used for displaying the section.
|
|
|
|
The `spaceship::section` is used to pack the section data into a data tuple. This data tuple is stored in the cache. During the rendering process, the data tuple for each section is being rendered into a section via `spaceship::section::render` function.
|
|
|
|
## `spaceship::section`
|
|
|
|
!!! tip
|
|
For creating a custom section, prefer using the [`spaceship::section::v4` function](#spaceshipsectionv4). The versioned function will ensure compatibility with new versions of Spaceship.
|
|
|
|
This is the main function for defining a section. This takes section parameters and its content and transforms it into a data tuple.
|
|
|
|
``` title="Signature"
|
|
spaceship::section [--color color] [--prefix prefix] [--suffix suffix] [--symbol symbol] <content>
|
|
```
|
|
|
|
It takes a single argument `content` which is the content of the section. Additionally, the function takes the following optional parameters:
|
|
|
|
* `--color` — color for displaying the `content`. Can be any of [basic colors](https://wiki.archlinux.org/index.php/zsh#Colors) or [color codes](https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg).
|
|
* `--prefix` — prefix before `content`. Usually, it's the value of `SPACESHIP_<SECTION>_PREFIX`.
|
|
* `--symbol` — the symbol of the section. Can be any valid value or result of command execution. Will be rendered before the content.
|
|
* `--suffix` — suffix after `content`. Usually, it's the value of `SPACESHIP_<SECTION>_SUFFIX`.
|
|
|
|
The order of the parameters is not important. All of them are default to empty strings.
|
|
|
|
!!! help
|
|
The `content`, `--prefix`, `--suffix` and `--symbol` can contain escapes to set additional foreground color, background color and other visual effects.
|
|
|
|
Read more about escapes in [13 Prompt Expansion](http://zsh.sourceforge.net/Doc/Release/Prompt-Expansion.html) section of Zsh documentation.
|
|
|
|
## `spaceship::section::v4`
|
|
|
|
This is an alias of `spaceship::section` function. It's the versioned function for creating a custom section.
|
|
|
|
The signature of this function is the same as for `spaceship::section` function.
|
|
|
|
Here is an example usage:
|
|
|
|
```zsh
|
|
local content="value"
|
|
|
|
spaceship::section::v4 \
|
|
--color "$SPACESHIP_SECTION_COLOR" \
|
|
--prefix "$SPACESHIP_SECTION_PREFIX" \
|
|
--suffix "$SPACESHIP_SECTION_SUFFIX" \
|
|
--symbol "$SPACESHIP_SECTION_SYMBOL" \
|
|
"$content"
|
|
```
|
|
|
|
## `spaceship::section::v3`
|
|
|
|
!!! warning
|
|
This function is introduced for compatibility with Spaceship v3 sections. It's recommended to use the [`spaceship::section::v4` function](#spaceshipsectionv4) instead.
|
|
|
|
This is a replacement for the `spaceship::section` function used in Spaceship v3. Use it for backward compatibility only.
|
|
|
|
``` title="Signature"
|
|
spaceship::section <color> [prefix] <content> [suffix]
|
|
```
|
|
|
|
The `spaceship::section:v3` relies on the following arguments order:
|
|
|
|
1. `color` _Required_ — color for displaying the `content`. Can be any of [basic colors](https://wiki.archlinux.org/index.php/zsh#Colors) or [color codes](https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg).
|
|
2. `prefix` _Optional_ — prefix before `content`. Usually, it's the value of `SPACESHIP_<SECTION>_PREFIX`.
|
|
3. `content` _Required_ — the content of the section. Can be any valid value or result of command execution.
|
|
4. `suffix` _Optional_ — suffix after `content`. Usually, it's the value of `SPACESHIP_<SECTION>_SUFFIX`.
|
|
|
|
Here is a simple example:
|
|
|
|
```zsh
|
|
# Display prompt section with prefix and suffix
|
|
# Backslash is used to escape line ending
|
|
spaceship::section \
|
|
"$SPACESHIP_SECTION_COLOR" \
|
|
"$SPACESHIP_SECTION_PREFIX" \
|
|
"$SPACESHIP_SECTION_SYMBOL$section_content" \
|
|
"$SPACESHIP_SECTION_SUFFIX"
|
|
|
|
# Display prompt section without prefix and suffix
|
|
spaceship::section "$color" "$SPACESHIP_CHAR_SYMBOL"
|
|
```
|
|
|
|
## `spaceship::section::render`
|
|
|
|
This function renders the section from the data tuple provided by [`spaceship::section`](#spaceshipsection).
|
|
|
|
``` title="Signature"
|
|
spaceship::render section <data>
|
|
```
|
|
|
|
If `SPACESHIP_PROMPT_PREFIXES_SHOW` is `false` or if the section is not the first in the prompt, then prefix will be omitted.
|
|
|
|
If `SPACESHIP_PROMPT_SUFFIXES_SHOW` is `false`, then suffix will be omitted.
|
|
|
|
The `data` is a result of the `spaceship::section` function. For example:
|
|
|
|
```zsh
|
|
local color="red" content="value"
|
|
|
|
spaceship::section::render "$(spaceship::section --color "$color" "$content")"
|
|
#> %{%B%F{red}%}value%{%b%f%}
|
|
```
|
|
|
|
!!! tip
|
|
You can use for rendering subsections within complex sections. See the sources of [`git`](https://github.com/spaceship-prompt/spaceship-prompt/blob/master/sections/git.zsh) or [`docker`](https://github.com/spaceship-prompt/spaceship-prompt/blob/master/sections/docker.zsh) sections for an example.
|