diff options
author | Tanner Prynn <tanner.prynn@nccgroup.trust> | 2016-02-22 16:34:46 -0600 |
---|---|---|
committer | Tanner Prynn <tanner.prynn@nccgroup.trust> | 2016-02-22 16:34:46 -0600 |
commit | cdec8b0e72a2716581d9e44174b754e2cb1b5c16 (patch) | |
tree | 4a3de42bb06c9bb03d6d38296acff33e13690128 /doc | |
parent | 4a8e158be9bdfa22f112f27ff62e83896ef5af86 (diff) | |
download | pygments-cdec8b0e72a2716581d9e44174b754e2cb1b5c16.tar.gz |
Add api, command line, etc. documentation for custom lexer/formatter loading
Diffstat (limited to 'doc')
-rw-r--r-- | doc/docs/api.rst | 11 | ||||
-rw-r--r-- | doc/docs/cmdline.rst | 13 | ||||
-rw-r--r-- | doc/docs/lexerdevelopment.rst | 34 |
3 files changed, 54 insertions, 4 deletions
diff --git a/doc/docs/api.rst b/doc/docs/api.rst index 1b6ca668..ea158d65 100644 --- a/doc/docs/api.rst +++ b/doc/docs/api.rst @@ -71,8 +71,12 @@ Functions from :mod:`pygments.lexers`: The lexer is given the `options` at its instantiation. :exc:`IOError` is raised if the file is not found or unreadable + :exc:`ImportError` is raised if the file doesn't have a CustomLexer class - :exc:`Exception` for any other error raised when evaluating filename + + Additionally, arbitrary exceptions could occur when evaluating the file + + .. versionadded:: ? .. function:: guess_lexer(text, **options) @@ -146,9 +150,12 @@ Functions from :mod:`pygments.formatters`: The formatter is given the `options` at its instantiation. :exc:`IOError` is raised if the file is not found or unreadable + :exc:`ImportError` is raised if the file doesn't have a CustomFormatter class - :exc:`Exception` for any other error raised when evaluating filename + Additionally, arbitrary exceptions could occur when evaluating the file + + .. versionadded:: ? .. module:: pygments.styles diff --git a/doc/docs/cmdline.rst b/doc/docs/cmdline.rst index 165af969..8fcd3c8c 100644 --- a/doc/docs/cmdline.rst +++ b/doc/docs/cmdline.rst @@ -99,6 +99,19 @@ 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:: ? + +The ``--load-from-file`` 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 --load-from-file + +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 2c868440..8c9b7baa 100644 --- a/doc/docs/lexerdevelopment.rst +++ b/doc/docs/lexerdevelopment.rst @@ -88,8 +88,38 @@ one. Adding and testing a new lexer ============================== -To make Pygments aware of your new lexer, you have to perform the following -steps: +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 ``--load-from-file``: + +.. code-block:: console + + $ pygmentize -l your_lexer_file.py --load-from-file + +Or, using the Python API: + +.. code-block:: python + + your_lexer = load_lexer_from_file(filename, **options) + +When loading custom lexers and formatters, be extremely careful to use only +trusted files; Pygments will perform the equivalent of ``eval`` on them. + +For more complicated tasks, you should add your lexer to Pygments. If you +want to make Pygments aware of your new lexer, you have to perform the +following steps: First, change to the current directory containing the Pygments source code: |