1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# API
This page describes the Spacefish API for creating plugins and tweaking Spacefish's behavior.
Spacefish uses the `SPACEFISH_` prefix for variables and the `__sf_` prefix for functions to avoid namespace collisions. All sections, including custom ones, are required to use the `__sf_` prefix before their name to load correctly.
## Example section
Below is an example of a typical section for Spacefish. Pay attention to a few critical aspects:
* Variables used for configuration should start with `SPACEFISH_`.
* The section's name should start with `__sf_`.
* Only show the section as is needed (only in directories containing specific files, when a specific command is available, etc).
Take a look at [Contribution guidelines](../CONTRIBUTING.md) for further details.
```sh
#
# Foobar
#
# Foobar is a supa-dupa cool tool for making you development easier.
# Link: https://www.foobar.xyz
# __sf_ prefix before section's name is required!
# Otherwise this section won't be loaded.
function __sf_section_foobar -d "Show foobar status"
# ------------------------------------------------------------------------------
# Configuration
# ------------------------------------------------------------------------------
__sf_util_set_default SPACEFISH_FOOBAR_SHOW true
__sf_util_set_default SPACEFISH_FOOBAR_PREFIX $SPACEFISH_PROMPT_DEFAULT_PREFIX
__sf_util_set_default SPACEFISH_FOOBAR_SUFFIX $SPACEFISH_PROMPT_DEFAULT_SUFFIX
__sf_util_set_default SPACEFISH_FOOBAR_SYMBOL "🍷 "
__sf_util_set_default SPACEFISH_FOOBAR_COLOR white
# ------------------------------------------------------------------------------
# Section
# ------------------------------------------------------------------------------
# If SPACEFISH_FOOBAR_SHOW is false, don't show the foobar section
[ $SPACEFISH_FOOBAR_SHOW = false ]; and return
# If the foobar command doesn't exist, don't show the foobar section
type -q foobar; or return
# Here some of the various expressions that can be tested
# The full list can be found here:
# https://fishshell.com/docs/current/commands.html#test
type -q command # test that a command exists
test -e /path/to/file # test that a file exists
test -d /path/to/dir # test that a directory exists
test operand1 = operand2 # that for two equal strings
test -n "$variable" # test that a variable exists
# Use `set -l` to define local variables to avoid populating
# the global namespace
set -l foobar_status
if test "$SOME_CONDITION" = "true"
set foobar_status (foobar baz)
else
set foobar_status (foobar foo)
end
# Display the foobar section
__sf_lib_section \
$SPACEFISH_FOOBAR_COLOR \
$SPACEFISH_FOOBAR_PREFIX \
$SPACEFISH_FOOBAR_SYMBOL \
$SPACEFISH_FOOBAR_SUFFIX
end
```
## `SPACEFISH_VERSION`
An environment variable that defines the version of currently running Spacefish prompt. Can be used for issue reporting or debugging purposes.
Accessible to any program or script running in a current shell session.
### Example
```sh
echo $SPACEFISH_VERSION
#> 0.1.0
```
## `__sf_lib_section <color> [prefix] <content> [suffix]`
This function prints out the prompt section prefixed with `prefix`, suffixed with `suffix` and `content` formatted to display in `color`. The **Bold** style is applied by default.
`prefix`, `suffix` and `content` can contain `set_color` to set an additional foreground color, background color or other formatting styles. Read more about `set_color` in the [set_color - set the terminal color](https://fishshell.com/docs/current/commands.html#set_color) section of the Fish Shell documentation.
If `SPACEFISH_PROMPT_PREFIXES_SHOW` is `false` or if the section is the first to appear in the prompt, then `prefix` will be omitted.
If `SPACEFISH_PROMPT_SUFFIXES_SHOW` is `false`, then `suffix` will be omitted.
Both `prefix` and `suffix` are optional. They are equal to empty strings by default.
### Arguments
1. `color` _Required_ — The color used when displaying the `content`. Can be any of the valid [basic colors](https://fishshell.com/docs/current/commands.html#set_color) or can be any valid RGB hex code.
2. `prefix` _Optional_ — The prefix shown before `content`. Usually, it's the value of `SPACEFISH_*_PREFIX`.
3. `content` _Required_ — The content of the section. Can be any valid value or the result of command execution.
4. `suffix` _Optional_ — The suffix shown after `content`. Usually, it's the value of `SPACEFISH_*_SUFFIX`.
### Example
```sh
# Display the prompt section with a prefix and suffix
# Backslash is used to escape the line endings
__sf_lib_section \
$SPACEFISH_SECTION_COLOR \
$SPACEFISH_SECTION_PREFIX \
$SPACEFISH_SECTION_SYMBOL$section_content \
$SPACEFISH_SECTION_SUFFIX
# Display prompt section without prefix and suffix
__sf_lib_section $color $SPACEFISH_CHAR_SYMBOL
```
## `__sf_util_set_default <variable_name> <value>`
This utility function is used to define a default value for a variable while allowing it to be overwritten by a user's personal configuration files (e.g. setting it in their `config.fish`)
### Arguments
1. `variable_name` _Required_ — the name of the configuration variable.
2. `value` _Required_ — the value to be assigned by default.
### Example
```sh
# Preassign a value to `SPACEFISH_CHAR_SYMBOL`
set -g SPACEFISH_CHAR_SYMBOL ❯
# Assign a value if one doesn't already exist
__sf_util_set_default SPACEFISH_CHAR_SYMBOL ■
__sf_util_set_default SPACEFISH_RUBY_SYMBOL 💎
# The original value assigned is used
echo $SPACEFISH_CHAR_SYMBOL
#> ❯
echo $SPACEFISH_RUBY_SYMBOL
#> 💎
```
## `__sf_util_git_branch`
This utility returns the current branch name if the current working directory is a Git repository, and will return nothing if it's not.
### Example
```sh
# Return if the current working directory is not a Git repository
[ -z (__sf_util_git_branch) ]; and return
# Print the Git branch name of the current working directory
echo (__sf_util_git_branch)
#> master
```
|
