diff options
115 files changed, 4142 insertions, 2553 deletions
diff --git a/Cargo.lock b/Cargo.lock index d9ad9d52a..17026fa67 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -868,6 +868,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0" [[package]] +name = "quick-xml" +version = "0.18.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3cc440ee4802a86e357165021e3e255a9143724da31db1e2ea540214c96a0f82" +dependencies = [ + "memchr", +] + +[[package]] name = "quote" version = "1.0.7" source = "registry+https://github.com/rust-lang/crates.io-index" @@ -1151,6 +1160,7 @@ dependencies = [ "pest", "pest_derive", "pretty_env_logger", + "quick-xml", "rayon", "regex", "remove_dir_all", diff --git a/Cargo.toml b/Cargo.toml index 111675f2f..b4dbf110d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -59,6 +59,7 @@ open = "1.4.0" unicode-width = "0.1.8" textwrap = "0.12.1" term_size = "0.3.2" +quick-xml = "0.18.1" # Optional/http: attohttpc = { version = "0.15.0", optional = true, default-features = false, features = ["tls", "form"] } diff --git a/docs/config/README.md b/docs/config/README.md index 01750a601..7dd339525 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -20,8 +20,8 @@ All configuration for starship is done in this [TOML](https://github.com/toml-la add_newline = false # Replace the "❯" symbol in the prompt with "➜" -[character] # The name of the module we are configuring is "character" -symbol = "➜" # The "symbol" segment is being set to "➜" +[character] # The name of the module we are configuring is "character" +success_symbol = "[➜](bold green)" # The "success_symbol" segment is being set to "➜" with the color "bold green" # Disable the package module, hiding it from the prompt completely [package] @@ -29,11 +29,13 @@ disabled = true ``` You can change default `starship.toml` file location with `STARSHIP_CONFIG` environment variable: + ```sh export STARSHIP_CONFIG=~/.starship ``` Equivalently in PowerShell (Windows) would be adding this line to your `$PROFILE`: + ```ps1 $ENV:STARSHIP_CONFIG = "$HOME\.starship" ``` @@ -42,17 +44,43 @@ $ENV:STARSHIP_CONFIG = "$HOME\.starship" **Module**: A component in the prompt giving information based on contextual information from your OS. For example, the "nodejs" module shows the version of NodeJS that is currently installed on your computer, if your current directory is a NodeJS project. -**Segment**: Smaller sub-components that compose a module. For example, the "symbol" segment in the "nodejs" module contains the character that is shown before the version number (⬢ by default). +**Variable**: Smaller sub-components that contains information provided by the module. For example, the "version" variable in the "nodejs" module contains the current version of NodeJS. -Here is the representation of the node module. In the following example, "symbol" and "version" -are segments within it. Every module also has a prefix and suffix that are the default terminal color. +By convention, most modules have a prefix of default terminal color (e.g. `via ` in "nodejs") and an empty space as a suffix. -``` -[prefix] [symbol] [version] [suffix] - "via " "⬢" "v10.4.1" "" -``` +### Format Strings + +Format strings are the format that a module prints all its variables with. +Most modules have an entry called `format` that configures the display format of the module. +You can use texts, variables and text groups in a format string. + +#### Variable + +A variable contains a `$` symbol followed by the name of the variable. +The name of a variable only contains letters, numbers and `_`. + +For example: + +- `$version` is a format string with a variable named `version`. +- `$git_branch$git_commit` is a format string with two variables named `git_branch` and `git_commit`. +- `$git_branch $git_commit` has the two variables separated with a space. + +#### Text Group + +A text group is made up of two different parts. + +The first part, which is enclosed in a `[]`, is a [format string](#format-strings). +You can add texts, variables, or even nested text groups in it. + +In the second part, which is enclosed in a `()`, is a [style string](#style-strings). This can be used style the first part. -### Style Strings +For example: + +- `[on](red bold)` will print a string `on` with bold text colored red. +- `[⬢ $version](bold green)` will print a symbol `⬢ ` followed by the content of variable `version`, with bold text colored green. +- `[a [b](red) c](green)` will print `a b c` with `b` red, and `a` and `c` green. + +#### Style Strings Most modules in starship allow you to configure their display styles. This is done with an entry (usually called `style`) which is a string specifying the configuration. Here are some examples of style strings along with what they do. For details on the full syntax, consult the [advanced config guide](/advanced-config/). @@ -65,17 +93,60 @@ Most modules in starship allow you to configure their display styles. This is do Note that what styling looks like will be controlled by your terminal emulator. For example, some terminal emulators will brighten the colors instead of bolding text, and some color themes use the same values for the normal and bright colors. Also, to get italic text, your terminal must support italics. +#### Conditional Format Strings + +A conditional format string wrapped in `(` and `)` will not render if all variables inside are empty. + +For example: + +- `(@$region)` will show nothing if the variable `region` is `None`, otherwise `@` followed by the value of region. +- `(some text)` will always show nothing since there are no variables wrapped in the braces. +- When `$all` is a shortcut for `\[$a$b\] `, `($all)` will show nothing only if `$a` and `$b` are both `None`. + This works the same as `(\[$a$b\] )`. + +#### Escapable characters + +The following symbols have special usage in a format string. +If you want to print the following symbols, you have to escape them with a backslash (`\`). + +- $ +- \\ +- [ +- ] +- ( +- ) + +Note that `toml` has [its own escape syntax](https://github.com/toml-lang/toml#user-content-string). +It is recommended to use a literal string (`''`) in your config. +If you want to use a basic string (`""`), pay attention to escape the backslash `\`. + +For example, when you want to print a `$` symbol on a new line, the following configs for `format` are equivalent: + +```toml +# with basic string +format = "\n\\$" + +# with multiline basic string +format = """ + +\\$""" + +# with literal string +format = ''' + +\$''' +``` + ## Prompt |