summaryrefslogtreecommitdiffstats
path: root/docs/source/configuration/reference.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/source/configuration/reference.rst602
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.