diff options
Diffstat (limited to 'doc/docs')
| -rw-r--r-- | doc/docs/api.rst | 23 | ||||
| -rw-r--r-- | doc/docs/cmdline.rst | 17 | ||||
| -rw-r--r-- | doc/docs/lexerdevelopment.rst | 45 | ||||
| -rw-r--r-- | doc/docs/quickstart.rst | 4 | ||||
| -rw-r--r-- | doc/docs/styles.rst | 47 |
5 files changed, 123 insertions, 13 deletions
diff --git a/doc/docs/api.rst b/doc/docs/api.rst index dd831bd1..a6b242dd 100644 --- a/doc/docs/api.rst +++ b/doc/docs/api.rst @@ -62,6 +62,18 @@ Functions from :mod:`pygments.lexers`: Will raise :exc:`pygments.util.ClassNotFound` if not lexer for that mimetype is found. +.. function:: load_lexer_from_file(filename, lexername="CustomLexer", **options) + + Return a `Lexer` subclass instance loaded from the provided file, relative + to the current directory. The file is expected to contain a Lexer class + named `lexername` (by default, CustomLexer). Users should be very careful with + the input, because this method is equivalent to running eval on the input file. + The lexer is given the `options` at its instantiation. + + :exc:`ClassNotFound` is raised if there are any errors loading the Lexer + + .. versionadded:: 2.2 + .. function:: guess_lexer(text, **options) Return a `Lexer` subclass instance that's guessed from the text in @@ -125,6 +137,17 @@ Functions from :mod:`pygments.formatters`: Will raise :exc:`pygments.util.ClassNotFound` if no formatter for that filename is found. +.. function:: load_formatter_from_file(filename, formattername="CustomFormatter", **options) + + Return a `Formatter` subclass instance loaded from the provided file, relative + to the current directory. The file is expected to contain a Formatter class + named ``formattername`` (by default, CustomFormatter). Users should be very + careful with the input, because this method is equivalent to running eval + on the input file. The formatter is given the `options` at its instantiation. + + :exc:`ClassNotFound` is raised if there are any errors loading the Formatter + + .. versionadded:: 2.2 .. module:: pygments.styles diff --git a/doc/docs/cmdline.rst b/doc/docs/cmdline.rst index 165af969..e4f94ea5 100644 --- a/doc/docs/cmdline.rst +++ b/doc/docs/cmdline.rst @@ -99,6 +99,23 @@ The ``-N`` option guesses a lexer name for a given filename, so that :: will print out ``python``. It won't highlight anything yet. If no specific lexer is known for that filename, ``text`` is printed. +Custom Lexers and Formatters +---------------------------- + +.. versionadded:: 2.2 + +The ``-x`` flag enables custom lexers and formatters to be loaded +from files relative to the current directory. Create a file with a class named +CustomLexer or CustomFormatter, then specify it on the command line:: + + $ pygmentize -l your_lexer.py -f your_formatter.py -x + +You can also specify the name of your class with a colon:: + + $ pygmentize -l your_lexer.py:SomeLexer -x + +For more information, see :doc:`the Pygments documentation on Lexer development +<lexerdevelopment>`. Getting help ------------ diff --git a/doc/docs/lexerdevelopment.rst b/doc/docs/lexerdevelopment.rst index fd6e76b9..63bd01a3 100644 --- a/doc/docs/lexerdevelopment.rst +++ b/doc/docs/lexerdevelopment.rst @@ -88,8 +88,47 @@ one. Adding and testing a new lexer ============================== -Using a lexer that is not part of Pygments can be done via the Python API. You -can import and instantiate the lexer, and pass it to :func:`pygments.highlight`. +The easiest way to use a new lexer is to use Pygments' support for loading +the lexer from a file relative to your current directory. + +First, change the name of your lexer class to CustomLexer: + +.. code-block:: python + + from pygments.lexer import RegexLexer + from pygments.token import * + + class CustomLexer(RegexLexer): + """All your lexer code goes here!""" + +Then you can load the lexer from the command line with the additional +flag ``-x``: + +.. code-block:: console + + $ pygmentize -l your_lexer_file.py -x + +To specify a class name other than CustomLexer, append it with a colon: + +.. code-block:: console + + $ pygmentize -l your_lexer.py:SomeLexer -x + +Or, using the Python API: + +.. code-block:: python + + # For a lexer named CustomLexer + your_lexer = load_lexer_from_file(filename, **options) + + # For a lexer named MyNewLexer + your_named_lexer = load_lexer_from_file(filename, "MyNewLexer", **options) + +When loading custom lexers and formatters, be extremely careful to use only +trusted files; Pygments will perform the equivalent of ``eval`` on them. + +If you only want to use your lexer with the Pygments API, you can import and +instantiate the lexer yourself, then pass it to :func:`pygments.highlight`. To prepare your new lexer for inclusion in the Pygments distribution, so that it will be found when passing filenames or lexer aliases from the command line, you @@ -361,7 +400,7 @@ There are a few more things you can do with states: tokens = {...} def get_tokens_unprocessed(self, text, stack=('root', 'otherstate')): - for item in RegexLexer.get_tokens_unprocessed(text, stack): + for item in RegexLexer.get_tokens_unprocessed(self, text, stack): yield item Some lexers like the `PhpLexer` use this to make the leading ``<?php`` diff --git a/doc/docs/quickstart.rst b/doc/docs/quickstart.rst index dba7698a..3a823e7f 100644 --- a/doc/docs/quickstart.rst +++ b/doc/docs/quickstart.rst @@ -39,7 +39,7 @@ Here is a small example for highlighting Python code: from pygments.formatters import HtmlFormatter code = 'print "Hello World"' - print highlight(code, PythonLexer(), HtmlFormatter()) + print(highlight(code, PythonLexer(), HtmlFormatter())) which prints something like this: @@ -56,7 +56,7 @@ can be produced by: .. sourcecode:: python - print HtmlFormatter().get_style_defs('.highlight') + print(HtmlFormatter().get_style_defs('.highlight')) The argument to :func:`get_style_defs` is used as an additional CSS selector: the output may look like this: diff --git a/doc/docs/styles.rst b/doc/docs/styles.rst index 1094a270..570293a5 100644 --- a/doc/docs/styles.rst +++ b/doc/docs/styles.rst @@ -153,17 +153,17 @@ Terminal Styles .. versionadded:: 2.2 Custom styles used with the 256-color terminal formatter can also map colors to -use the 8 default ANSI colors. To do so, use ``#ansigreen``, ``#ansired`` or +use the 8 default ANSI colors. To do so, use ``ansigreen``, ``ansibrightred`` or any other colors defined in :attr:`pygments.style.ansicolors`. 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 variants are treated as foreground color with and an added bold flag. -``bg:#ansi<color>`` will also be respected, except the light variant will be the +``bg:ansi<color>`` will also be respected, except the light variant will be the same shade as their dark variant. See the following example where the color of the string ``"hello world"`` is -governed by the escape sequence ``\x1b[34;01m`` (Ansi Blue, Bold, 41 being red +governed by the escape sequence ``\x1b[34;01m`` (Ansi bright blue, Bold, 41 being red background) instead of an extended foreground & background color. .. sourcecode:: pycon @@ -176,7 +176,7 @@ background) instead of an extended foreground & background color. >>> class MyStyle(Style): styles = { - Token.String: '#ansiblue bg:#ansired', + Token.String: 'ansibrightblue bg:ansibrightred', } >>> code = 'print("Hello World")' @@ -184,18 +184,49 @@ background) instead of an extended foreground & background color. >>> print(result.encode()) b'\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' -Colors specified using ``#ansi*`` are converted to a default set of RGB colors +Colors specified using ``ansi*`` are converted to a default set of RGB colors when used with formatters other than the terminal-256 formatter. By definition of ANSI, the following colors are considered "light" colors, and will be rendered by most terminals as bold: -- "darkgray", "red", "green", "yellow", "blue", "fuchsia", "turquoise", "white" +- "brightblack" (darkgrey), "brightred", "brightgreen", "brightyellow", "brightblue", + "brightmagenta", "brightcyan", "white" The following are considered "dark" colors and will be rendered as non-bold: -- "black", "darkred", "darkgreen", "brown", "darkblue", "purple", "teal", - "lightgray" +- "black", "red", "green", "yellow", "blue", "magenta", "cyan", + "gray" Exact behavior might depends on the terminal emulator you are using, and its settings. + +.. _new-ansi-color-names: + +.. versionchanged:: 2.4 + +The definition of the ANSI color names has changed. +New names are easier to understand and align to the colors used in other projects. + +===================== ==================== +New names Pygments up to 2.3 +===================== ==================== +``ansiblack`` ``#ansiblack`` +``ansired`` ``#ansidarkred`` +``ansigreen`` ``#ansidarkgreen`` +``ansiyellow`` ``#ansibrown`` +``ansiblue`` ``#ansidarkblue`` +``ansimagenta`` ``#ansipurple`` +``ansicyan`` ``#ansiteal`` +``ansigray`` ``#ansilightgray`` +``ansibrightblack`` ``#ansidarkgray`` +``ansibrightred`` ``#ansired`` +``ansibrightgreen`` ``#ansigreen`` +``ansibrightyellow`` ``#ansiyellow`` +``ansibrightblue`` ``#ansiblue`` +``ansibrightmagenta`` ``#ansifuchsia`` +``ansibrightcyan`` ``#ansiturquoise`` +``ansiwhite`` ``#ansiwhite`` +===================== ==================== + +Old ANSI color names are deprecated but will still work. |