diff options
Diffstat (limited to '.config/fisher/github.com/matchai/spacefish/docs/API.md')
| -rw-r--r-- | .config/fisher/github.com/matchai/spacefish/docs/API.md | 162 |
1 files changed, 0 insertions, 162 deletions
diff --git a/.config/fisher/github.com/matchai/spacefish/docs/API.md b/.config/fisher/github.com/matchai/spacefish/docs/API.md deleted file mode 100644 index a0db51a9..00000000 --- a/.config/fisher/github.com/matchai/spacefish/docs/API.md +++ /dev/null @@ -1,162 +0,0 @@ -# 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 -``` |