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. 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.
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 thecontent. Can be any of basic colors or color codes.--prefix— prefix beforecontent. Usually, it's the value ofSPACESHIP_<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 aftercontent. Usually, it's the value ofSPACESHIP_<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 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:
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 instead.
This is a replacement for the spaceship::section function used in Spaceship v3. Use it for backward compatibility only.
spaceship::section <color> [prefix] <content> [suffix]
The spaceship::section:v3 relies on the following arguments order:
colorRequired — color for displaying thecontent. Can be any of basic colors or color codes.prefixOptional — prefix beforecontent. Usually, it's the value ofSPACESHIP_<SECTION>_PREFIX.contentRequired — the content of the section. Can be any valid value or result of command execution.suffixOptional — suffix aftercontent. Usually, it's the value ofSPACESHIP_<SECTION>_SUFFIX.
Here is a simple example:
# 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.
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:
local color="red" content="value"
spaceship::section::render "$(spaceship::section --color "$color" "$content")"
#> %{%B%F{red}%}value%{%b%f%}