1
0
mirror of https://github.com/dcarrillo/prezto.git synced 2024-12-23 07:58:00 +00:00
prezto/modules/prompt/README.md
Kaleb Elwert cbcbedd694 prompt: Add basic troubleshooting information for fonts
This is related to #1495 and a number of other issues which have been
filed about font issues.
2017-10-24 12:52:42 -07:00

157 lines
4.0 KiB
Markdown

Prompt
======
Loads prompt [themes][1].
Settings
--------
### Prompt Theme
To select a prompt theme, add the following to *zpreztorc*, and replace **name**
with the name of the theme you wish to load. Setting it to **random** will load
a random theme.
```sh
zstyle ':prezto:module:prompt' theme 'name'
```
### Prompt Display Length
To change working directory prompt display length from 'short', set the
following to 'long' (without `~` expansion) or 'full' (with `~` expansion)
in *zpreztorc*.
```sh
zstyle ':prezto:module:prompt' pwd-length 'short'
```
### Display Return Value
Some prompts display the return value in the prompt. If a prompt has support,
this can be disabled with the following snippet.
```sh
zstyle ':prezto:module:prompt' show-return-val 'no'
```
Theming
-------
A prompt theme is an autoloadable function file with a special name,
`prompt_name_setup`, placed anywhere in `$fpath`, but for the purpose of this
project, themes **should** be placed in the *modules/prompt/functions*
directory.
### Theme Functions
There are three theme functions, a setup function, a help function, and
a preview function. The setup function **must** always be defined. The help
function and the preview functions are optional.
#### `prompt_name_setup`
This function is called by the `prompt` function to install the theme. This
function may define other functions as necessary to maintain the prompt,
including a function that displays help or a function used to preview it.
**Do not call this function directly.**
The most basic example of this function can be seen below.
```sh
function prompt_name_setup {
PROMPT='%m%# '
RPROMPT=''
}
```
#### `prompt_name_help`
If the `prompt_name_setup` function is customizable via parameters, a help
function **should** be defined. The user will access it via `prompt -h name`.
The most basic example of this function can be seen below.
```sh
function prompt_name_help {
cat <<EOH
This prompt is color-scheme-able. You can invoke it thus:
prompt theme [<color1>] [<color2>]
where the color is for the left-hand prompt.
EOH
}
```
#### `prompt_name_preview`
If the `prompt_name_setup` function is customizable via parameters, a preview
function **should** be defined. The user will access it via `prompt -p name`.
The most basic example of this function can be seen below.
```sh
function prompt_name_preview {
if (( $# > 0 )); then
prompt_preview_theme theme "$@"
else
prompt_preview_theme theme red green blue
print
prompt_preview_theme theme yellow magenta black
fi
}
```
### Hook Functions
There are many Zsh [hook][2] functions, but mostly the *precmd* hook will be
used.
#### `prompt_name_precmd`
This hook is called before the prompt is displayed and is useful for getting
information to display in a prompt.
When calling functions to get information to display in a prompt, do not assume
that all the dependencies have been loaded. Always check for the availability of
a function before you calling it.
**Do not register hook functions. They will be registered by the `prompt` function.**
The most basic example of this function can be seen below.
```sh
function prompt_name_precmd {
if (( $+functions[git-info] )); then
git-info
fi
}
```
Troubleshooting
---------------
### Fonts aren't displaying properly.
On most systems, themes which use special characters need to have a patched font
installed and configured properly.
Powerline provides some information on [terminal support][4] and [how to install
patched fonts][5] which should fix most font issues.
Authors
-------
*The authors of this module should be contacted via the [issue tracker][3].*
- [Sorin Ionescu](https://github.com/sorin-ionescu)
[1]: http://zsh.sourceforge.net/Doc/Release/User-Contributions.html#Prompt-Themes
[2]: http://zsh.sourceforge.net/Doc/Release/Functions.html#Hook-Functions
[3]: https://github.com/sorin-ionescu/prezto/issues
[4]: http://powerline.readthedocs.io/en/master/usage.html#terminal-emulator-requirements
[5]: http://powerline.readthedocs.io/en/latest/installation.html#fonts-installation