From efb336a23b65a9a2d56889396b13c1757bdaf354 Mon Sep 17 00:00:00 2001 From: Roger Gonzalez Date: Sun, 29 Dec 2019 14:58:33 -0300 Subject: Initial commit --- .../github.com/matchai/spacefish/docs/API.md | 162 +++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 .config/fisher/github.com/matchai/spacefish/docs/API.md (limited to '.config/fisher/github.com/matchai/spacefish/docs/API.md') diff --git a/.config/fisher/github.com/matchai/spacefish/docs/API.md b/.config/fisher/github.com/matchai/spacefish/docs/API.md new file mode 100644 index 00000000..a0db51a9 --- /dev/null +++ b/.config/fisher/github.com/matchai/spacefish/docs/API.md @@ -0,0 +1,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 [prefix] [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 ` + +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 +``` -- cgit v1.2.3