diff options
author | Georg Brandl <georg@python.org> | 2016-02-14 19:07:16 +0100 |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2016-02-14 19:07:16 +0100 |
commit | f8e9795479bdace4e822641567d806538a345f4f (patch) | |
tree | 1f7b1d99f35d28a1ef2a27a49046797e48179186 /doc | |
parent | e71840a35ffb2aa453542ecd6f770ffbaa7db439 (diff) | |
parent | 064edec39bc9075dad066450c9a5bab254f4a581 (diff) | |
download | pygments-f8e9795479bdace4e822641567d806538a345f4f.tar.gz |
Merged in Carreau/pygments-main/256ansi (pull request #531)
Allow ansi escape sequence as color format
Diffstat (limited to 'doc')
-rw-r--r-- | doc/docs/styles.rst | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/doc/docs/styles.rst b/doc/docs/styles.rst index d56db0db..0076d062 100644 --- a/doc/docs/styles.rst +++ b/doc/docs/styles.rst @@ -143,3 +143,62 @@ a way to iterate over all styles: >>> from pygments.styles import get_all_styles >>> styles = list(get_all_styles()) + + +.. _AnsiTerminalStyle: + +Terminal Styles +=============== + +.. versionadded:: 2.2 + +Custom styles used with `Terminal256` formatter can also defines colors using +ansi-color. To do so use the `#ansigreen`, `#ansired` or any other colors +defined in ``pygments.style.ansilist``. Foreground ANSI colors will be mapped +to the corresponding `escape codes 30 to 37 +<https://en.wikipedia.org/wiki/ANSI_escape_code#Colors>`_ thus respecting any +custom color mapping and themes provided by many terminal emulators. Light +variant are treated for foreground color with and extra bold flag. +`bg:#ansi<color>` will also be respected, except the light variant will be the +same shade as their light variant. + +See following example where the color of the string `"hello world"` is governed +by the escape sequence `\x1b34;01m` (Ansi Blue, Bold, `41` beeing red background) +instead of an extended foreground & background color. + +.. sourcecode:: pycon + + >>> from pygments import highlight + >>> from pygments.style import Style + >>> from pygments.token import Token + >>> from pygments.lexers import Python3Lexer + >>> from pygments.formatters import Terminal256Formatter + + >>> class MyStyle(Style): + styles = { + Token.String: '#ansiblue bg:#ansired', + } + + >>> code = 'print("Hello World")' + >>> result = highlight(code, Python3Lexer(), Terminal256Formatter(style=MyStyle)) + >>> print(result.encode()) + b'print(\x1b[34;41;01m"\x1b[39;49;00m\x1b[34;41;01mHello World\x1b[39;49;00m\x1b[34;41;01m"\x1b[39;49;00m)\n' + +Style that use `#ansi*` colors might not correctly work with +formatters others than ``Terminal256``. `HtmlFormatter` is capable of handling +some `#ansi*` code and will map to a fixed HTML/CSS color. For example, +`#ansiblue` will be converted to `color:#0000ff` , `#ansired` to `color:#ff0000`. + +By definition of Ansi color the following color are considered "light" colors, +and will be rendered by most terminal as bold: + + - "darkgray", "red", "green", "yellow", "blue", "fuchsia", "turquoise", + "white" + + +The following are considered "dark" color and will be rendered as non-bold: + + - "black", "darkred", "darkgreen", "brown", "darkblue", "purple", "teal", + "lightgray" + +Exact behavior might depends on the terminal emulator you are using, and its settings. |