# Overview
- [📦 crates.io](https://crates.io/crates/eliprompt)
- [📖 Documentation](https://docs.rs/eliprompt)
- [⚖ MIT license](https://spdx.org/licenses/MIT.html)

CLI to generate a shell prompt.

# Font
The default prompt configuration uses symbols from [Nerd Fonts](https://www.nerdfonts.com/) and
expects one of them to be installed.

# Shell support
Only zsh is supported. Please open an issue if support for another shell is desired.

# Installation
```sh
cargo install eliprompt
```

Make sure `eliprompt` is in your `PATH` and add the following to `.zshrc`:
```sh
eval "$(eliprompt install --shell zsh)"
```

# Configuration
The prompt is made of blocks. Each block contains the text to display as well as the style
(foreground and background colors).

The configuration is stored in `~/.config/eliprompt/config.json`. It consists of a JSON object
of type [`Config`](#config-type). `Config` and the other JSON types involved are detailed below.

## `BlockProducer` type
JSON object with a single field named after its type among:
- [`Elapsed`](#elapsed-type)
- [`ExitCode`](#exitcode-type)
- [`GitHead`](#githead-type)
- [`GitPath`](#gitpath-type)
- [`Hostname`](#hostname-type)
- [`WorkingDirectory`](#workingdirectory-type)
- [`Username`](#username-type)
- [`Newline`](#newline-type)
- [`Space`](#space-type)
- [`Text`](#text-type)
- [`ExitStatusSymbol`](#exitstatussymbol-type)
- [`Or`](#or-type)
- [`Sequence`](#sequence-type)
- [`Separated`](#separated-type)
- [`Styled`](#styled-type)

## `Color` type
String with a CSS color name (e.g. `"red"`) or a CSS sRGB color (e.g. `"#ff1000"`).

## `Config` type
Root configuration object. JSON object with the following fields:
- `prompt` [optional]:
  - Type: [`BlockProducer`](#blockproducer-type)
  - The prompt definition.
- `alternative_prompt` [optional]:
  - Type: [`BlockProducer`](#blockproducer-type) or `null`
  - Alternative prompt definition to use when `$TERM` is `linux` or the environment variable
    `ELIPROMPT_ALTERNATIVE_PROMPT` is defined.
- `timeout` [optional]:
  - Type: [`Duration`](#duration-type)
  - Maximum time allocated to build the prompt. If it takes longer, a default prompt will be shown.

## `Duration` type
String containing a duration with unit, e.g. `"3s"` for 3 seconds.

## `Elapsed` type
Shows the duration of the previous command. JSON object with the following fields:
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the duration.
- `threshold` [optional]:
  - Type: [`Duration`](#duration-type)
  - The duration of a command is displayed if and only if it took longer than the threshold.

## `ExitCode` type
Shows the exit code of the previous command if it was not zero. JSON object with the following
fields:
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the exit code.

## `ExitStatusSymbol` type
- `style` [optional]:
  - Type: [`Style`](#style-type)
  - Style to use when the exit status is zero.
- `error_style` [optional]:
  - Type: [`Style`](#style-type)
  - Style to use when the exit status is not zero.
- `contents`:
  - Type: `String`

## `GitHead` type
Shows the current git branch. JSON object with the following fields:
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the git branch.

## `GitPath` type
If the current working directory is in a git repository, it is shown relative to the root of the
repository. JSON object with the following fields:
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the path.

## `Hostname` type
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the hostname.

## `Newline` type
Adds a newline character.

## `Or` type
List of [`BlockProducer`](#blockproducer-type) items. Returns blocks from the first producer that
produces at least one block.

## `Separated` type
- `separator_style` [optional]:
  - Type: [`Style`](#style-type)
  - Style to use for the separator.
- `separator` [optional]:
  - Type: `String`
  - Separator to insert between groups of blocks generated by the producers.
- `producers`:
  - Type: List of [`BlockProducer`](#blockproducer-type) items

## `Sequence` type
List of [`BlockProducer`](#blockproducer-type) items. Returns blocks from all producers.

## `Space` type
Adds a space character.

## `Style` type
JSON object with the following fields:
- `foreground` [optional]:
  - Type: [`Color`](#color-type) or `null`
- `background` [optional]:
  - Type: [`Color`](#color-type) or `null`

## `Styled` type
- `style` [optional]:
  - Type: [`Style`](#style-type)
  - Default style for items that do not specify their foreground or background color.
- `producer`:
  - Type: [`BlockProducer`](#blockproducer-type)
  - Generator whose blocks the default style is applied to.

## `Text` type
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `contents`:
  - Type: `String`

## `Username` type
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the username.

## `WorkingDirectory` type
Shows the current working directory. JSON object with the following fields:
- `style` [optional]:
  - Type: [`Style`](#style-type)
- `home_as_tilde` [optional]:
  - Type: `bool`
  - Indicates if the home directory should be displayed as a tilde.
- `prefix` [optional]:
  - Type: `String`
  - Text to display before the working directory.

## Example
```json
{
  "prompt": {
    "Styled": {
      "style": {
        "foreground": "teal",
        "background": "black"
      },
      "producer": {
        "Sequence": [
          {
            "Separated": {
              "separator_style": {},
              "separator": " | ",
              "producers": [
                {
                  "Separated": {
                    "separator_style": {},
                    "separator": "@",
                    "producers": [
                      {
                        "Username": {
                          "style": {},
                          "prefix": ""
                        }
                      },
                      {
                        "Hostname": {
                          "style": {},
                          "prefix": ""
                        }
                      }
                    ]
                  }
                },
                {
                  "Or": [
                    {
                      "GitPath": {
                        "style": {},
                        "prefix": ""
                      }
                    },
                    {
                      "WorkingDirectory": {
                        "style": {},
                        "home_as_tilde": true,
                        "prefix": ""
                      }
                    }
                  ]
                },
                {
                  "GitHead": {
                    "style": {},
                    "prefix": ""
                  }
                },
                {
                  "Elapsed": {
                    "style": {},
                    "prefix": "祥",
                    "threshold": "2s"
                  }
                },
                {
                  "ExitCode": {
                    "style": {
                      "foreground": "crimson"
                    },
                    "prefix": ""
                  }
                }
              ]
            }
          },
          {
            "Newline": null
          },
          {
            "ExitStatusSymbol": {
              "style": {
                "foreground": "dodgerblue"
              },
              "error_style": {
                "foreground": "crimson"
              },
              "contents": "→"
            }
          },
          {
            "Space": null
          }
        ]
      }
    }
  },
  "alternative_prompt": {
    "Styled": {
      "style": {
        "foreground": "teal"
      },
      "producer": {
        "Sequence": [
          {
            "Separated": {
              "separator_style": {},
              "separator": " | ",
              "producers": [
                {
                  "Separated": {
                    "separator_style": {},
                    "separator": "@",
                    "producers": [
                      {
                        "Username": {
                          "style": {},
                          "prefix": ""
                        }
                      },
                      {
                        "Hostname": {
                          "style": {},
                          "prefix": ""
                        }
                      }
                    ]
                  }
                },
                {
                  "WorkingDirectory": {
                    "style": {},
                    "home_as_tilde": true,
                    "prefix": ""
                  }
                },
                {
                  "Elapsed": {
                    "style": {},
                    "prefix": "",
                    "threshold": "2s"
                  }
                },
                {
                  "ExitCode": {
                    "style": {
                      "foreground": "crimson"
                    },
                    "prefix": ""
                  }
                }
              ]
            }
          },
          {
            "Newline": null
          },
          {
            "ExitStatusSymbol": {
              "style": {
                "foreground": "dodgerblue"
              },
              "error_style": {
                "foreground": "crimson"
              },
              "contents": "→"
            }
          },
          {
            "Space": null
          }
        ]
      }
    }
  },
  "timeout": "1s"
}
```

# Contribute
All contributions shall be licensed under the [MIT license](https://spdx.org/licenses/MIT.html).

# Related projects
[starship](https://github.com/starship/starship) provides more blocks and supports more shells.