pygments.rb 1.2.1 → 2.2.0

data/vendor/pygments-main/doc/docs/authors.rst

@@ -1,4 +0,0 @@
-Full contributor list
-=====================
-
-.. include:: ../../AUTHORS

data/vendor/pygments-main/doc/docs/changelog.rst

@@ -1 +0,0 @@
-.. include:: ../../CHANGES

data/vendor/pygments-main/doc/docs/cmdline.rst

@@ -1,166 +0,0 @@
-.. -*- mode: rst -*-
-
-======================
-Command Line Interface
-======================
-
-You can use Pygments from the shell, provided you installed the
-:program:`pygmentize` script::
-
-    $ pygmentize test.py
-    print "Hello World"
-
-will print the file test.py to standard output, using the Python lexer
-(inferred from the file name extension) and the terminal formatter (because
-you didn't give an explicit formatter name).
-
-If you want HTML output::
-
-    $ pygmentize -f html -l python -o test.html test.py
-
-As you can see, the -l option explicitly selects a lexer. As seen above, if you
-give an input file name and it has an extension that Pygments recognizes, you can
-omit this option.
-
-The ``-o`` option gives an output file name. If it is not given, output is
-written to stdout.
-
-The ``-f`` option selects a formatter (as with ``-l``, it can also be omitted
-if an output file name is given and has a supported extension).
-If no output file name is given and ``-f`` is omitted, the
-:class:`.TerminalFormatter` is used.
-
-The above command could therefore also be given as::
-
-    $ pygmentize -o test.html test.py
-
-To create a full HTML document, including line numbers and stylesheet (using the
-"emacs" style), highlighting the Python file ``test.py`` to ``test.html``::
-
-    $ pygmentize -O full,style=emacs -o test.html test.py
-
-
-Options and filters
--------------------
-
-Lexer and formatter options can be given using the ``-O`` option::
-
-    $ pygmentize -f html -O style=colorful,linenos=1 -l python test.py
-
-Be sure to enclose the option string in quotes if it contains any special shell
-characters, such as spaces or expansion wildcards like ``*``. If an option
-expects a list value, separate the list entries with spaces (you'll have to
-quote the option value in this case too, so that the shell doesn't split it).
-
-Since the ``-O`` option argument is split at commas and expects the split values
-to be of the form ``name=value``, you can't give an option value that contains
-commas or equals signs.  Therefore, an option ``-P`` is provided (as of Pygments
-0.9) that works like ``-O`` but can only pass one option per ``-P``. Its value
-can then contain all characters::
-
-    $ pygmentize -P "heading=Pygments, the Python highlighter" ...
-
-Filters are added to the token stream using the ``-F`` option::
-
-    $ pygmentize -f html -l pascal -F keywordcase:case=upper main.pas
-
-As you see, options for the filter are given after a colon. As for ``-O``, the
-filter name and options must be one shell word, so there may not be any spaces
-around the colon.
-
-
-Generating styles
------------------
-
-Formatters normally don't output full style information.  For example, the HTML
-formatter by default only outputs ``<span>`` tags with ``class`` attributes.
-Therefore, there's a special ``-S`` option for generating style definitions.
-Usage is as follows::
-
-    $ pygmentize -f html -S colorful -a .syntax
-
-generates a CSS style sheet (because you selected the HTML formatter) for
-the "colorful" style prepending a ".syntax" selector to all style rules.
-
-For an explanation what ``-a`` means for :doc:`a particular formatter
-<formatters>`, look for the `arg` argument for the formatter's
-:meth:`.get_style_defs()` method.
-
-
-Getting lexer names
--------------------
-
-.. versionadded:: 1.0
-
-The ``-N`` option guesses a lexer name for a given filename, so that ::
-
-    $ pygmentize -N setup.py
-
-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
-------------
-
-The ``-L`` option lists lexers, formatters, along with their short
-names and supported file name extensions, styles and filters. If you want to see
-only one category, give it as an argument::
-
-    $ pygmentize -L filters
-
-will list only all installed filters.
-
-The ``-H`` option will give you detailed information (the same that can be found
-in this documentation) about a lexer, formatter or filter. Usage is as follows::
-
-    $ pygmentize -H formatter html
-
-will print the help for the HTML formatter, while ::
-
-    $ pygmentize -H lexer python
-
-will print the help for the Python lexer, etc.
-
-
-A note on encodings
--------------------
-
-.. versionadded:: 0.9
-
-Pygments tries to be smart regarding encodings in the formatting process:
-
-* If you give an ``encoding`` option, it will be used as the input and
-  output encoding.
-
-* If you give an ``outencoding`` option, it will override ``encoding``
-  as the output encoding.
-
-* If you give an ``inencoding`` option, it will override ``encoding``
-  as the input encoding.
-
-* If you don't give an encoding and have given an output file, the default
-  encoding for lexer and formatter is the terminal encoding or the default
-  locale encoding of the system.  As a last resort, ``latin1`` is used (which
-  will pass through all non-ASCII characters).
-
-* If you don't give an encoding and haven't given an output file (that means
-  output is written to the console), the default encoding for lexer and
-  formatter is the terminal encoding (``sys.stdout.encoding``).

data/vendor/pygments-main/doc/docs/filterdevelopment.rst

@@ -1,71 +0,0 @@
-.. -*- mode: rst -*-
-
-=====================
-Write your own filter
-=====================
-
-.. versionadded:: 0.7
-
-Writing own filters is very easy. All you have to do is to subclass
-the `Filter` class and override the `filter` method. Additionally a
-filter is instantiated with some keyword arguments you can use to
-adjust the behavior of your filter.
-
-
-Subclassing Filters
-===================
-
-As an example, we write a filter that converts all `Name.Function` tokens
-to normal `Name` tokens to make the output less colorful.
-
-.. sourcecode:: python
-
-    from pygments.util import get_bool_opt
-    from pygments.token import Name
-    from pygments.filter import Filter
-
-    class UncolorFilter(Filter):
-
-        def __init__(self, **options):
-            Filter.__init__(self, **options)
-            self.class_too = get_bool_opt(options, 'classtoo')
-
-        def filter(self, lexer, stream):
-            for ttype, value in stream:
-                if ttype is Name.Function or (self.class_too and
-                                              ttype is Name.Class):
-                    ttype = Name
-                yield ttype, value
-
-Some notes on the `lexer` argument: that can be quite confusing since it doesn't
-need to be a lexer instance. If a filter was added by using the `add_filter()`
-function of lexers, that lexer is registered for the filter. In that case
-`lexer` will refer to the lexer that has registered the filter. It *can* be used
-to access options passed to a lexer. Because it could be `None` you always have
-to check for that case if you access it.
-
-
-Using a decorator
-=================
-
-You can also use the `simplefilter` decorator from the `pygments.filter` module:
-
-.. sourcecode:: python
-
-    from pygments.util import get_bool_opt
-    from pygments.token import Name
-    from pygments.filter import simplefilter
-
-
-    @simplefilter
-    def uncolor(self, lexer, stream, options):
-        class_too = get_bool_opt(options, 'classtoo')
-        for ttype, value in stream:
-            if ttype is Name.Function or (class_too and
-                                          ttype is Name.Class):
-                ttype = Name
-            yield ttype, value
-
-The decorator automatically subclasses an internal filter class and uses the
-decorated function as a method for filtering.  (That's why there is a `self`
-argument that you probably won't end up using in the method.)

data/vendor/pygments-main/doc/docs/filters.rst

@@ -1,41 +0,0 @@
-.. -*- mode: rst -*-
-
-=======
-Filters
-=======
-
-.. versionadded:: 0.7
-
-You can filter token streams coming from lexers to improve or annotate the
-output. For example, you can highlight special words in comments, convert
-keywords to upper or lowercase to enforce a style guide etc.
-
-To apply a filter, you can use the `add_filter()` method of a lexer:
-
-.. sourcecode:: pycon
-
-    >>> from pygments.lexers import PythonLexer
-    >>> l = PythonLexer()
-    >>> # add a filter given by a string and options
-    >>> l.add_filter('codetagify', case='lower')
-    >>> l.filters
-    [<pygments.filters.CodeTagFilter object at 0xb785decc>]
-    >>> from pygments.filters import KeywordCaseFilter
-    >>> # or give an instance
-    >>> l.add_filter(KeywordCaseFilter(case='lower'))
-
-The `add_filter()` method takes keyword arguments which are forwarded to
-the constructor of the filter.
-
-To get a list of all registered filters by name, you can use the
-`get_all_filters()` function from the `pygments.filters` module that returns an
-iterable for all known filters.
-
-If you want to write your own filter, have a look at :doc:`Write your own filter
-<filterdevelopment>`.
-
-
-Builtin Filters
-===============
-
-.. pygmentsdoc:: filters

data/vendor/pygments-main/doc/docs/formatterdevelopment.rst

@@ -1,169 +0,0 @@
-.. -*- mode: rst -*-
-
-========================
-Write your own formatter
-========================
-
-As well as creating :doc:`your own lexer <lexerdevelopment>`, writing a new
-formatter for Pygments is easy and straightforward.
-
-A formatter is a class that is initialized with some keyword arguments (the
-formatter options) and that must provides a `format()` method.
-Additionally a formatter should provide a `get_style_defs()` method that
-returns the style definitions from the style in a form usable for the
-formatter's output format.
-
-
-Quickstart
-==========
-
-The most basic formatter shipped with Pygments is the `NullFormatter`. It just
-sends the value of a token to the output stream:
-
-.. sourcecode:: python
-
-    from pygments.formatter import Formatter
-
-    class NullFormatter(Formatter):
-        def format(self, tokensource, outfile):
-            for ttype, value in tokensource:
-                outfile.write(value)
-
-As you can see, the `format()` method is passed two parameters: `tokensource`
-and `outfile`. The first is an iterable of ``(token_type, value)`` tuples,
-the latter a file like object with a `write()` method.
-
-Because the formatter is that basic it doesn't overwrite the `get_style_defs()`
-method.
-
-
-Styles
-======
-
-Styles aren't instantiated but their metaclass provides some class functions
-so that you can access the style definitions easily.
-
-Styles are iterable and yield tuples in the form ``(ttype, d)`` where `ttype`
-is a token and `d` is a dict with the following keys:
-
-``'color'``
-    Hexadecimal color value (eg: ``'ff0000'`` for red) or `None` if not
-    defined.
-
-``'bold'``
-    `True` if the value should be bold
-
-``'italic'``
-    `True` if the value should be italic
-
-``'underline'``
-    `True` if the value should be underlined
-
-``'bgcolor'``
-    Hexadecimal color value for the background (eg: ``'eeeeeee'`` for light
-    gray) or `None` if not defined.
-
-``'border'``
-    Hexadecimal color value for the border (eg: ``'0000aa'`` for a dark
-    blue) or `None` for no border.
-
-Additional keys might appear in the future, formatters should ignore all keys
-they don't support.
-
-
-HTML 3.2 Formatter
-==================
-
-For an more complex example, let's implement a HTML 3.2 Formatter. We don't
-use CSS but inline markup (``<u>``, ``<font>``, etc). Because this isn't good
-style this formatter isn't in the standard library ;-)
-
-.. sourcecode:: python
-
-    from pygments.formatter import Formatter
-
-    class OldHtmlFormatter(Formatter):
-
-        def __init__(self, **options):
-            Formatter.__init__(self, **options)
-
-            # create a dict of (start, end) tuples that wrap the
-            # value of a token so that we can use it in the format
-            # method later
-            self.styles = {}
-
-            # we iterate over the `_styles` attribute of a style item
-            # that contains the parsed style values.
-            for token, style in self.style:
-                start = end = ''
-                # a style item is a tuple in the following form:
-                # colors are readily specified in hex: 'RRGGBB'
-                if style['color']:
-                    start += '<font color="#%s">' % style['color']
-                    end = '</font>' + end
-                if style['bold']:
-                    start += '<b>'
-                    end = '</b>' + end
-                if style['italic']:
-                    start += '<i>'
-                    end = '</i>' + end
-                if style['underline']:
-                    start += '<u>'
-                    end = '</u>' + end
-                self.styles[token] = (start, end)
-
-        def format(self, tokensource, outfile):
-            # lastval is a string we use for caching
-            # because it's possible that an lexer yields a number
-            # of consecutive tokens with the same token type.
-            # to minimize the size of the generated html markup we
-            # try to join the values of same-type tokens here
-            lastval = ''
-            lasttype = None
-
-            # wrap the whole output with <pre>
-            outfile.write('<pre>')
-
-            for ttype, value in tokensource:
-                # if the token type doesn't exist in the stylemap
-                # we try it with the parent of the token type
-                # eg: parent of Token.Literal.String.Double is
-                # Token.Literal.String
-                while ttype not in self.styles:
-                    ttype = ttype.parent
-                if ttype == lasttype:
-                    # the current token type is the same of the last
-                    # iteration. cache it
-                    lastval += value
-                else:
-                    # not the same token as last iteration, but we
-                    # have some data in the buffer. wrap it with the
-                    # defined style and write it to the output file
-                    if lastval:
-                        stylebegin, styleend = self.styles[lasttype]
-                        outfile.write(stylebegin + lastval + styleend)
-                    # set lastval/lasttype to current values
-                    lastval = value
-                    lasttype = ttype
-
-            # if something is left in the buffer, write it to the
-            # output file, then close the opened <pre> tag
-            if lastval:
-                stylebegin, styleend = self.styles[lasttype]
-                outfile.write(stylebegin + lastval + styleend)
-            outfile.write('</pre>\n')
-
-The comments should explain it. Again, this formatter doesn't override the
-`get_style_defs()` method. If we would have used CSS classes instead of
-inline HTML markup, we would need to generate the CSS first. For that
-purpose the `get_style_defs()` method exists:
-
-
-Generating Style Definitions
-============================
-
-Some formatters like the `LatexFormatter` and the `HtmlFormatter` don't
-output inline markup but reference either macros or css classes. Because
-the definitions of those are not part of the output, the `get_style_defs()`
-method exists. It is passed one parameter (if it's used and how it's used
-is up to the formatter) and has to return a string or ``None``.