diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/source/configuration/reference.rst | 602 |
1 files changed, 602 insertions, 0 deletions
diff --git a/docs/source/configuration/reference.rst b/docs/source/configuration/reference.rst new file mode 100644 index 0000000..d4fd4ab --- /dev/null +++ b/docs/source/configuration/reference.rst @@ -0,0 +1,602 @@ +*********************** +Configuration reference +*********************** + +.. _config-main: + +Main configuration +================== + +:Location: :file:`powerline/config.json` + +The main configuration file defines some common options that applies to all +extensions, as well as some extension-specific options like themes and +colorschemes. + +Common configuration +-------------------- + +Common configuration is a subdictionary that is a value of ``common`` key in +:file:`powerline/config.json` file. + +.. _config-common-term_truecolor: + +``term_truecolor`` + Defines whether to output cterm indices (8-bit) or RGB colors (24-bit) + to the terminal emulator. See the :ref:`term-feature-support-matrix` for + information on whether used terminal emulator supports 24-bit colors. + + This variable is forced to be ``false`` if :ref:`term_escape_style + <config-common-term_escape_style>` option is set to ``"fbterm"`` or if it is + set to ``"auto"`` and powerline detected fbterm. + +.. _config-common-term_escape_style: + +``term_escape_style`` + Defines what escapes sequences should be used. Accepts three variants: + + ======= =================================================================== + Variant Description + ======= =================================================================== + auto ``xterm`` or ``fbterm`` depending on ``$TERM`` variable value: + ``TERM=fbterm`` implies ``fbterm`` escaping style, all other values + select ``xterm`` escaping. + xterm Uses ``\e[{fb};5;{color}m`` for colors (``{fb}`` is either ``38`` + (foreground) or ``48`` (background)). Should be used for most + terminals. + fbterm Uses ``\e[{fb};{color}}`` for colors (``{fb}`` is either ``1`` + (foreground) or ``2`` (background)). Should be used for fbterm: + framebuffer terminal. + ======= =================================================================== + +.. _config-common-ambiwidth: + +``ambiwidth`` + Tells powerline what to do with characters with East Asian Width Class + Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek + letters, Cyrillic letters). Valid values: any positive integer; it is + suggested that this option is only set it to 1 (default) or 2. + +.. _config-common-watcher: + +``watcher`` + Select filesystem watcher. Variants are + + ======= =================================== + Variant Description + ======= =================================== + auto Selects most performant watcher. + inotify Select inotify watcher. Linux only. + stat Select stat-based polling watcher. + uv Select libuv-based watcher. + ======= =================================== + + Default is ``auto``. + +.. _config-common-additional_escapes: + +``additional_escapes`` + Valid for shell extensions, makes sense only if :ref:`term_truecolor + <config-common-term_truecolor>` is enabled. Is to be set from command-line. + Controls additional escaping that is needed for tmux/screen to work with + terminal true color escape codes: normally tmux/screen prevent terminal + emulator from receiving these control codes thus rendering powerline prompt + colorless. Valid values: ``"tmux"``, ``"screen"``, ``null`` (default). + +.. _config-common-paths: + +``paths`` + Defines additional paths which will be searched for modules when using + :ref:`function segment option <config-themes-seg-function>` or :ref:`Vim + local_themes option <config-ext-local_themes>`. Paths defined here have + priority when searching for modules. + +.. _config-common-log: + +``log_file`` + Defines how logs will be handled. There are three variants here: + + #. Absent. In this case logging will be done to stderr: equivalent to + ``[["logging.StreamHandler", []]]`` or ``[null]``. + #. Plain string. In this case logging will be done to the given file: + ``"/file/name"`` is equivalent to ``[["logging.FileHandler", + [["/file/name"]]]]`` or ``["/file/name"]``. Leading ``~/`` is expanded in + the file name, so using ``"~/.log/foo"`` is permitted. If directory + pointed by the option is absent, it will be created, but not its parent. + #. List of handler definitions. Handler definition may either be ``null``, + a string or a list with two or three elements: + + #. Logging class name and module. If module name is absent, it is + equivalent to ``logging.handlers``. + #. Class constructor arguments in a form ``[[args[, kwargs]]]``: accepted + variants are ``[]`` (no arguments), ``[args]`` (e.g. + ``[["/file/name"]]``: only positional arguments) or ``[args, kwargs]`` + (e.g. ``[[], {"host": "localhost", "port": 6666}]``: positional and + keyword arguments, but no positional arguments in the example). + #. Optional logging level. Overrides :ref:`log_level key + <config-common-log_level>` and has the same format. + #. Optional format string. Partially overrides :ref:`log_format key + <config-common-log_format>` and has the same format. “Partially” here + means that it may only specify more critical level. + +.. _config-common-log_level: + +``log_level`` + String, determines logging level. Defaults to ``WARNING``. + +.. _config-common-log_format: + +``log_format`` + String, determines format of the log messages. Defaults to + ``'%(asctime)s:%(level)s:%(message)s'``. + +``interval`` + Number, determines time (in seconds) between checks for changed + configuration. Checks are done in a separate thread. Use ``null`` to check + for configuration changes on ``.render()`` call in main thread. + Defaults to ``None``. + +``reload_config`` + Boolean, determines whether configuration should be reloaded at all. + Defaults to ``True``. + +.. _config-common-default_top_theme: + +``default_top_theme`` + String, determines which top-level theme will be used as the default. + Defaults to ``powerline_terminus`` in unicode locales and ``ascii`` in + non-unicode locales. See `Themes`_ section for more details. + +Extension-specific configuration +-------------------------------- + +Common configuration is a subdictionary that is a value of ``ext`` key in +:file:`powerline/config.json` file. + +``colorscheme`` + Defines the colorscheme used for this extension. + +.. _config-ext-theme: + +``theme`` + Defines the theme used for this extension. + +.. _config-ext-top_theme: + +``top_theme`` + Defines the top-level theme used for this extension. See `Themes`_ section + for more details. + +.. _config-ext-local_themes: + +``local_themes`` + Defines themes used when certain conditions are met, e.g. for + buffer-specific statuslines in vim. Value depends on extension used. For vim + it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name`` + is either ``matcher_module.module_attribute`` or ``module_attribute`` + (``matcher_module`` defaults to ``powerline.matchers.vim``) and + ``module_attribute`` should point to a function that returns boolean value + indicating that current buffer has (not) matched conditions. There is an + exception for ``matcher_name`` though: if it is ``__tabline__`` no functions + are loaded. This special theme is used for ``tabline`` Vim option. + + For shell and ipython it is a simple ``{prompt_type : theme_name}``, where + ``prompt_type`` is a string with no special meaning (specifically it does + not refer to any Python function). Shell has ``continuation``, and + ``select`` prompts with rather self-explanatory names, IPython has ``in2``, + ``out`` and ``rewrite`` prompts (refer to IPython documentation for more + details) while ``in`` prompt is the default. + + For wm (:ref:`lemonbar <lemonbar-usage>` only) it is a dictionary + ``{output : theme_name}`` that maps the ``xrandr`` output names to the + local themes to use on that output. + +.. _config-ext-components: + +``components`` + Determines which extension components should be enabled. This key is highly + extension-specific, here is the table of extensions and corresponding + components: + + +---------+----------+-----------------------------------------------------+ + |Extension|Component |Description | + +---------+----------+-----------------------------------------------------+ + |vim |statusline|Makes Vim use powerline statusline. | + | +----------+-----------------------------------------------------+ + | |tabline |Makes Vim use powerline tabline. | + +---------+----------+-----------------------------------------------------+ + |shell |prompt |Makes shell display powerline prompt. | + | +----------+-----------------------------------------------------+ + | |tmux |Makes shell report its current working directory | + | | |and screen width to tmux for tmux powerline | + | | |bindings. | + | | | | + +---------+----------+-----------------------------------------------------+ + + All components are enabled by default. + +.. _config-ext-update_interval: + +``update_interval`` + Determines how often WM status bars need to be updated, in seconds. Only + valid for WM extensions which use ``powerline-daemon``. Defaults to + 2 seconds. + +.. _config-colors: + +Color definitions +================= + +:Location: :file:`powerline/colors.json` + +.. _config-colors-colors: + +``colors`` + Color definitions, consisting of a dict where the key is the name of the + color, and the value is one of the following: + + * A cterm color index. + * A list with a cterm color index and a hex color string (e.g. ``[123, + "aabbcc"]``). This is useful for colorschemes that use colors that + aren’t available in color terminals. + +``gradients`` + Gradient definitions, consisting of a dict where the key is the name of the + gradient, and the value is a list containing one or two items, second item + is optional: + + * A list of cterm color indices. + * A list of hex color strings. + + It is expected that gradients are defined from least alert color to most + alert or non-alert colors are used. + +.. _config-colorschemes: + +Colorschemes +============ + +:Location: :file:`powerline/colorschemes/{name}.json`, + :file:`powerline/colorschemes/__main__.json`, + :file:`powerline/colorschemes/{extension}/{name}.json` + +Colorscheme files are processed in order given: definitions from each next file +override those from each previous file. It is required that either +:file:`powerline/colorschemes/{name}.json`, or +:file:`powerline/colorschemes/{extension}/{name}.json` exists. + +``name`` + Name of the colorscheme. + +.. _config-colorschemes-groups: + +``groups`` + Segment highlighting groups, consisting of a dict where the key is the + name of the highlighting group (usually the function name for function + segments), and the value is either + + #) a dict that defines the foreground color, background color and + attributes: + + ``fg`` + Foreground color. Must be defined in :ref:`colors + <config-colors-colors>`. + + ``bg`` + Background color. Must be defined in :ref:`colors + <config-colors-colors>`. + + ``attrs`` + List of attributes. Valid values are one or more of ``bold``, + ``italic`` and ``underline``. Note that some attributes may be + unavailable in some applications or terminal emulators. If no + attributes are needed this list should be left empty. + + #) a string (an alias): a name of existing group. This group’s definition + will be used when this color is requested. + +``mode_translations`` + Mode-specific highlighting for extensions that support it (e.g. the vim + extension). It’s an easy way of changing a color in a specific mode. + Consists of a dict where the key is the mode and the value is a dict + with the following options: + + ``colors`` + A dict where the key is the color to be translated in this mode, and + the value is the new color. Both the key and the value must be defined + in :ref:`colors <config-colors-colors>`. + + ``groups`` + Segment highlighting groups for this mode. Same syntax as the main + :ref:`groups <config-colorschemes-groups>` option. + +.. _config-themes: + +Themes +====== + +:Location: :file:`powerline/themes/{top_theme}.json`, + :file:`powerline/themes/{extension}/__main__.json`, + :file:`powerline/themes/{extension}/{name}.json` + +Theme files are processed in order given: definitions from each next file +override those from each previous file. It is required that file +:file:`powerline/themes/{extension}/{name}.json` exists. + +`{top_theme}` component of the file name is obtained either from :ref:`top_theme +extension-specific key <config-ext-top_theme>` or from :ref:`default_top_theme +common configuration key <config-common-default_top_theme>`. Powerline ships +with the following top themes: + +.. _config-top_themes-list: + +========================== ==================================================== +Theme Description +========================== ==================================================== +powerline Default powerline theme with fancy powerline symbols +powerline_unicode7 Theme with powerline dividers and unicode-7 symbols +unicode Theme without any symbols from private use area +unicode_terminus Theme containing only symbols from terminus PCF font +unicode_terminus_condensed Like above, but occupies as less space as possible +powerline_terminus Like unicode_terminus, but with powerline symbols +ascii Theme without any unicode characters at all +========================== ==================================================== + +``name`` + Name of the theme. + +.. _config-themes-default_module: + +``default_module`` + Python module where segments will be looked by default. Defaults to + ``powerline.segments.{ext}``. + +``spaces`` + Defines number of spaces just before the divider (on the right side) or just + after it (on the left side). These spaces will not be added if divider is + not drawn. + +``use_non_breaking_spaces`` + Determines whether non-breaking spaces should be used in place of the + regular ones. This option is needed because regular spaces are not displayed + properly when using powerline with some font configuration. Defaults to + ``True``. + + .. note:: + Unlike all other options this one is only checked once at startup using + whatever theme is :ref:`the default <config-ext-theme>`. If this option + is set in the local themes it will be ignored. This option may also be + ignored in some bindings. + +``outer_padding`` + Defines number of spaces at the end of output (on the right side) or at + the start of output (on the left side). Defaults to ``1``. + + +``dividers`` + Defines the dividers used in all Powerline extensions. + + The ``hard`` dividers are used to divide segments with different + background colors, while the ``soft`` dividers are used to divide + segments with the same background color. + +.. _config-themes-cursor_space: + +``cursor_space`` + Space reserved for user input in shell bindings. It is measured in per + cents. + +``cursor_columns`` + Space reserved for user input in shell bindings. Unlike :ref:`cursor_space + <config-themes-cursor_space>` it is measured in absolute amount of columns. + +.. _config-themes-segment_data: + +``segment_data`` + A dict where keys are segment names or strings ``{module}.{function}``. Used + to specify default values for various keys: + :ref:`after <config-themes-seg-after>`, + :ref:`before <config-themes-seg-before>`, + :ref:`contents <config-themes-seg-contents>` (only for string segments + if :ref:`name <config-themes-seg-name>` is defined), + :ref:`display <config-themes-seg-display>`. + + Key :ref:`args <config-themes-seg-args>` (only for function and + segment_list segments) is handled specially: unlike other values it is + merged with all other values, except that a single ``{module}.{function}`` + key if found prevents merging all ``{function}`` values. + + When using :ref:`local themes <config-ext-local_themes>` values of these + keys are first searched in the segment description, then in ``segment_data`` + key of a local theme, then in ``segment_data`` key of a :ref:`default theme + <config-ext-theme>`. For the :ref:`default theme <config-ext-theme>` itself + step 2 is obviously avoided. + + .. note:: Top-level themes are out of equation here: they are merged + before the above merging process happens. + +.. _config-themes-segments: + +``segments`` + A dict with a ``left`` and a ``right`` lists, consisting of segment + dictionaries. Shell themes may also contain ``above`` list of dictionaries. + Each item in ``above`` list may have ``left`` and ``right`` keys like this + dictionary, but no ``above`` key. + + .. _config-themes-above: + + ``above`` list is used for multiline shell configurations. + + ``left`` and ``right`` lists are used for segments that should be put on the + left or right side in the output. Actual mechanizm of putting segments on + the left or the right depends on used renderer, but most renderers require + one to specify segment with :ref:`width <config-themes-seg-width>` ``auto`` + on either side to make generated line fill all of the available width. + + Each segment dictionary has the following options: + + .. _config-themes-seg-type: + + ``type`` + The segment type. Can be one of ``function`` (default), ``string`` or + ``segment_list``: + + ``function`` + The segment contents is the return value of the function defined in + the :ref:`function option <config-themes-seg-function>`. + + List of function segments is available in :ref:`Segment reference + <config-segments>` section. + + ``string`` + A static string segment where the contents is defined in the + :ref:`contents option <config-themes-seg-contents>`, and the + highlighting group is defined in the :ref:`highlight_groups option + <config-themes-seg-highlight_groups>`. + + ``segment_list`` + Sub-list of segments. This list only allows :ref:`function + <config-themes-seg-function>`, :ref:`segments + <config-themes-seg-segments>` and :ref:`args + <config-themes-seg-args>` options. + + List of lister segments is available in :ref:`Lister reference + <config-listers>` section. + + .. _config-themes-seg-name: + + ``name`` + Segment name. If present allows referring to this segment in + :ref:`segment_data <config-themes-segment_data>` dictionary by this + name. If not ``string`` segments may not be referred there at all and + ``function`` and ``segment_list`` segments may be referred there using + either ``{module}.{function_name}`` or ``{function_name}``, whichever + will be found first. Function name is taken from :ref:`function key + <config-themes-seg-function>`. + + .. note:: + If present prevents ``function`` key from acting as a segment name. + + .. _config-themes-seg-function: + + ``function`` + Function used to get segment contents, in format ``{module}.{function}`` + or ``{function}``. If ``{module}`` is omitted :ref:`default_module + option <config-themes-default_module>` is used. + + .. _config-themes-seg-highlight_groups: + + ``highlight_groups`` + Highlighting group for this segment. Consists of a prioritized list of + highlighting groups, where the first highlighting group that is + available in the colorscheme is used. + + Ignored for segments that have ``function`` type. + + .. _config-themes-seg-before: + + ``before`` + A string which will be prepended to the segment contents. + + .. _config-themes-seg-after: + + ``after`` + A string which will be appended to the segment contents. + + .. _config-themes-seg-contents: + + ``contents`` + Segment contents, only required for ``string`` segments. + + .. _config-themes-seg-args: + + ``args`` + A dict of arguments to be passed to a ``function`` segment. + + .. _config-themes-seg-align: + + ``align`` + Aligns the segments contents to the left (``l``), center (``c``) or + right (``r``). Has no sense if ``width`` key was not specified or if + segment provides its own function for ``auto`` ``width`` handling and + does not care about this option. + + .. _config-themes-seg-width: + + ``width`` + Enforces a specific width for this segment. + + This segment will work as a spacer if the width is set to ``auto``. + Several spacers may be used, and the space will be distributed + equally among all the spacer segments. Spacers may have contents, + either returned by a function or a static string, and the contents + can be aligned with the ``align`` property. + + .. _config-themes-seg-priority: + + ``priority`` + Optional segment priority. Segments with priority ``None`` (the default + priority, represented by ``null`` in json) will always be included, + regardless of the width of the prompt/statusline. + + If the priority is any number, the segment may be removed if the + prompt/statusline width is too small for all the segments to be + rendered. A lower number means that the segment has a higher priority. + + Segments are removed according to their priority, with low priority + segments (i.e. with a greater priority number) being removed first. + + .. _config-themes-seg-draw_divider: + + ``draw_hard_divider``, ``draw_soft_divider`` + Whether to draw a divider between this and the adjacent segment. The + adjacent segment is to the *right* for segments on the *left* side, and + vice versa. Hard dividers are used between segments with different + background colors, soft ones are used between segments with same + background. Both options default to ``True``. + + .. _config-themes-seg-draw_inner_divider: + + ``draw_inner_divider`` + Determines whether inner soft dividers are to be drawn for function + segments. Only applicable for functions returning multiple segments. + Defaults to ``False``. + + .. _config-themes-seg-exclude_modes: + + ``exclude_modes``, ``include_modes`` + A list of modes where this segment will be excluded: the segment is not + included or is included in all modes, *except* for the modes in one of + these lists respectively. If ``exclude_modes`` is not present then it + acts like an empty list (segment is not excluded from any modes). + Without ``include_modes`` it acts like a list with all possible modes + (segment is included in all modes). When there are both + ``exclude_modes`` overrides ``include_modes``. + + .. _config-themes-seg-exclude_function: + + ``exclude_function``, ``include_function`` + Function name in a form ``{name}`` or ``{module}.{name}`` (in the first + form ``{module}`` defaults to ``powerline.selectors.{ext}``). Determines + under which condition specific segment will be included or excluded. By + default segment is always included and never excluded. + ``exclude_function`` overrides ``include_function``. + + .. note:: + Options :ref:`exclude_/include_modes + <config-themes-seg-exclude_modes>` complement + ``exclude_/include_functions``: segment will be included if it is + included by either ``include_mode`` or ``include_function`` and will + be excluded if it is excluded by either ``exclude_mode`` or + ``exclude_function``. + + .. _config-themes-seg-display: + + ``display`` + Boolean. If false disables displaying of the segment. + Defaults to ``True``. + + .. _config-themes-seg-segments: + + ``segments`` + A list of subsegments. |