diff options
Diffstat (limited to 'docs/source/configuration/local.rst')
| -rw-r--r-- | docs/source/configuration/local.rst | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/docs/source/configuration/local.rst b/docs/source/configuration/local.rst new file mode 100644 index 0000000..0f3d110 --- /dev/null +++ b/docs/source/configuration/local.rst @@ -0,0 +1,260 @@ +.. _local-configuration-overrides: + +***************************** +Local configuration overrides +***************************** + +Depending on the application used it is possible to override configuration. Here +is the list: + +Vim overrides +============= + +Vim configuration can be overridden using the following options: + +.. _local-configuration-overrides-vim-config: + +``g:powerline_config_overrides`` + Dictionary, recursively merged with contents of + :file:`powerline/config.json`. + +``g:powerline_theme_overrides`` + Dictionary mapping theme names to theme overrides, recursively merged with + contents of :file:`powerline/themes/vim/{key}.json`. Note that this way some + value (e.g. segment) in a list cannot be redefined, only the whole list + itself: only dictionaries are merged recursively. + +``g:powerline_config_paths`` + Paths list (each path must be expanded, ``~`` shortcut is not supported). + Points to the list of directories which will be searched for configuration. + When this option is present, none of the other locations are searched. + +``g:powerline_no_python_error`` + If this variable is set to a true value it will prevent Powerline from reporting + an error when loaded in a copy of vim without the necessary Python support. + +``g:powerline_use_var_handler`` + This variable may be set to either 0 or 1. If it is set to 1 then Vim will + save log in ``g:powerline_log_messages`` variable in addition to whatever + was configured in :ref:`log_* options <config-common-log>`. Level is always + :ref:`log_level <config-common-log_level>`, same for format. + + .. warning:: + This variable is deprecated. Use :ref:`log_file option + <config-common-log>` in conjunction with + :py:class:`powerline.vim.VimVarHandler` class and :ref:`Vim config + overrides variable <local-configuration-overrides-vim-config>`. Using + this is also the only variant to make saving into the environment + variable the *only* place where log is saved or save into different + variable. + + .. autoclass:: powerline.vim.VimVarHandler + +.. _local-configuration-overrides-script: + +Powerline script overrides +========================== + +Powerline script has a number of options controlling powerline behavior. Here +``VALUE`` always means “some JSON object”. + +``-c KEY.NESTED_KEY=VALUE`` or ``--config-override=KEY.NESTED_KEY=VALUE`` + Overrides options from :file:`powerline/config.json`. + ``KEY.KEY2.KEY3=VALUE`` is a shortcut for ``KEY={"KEY2": {"KEY3": VALUE}}``. + Multiple options (i.e. ``-c K1=V1 -c K2=V2``) are allowed, result (in the + example: ``{"K1": V1, "K2": V2}``) is recursively merged with the contents + of the file. + + If ``VALUE`` is omitted then corresponding key will be removed from the + configuration (if it was present). + +``-t THEME_NAME.KEY.NESTED_KEY=VALUE`` or ``--theme-override=THEME_NAME.KEY.NESTED_KEY=VALUE`` + Overrides options from :file:`powerline/themes/{ext}/{THEME_NAME}.json`. + ``KEY.NESTED_KEY=VALUE`` is processed like described above, ``{ext}`` is the + first argument to powerline script. May be passed multiple times. + + If ``VALUE`` is omitted then corresponding key will be removed from the + configuration (if it was present). + +``-p PATH`` or ``--config-path=PATH`` + Sets directory where configuration should be read from. If present, no + default locations are searched for configuration. No expansions are + performed by powerline script itself, but ``-p ~/.powerline`` will likely be + expanded by the shell to something like ``-p /home/user/.powerline``. + +.. warning:: + Such overrides are suggested for testing purposes only. Use + :ref:`Environment variables overrides <local-configuration-overrides-env>` + for other purposes. + +.. _local-configuration-overrides-env: + +Environment variables overrides +=============================== + +All bindings that use ``POWERLINE_COMMAND`` environment variable support taking +overrides from environment variables. In this case overrides should look like +the following:: + + OVERRIDE='key1.key2.key3=value;key4.key5={"value":1};key6=true;key1.key7=10' + +. This will be parsed into + +.. code-block:: Python + + { + "key1": { + "key2": { + "key3": "value" + }, + "key7": 10, + }, + "key4": { + "key5": { + "value": 1, + }, + }, + "key6": True, + } + +. Rules: + +#. Environment variable must form a semicolon-separated list of key-value pairs: + ``key=value;key2=value2``. +#. Keys are always dot-separated strings that must not contain equals sign (as + well as semicolon) or start with an underscore. They are interpreted + literally and create a nested set of dictionaries: ``k1.k2.k3`` creates + ``{"k1":{"k2":{}}}`` and inside the innermost dictionary last key (``k3`` in + the example) is contained with its value. +#. Value may be empty in which case they are interpreted as an order to remove + some value: ``k1.k2=`` will form ``{"k1":{"k2":REMOVE_THIS_KEY}}`` nested + dictionary where ``k2`` value is a special value that tells + dictionary-merging function to remove ``k2`` rather then replace it with + something. +#. Value may be a JSON strings like ``{"a":1}`` (JSON dictionary), ``["a",1]`` + (JSON list), ``1`` or ``-1`` (JSON number), ``"abc"`` (JSON string) or + ``true``, ``false`` and ``null`` (JSON boolean objects and ``Null`` object + from JSON). General rule is that anything starting with a digit (U+0030 till + U+0039, inclusive), a hyphenminus (U+002D), a quotation mark (U+0022), a left + curly bracket (U+007B) or a left square bracket (U+005B) is considered to be + some JSON object, same for *exact* values ``true``, ``false`` and ``null``. +#. Any other value is considered to be literal string: ``k1=foo:bar`` parses to + ``{"k1": "foo:bar"}``. + +The following environment variables may be used for overrides according to the +above rules: + +``POWERLINE_CONFIG_OVERRIDES`` + Overrides values from :file:`powerline/config.json`. + +``POWERLINE_THEME_OVERRIDES`` + Overrides values from :file:`powerline/themes/{ext}/{key}.json`. Top-level + key is treated as a name of the theme for which overrides are used: e.g. to + disable cwd segment defined in :file:`powerline/themes/shell/default.json` + one needs to use:: + + POWERLINE_THEME_OVERRIDES=default.segment_data.cwd.display=false + +Additionally one environment variable is a usual *colon*-separated list of +directories: ``POWERLINE_CONFIG_PATHS``. This one defines paths which will be +searched for configuration. Empty paths in ``POWERLINE_CONFIG_PATHS`` are +ignored. + +.. note:: + Overrides from environment variables have lower priority then + :ref:`Powerline script overrides <local-configuration-overrides-script>`. + Latter are suggested for tests only. + +Zsh/zpython overrides +===================== + +Here overrides are controlled by similarly to the powerline script, but values +are taken from zsh variables. :ref:`Environment variable overrides +<local-configuration-overrides-env>` are also supported: if variable is a string +this variant is used. + +``POWERLINE_CONFIG_OVERRIDES`` + Overrides options from :file:`powerline/config.json`. Should be a zsh + associative array with keys equal to ``KEY.NESTED_KEY`` and values being + JSON strings. Pair ``KEY.KEY1 VALUE`` is equivalent to ``{"KEY": {"KEY1": + VALUE}}``. All pairs are then recursively merged into one dictionary and + this dictionary is recursively merged with the contents of the file. + +``POWERLINE_THEME_OVERRIDES`` + Overrides options from :file:`powerline/themes/shell/*.json`. Should be + a zsh associative array with keys equal to ``THEME_NAME.KEY.NESTED_KEY`` and + values being JSON strings. Is processed like the above + ``POWERLINE_CONFIG_OVERRIDES``, but only subdictionaries for ``THEME_NAME`` + key are merged with theme configuration when theme with given name is + requested. + +``POWERLINE_CONFIG_PATHS`` + Sets directories where configuration should be read from. If present, no + default locations are searched for configuration. No expansions are + performed by powerline script itself, but zsh usually performs them on its + own if variable without is set without quotes: ``POWERLINE_CONFIG_PATHS=( + ~/example )``. In addition to arrays usual colon-separated “array” string + can be used: ``POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2``. + +Ipython overrides +================= + +Ipython overrides depend on ipython version. Before ipython-0.11 additional +keyword arguments should be passed to setup() function. After ipython-0.11 +``c.Powerline.KEY`` should be used. Supported ``KEY`` strings or keyword +argument names: + +``config_overrides`` + Overrides options from :file:`powerline/config.json`. Should be a dictionary + that will be recursively merged with the contents of the file. + +``theme_overrides`` + Overrides options from :file:`powerline/themes/ipython/*.json`. Should be + a dictionary where keys are theme names and values are dictionaries which + will be recursively merged with the contents of the given theme. + +``config_paths`` + Sets directories where configuration should be read from. If present, no + default locations are searched for configuration. No expansions are + performed thus paths starting with ``~/`` cannot be used: use + :py:func:`os.path.expanduser`. + +Prompt command +============== + +In addition to the above configuration options ``$POWERLINE_COMMAND`` +environment variable can be used to tell shell or tmux to use specific powerline +implementation and ``$POWERLINE_CONFIG_COMMAND`` to tell zsh or tmux where +``powerline-config`` script is located. This is mostly useful for putting +powerline into different directory. + +.. note:: + + ``$POWERLINE_COMMAND`` is always treated as one path in shell bindings, so + path with spaces in it may be used. To specify additional arguments one may + use ``$POWERLINE_COMMAND_ARGS``, but note that this variable exists for + testing purposes only and may be removed. One should use :ref:`Environment + variable overrides <local-configuration-overrides-env>` instead. + +To disable prompt in shell, but still have tmux support or to disable tmux +support environment variables ``$POWERLINE_NO_{SHELL}_PROMPT`` and +``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT`` can be used (substitute ``{SHELL}`` with +the name of the shell (all-caps) that should be affected (e.g. ``BASH``) or use +all-inclusive ``SHELL`` that will disable support for all shells). These +variables have no effect after configuration script was sourced (in fish case: +after ``powerline-setup`` function was run). To disable specific feature support +set one of these variables to some non-empty value. + +In order to keep shell prompt, but avoid launching Python twice to get unused +:ref:`above <config-themes-above>` lines in tcsh ``$POWERLINE_NO_TCSH_ABOVE`` or +``$POWERLINE_NO_SHELL_ABOVE`` variable should be set. + +In order to remove additional space from the end of the right prompt in fish +that was added in order to support multiline prompt ``$POWERLINE_NO_FISH_ABOVE`` +or ``$POWERLINE_NO_SHELL_ABOVE`` variable should be set. + +PDB overrides +============= + +Like shell bindings :ref:`PDB bindings <pdb-prompt>` take overrides from +:ref:`environment variables <local-configuration-overrides-env>`. |