diff options
author | Tanner Prynn <tanner.prynn@nccgroup.trust> | 2016-02-24 17:46:32 -0600 |
---|---|---|
committer | Tanner Prynn <tanner.prynn@nccgroup.trust> | 2016-02-24 17:46:32 -0600 |
commit | 1dcbeab604b4f6b9402a05895ceef1ce31177339 (patch) | |
tree | 6008ecde4c53170843898ae2f98cdd392ba2915c /doc | |
parent | cdec8b0e72a2716581d9e44174b754e2cb1b5c16 (diff) | |
download | pygments-1dcbeab604b4f6b9402a05895ceef1ce31177339.tar.gz |
Update pull request per comments by birkenfeld.
Add optional function parameter for the class name to instantiate, and update cli to support this.
Move error handling to within the loading functions; they now only raise ClassNotFound.
Modify doc with these updates and the version number.
Test case clean up and additions.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/docs/api.rst | 32 | ||||
-rw-r--r-- | doc/docs/cmdline.rst | 10 | ||||
-rw-r--r-- | doc/docs/lexerdevelopment.rst | 14 |
3 files changed, 31 insertions, 25 deletions
diff --git a/doc/docs/api.rst b/doc/docs/api.rst index ea158d65..a6b242dd 100644 --- a/doc/docs/api.rst +++ b/doc/docs/api.rst @@ -62,21 +62,17 @@ 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, **options) +.. 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 CustomLexer class - which matches Pygments' lexer definitions. Users should be very careful with + 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:`IOError` is raised if the file is not found or unreadable + :exc:`ClassNotFound` is raised if there are any errors loading the Lexer - :exc:`ImportError` is raised if the file doesn't have a CustomLexer class - - Additionally, arbitrary exceptions could occur when evaluating the file - - .. versionadded:: ? + .. versionadded:: 2.2 .. function:: guess_lexer(text, **options) @@ -141,21 +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, **options) +.. 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 CustomFormatter class - which matches Pygments' formatter definitions. 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. + 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:`IOError` is raised if the file is not found or unreadable + :exc:`ClassNotFound` is raised if there are any errors loading the Formatter - :exc:`ImportError` is raised if the file doesn't have a CustomFormatter class - - Additionally, arbitrary exceptions could occur when evaluating the file - - .. versionadded:: ? + .. versionadded:: 2.2 .. module:: pygments.styles diff --git a/doc/docs/cmdline.rst b/doc/docs/cmdline.rst index 8fcd3c8c..e4f94ea5 100644 --- a/doc/docs/cmdline.rst +++ b/doc/docs/cmdline.rst @@ -102,13 +102,17 @@ lexer is known for that filename, ``text`` is printed. Custom Lexers and Formatters ---------------------------- -.. versionadded:: ? +.. versionadded:: 2.2 -The ``--load-from-file`` flag enables custom lexers and formatters to be loaded +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 --load-from-file + $ 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>`. diff --git a/doc/docs/lexerdevelopment.rst b/doc/docs/lexerdevelopment.rst index 8c9b7baa..bba81d24 100644 --- a/doc/docs/lexerdevelopment.rst +++ b/doc/docs/lexerdevelopment.rst @@ -102,18 +102,28 @@ First, change the name of your lexer class to CustomLexer: """All your lexer code goes here!""" Then you can load the lexer from the command line with the additional -flag ``--load-from-file``: +flag ``-x``: .. code-block:: console - $ pygmentize -l your_lexer_file.py --load-from-file + $ 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. |