pygments.rb-jruby 0.5.4

data/vendor/pygments-main/docs/pygmentize.1

@@ -0,0 +1,94 @@
+.TH PYGMENTIZE 1 "February 15, 2007"
+
+.SH NAME
+pygmentize \- highlights the input file
+
+.SH SYNOPSIS
+.B \fBpygmentize\fP
+.RI  [-l\ \fI<lexer>\fP]\ [-F\ \fI<filter>\fP[:\fI<options>\fP]]\ [-f\ \fI<formatter>\fP]
+.RI  [-O\ \fI<options>\fP]\ [-P\ \fI<option=value>\fP]\ [-o\ \fI<outfile>\fP]\ [\fI<infile>\fP]
+.br
+.B \fBpygmentize\fP
+.RI -S\ \fI<style>\fP\ -f\ \fI<formatter>\fP\ [-a\ \fI<arg>\fP]\ [-O\ \fI<options>\fP]\ [-P\ \fI<option=value>\fP]
+.br
+.B \fBpygmentize\fP
+.RI -L\ [\fI<which>\fP\ ...]
+.br
+.B \fBpygmentize\fP
+.RI -H\ \fI<type>\fP\ \fI<name>\fP
+.br
+.B \fBpygmentize\fP
+.RI -h\ |\ -V
+
+.SH DESCRIPTION
+Pygments is a generic syntax highlighter for general use in all kinds
+of software such as forum systems, wikis or other applications that need to
+prettify source code.
+.PP
+Its highlights are:
+  * a wide range of common languages and markup formats is supported
+  * special attention is paid to details, increasing quality by a fair amount
+  * support for new languages and formats are added easily
+  * a number of output formats, presently HTML, LaTeX and ANSI sequences
+  * it is usable as a command-line tool and as a library
+  * ... and it highlights even Brainfuck!
+.PP
+\fBpygmentize\fP is a command that uses Pygments to highlight the input file and
+write the result to \fI<outfile>\fP. If no \fI<infile>\fP is given, stdin is used.
+.SH OPTIONS
+A summary of options is included below.
+.TP
+.B \-l \fI<lexer>\fP
+Set the lexer name. If not given, the lexer is guessed from the extension of the
+input file name (this obviously doesn't work if the input is stdin).
+.TP
+.B \-F \fI<filter>\fP[:\fI<options>\fP]
+Add a filter to the token stream. You can give options in the same way as for
+-O after a colon (note: there must not be spaces around the colon).
+This option can be given multiple times.
+.TP
+.B \-f \fI<formatter>\fP
+Set the formatter name. If not given, it will be guessed from the extension of
+the output file name. If no output file is given, the terminal formatter will be
+used by default.
+.TP
+.B \-o \fI<outfile>\fP
+Set output file. If not given, stdout is used.
+.TP
+.B \-O \fI<options>\fP
+With this option, you can give the lexer and formatter a comma-separated list of
+options, e.g. "-O bg=light,python=cool". Which options are valid for which
+lexers and formatters can be found in the documentation.
+This option can be given multiple times.
+.TP
+.B \-P \fI<option=value>\fP
+This option adds lexer and formatter options like the -O option, but
+you can only give one option per -P. That way, the option value may contain
+commas and equals signs, which it can't with -O.
+.TP
+.B \-S \fI<style>\fP
+Print out style definitions for style \fI<style>\fP and for formatter \fI<formatter>\fP.
+The meaning of the argument given by
+.B \-a \fI<arg>\fP
+is formatter dependent and can be found in the documentation.
+.TP
+.B \-L [\fI<which>\fP ...]
+List lexers, formatters, styles or filters. Set \fI<which>\fP to the thing you want
+to list (e.g. "styles"), or omit it to list everything.
+.TP
+.B \-H \fI<type>\fP \fI<name>\fP
+Print detailed help for the object \fI<name>\fP of type \fI<type>\fP, where \fI<type>\fP is one
+of "lexer", "formatter" or "filter".
+.TP
+.B \-h
+Show help screen.
+.TP
+.B \-V
+Show version of the Pygments package.
+.SH SEE ALSO
+/usr/share/doc/python-pygments/index.html
+.SH AUTHOR
+pygmentize was written by Georg Brandl <g.brandl@gmx.net>.
+.PP
+This manual page was written by Piotr Ozarowski <ozarow@gmail.com>,
+for the Debian project (but may be used by others).

data/vendor/pygments-main/docs/src/api.txt

@@ -0,0 +1,270 @@
+.. -*- mode: rst -*-
+
+=====================
+The full Pygments API
+=====================
+
+This page describes the Pygments API.
+
+High-level API
+==============
+
+Functions from the `pygments` module:
+
+def `lex(code, lexer):`
+    Lex `code` with the `lexer` (must be a `Lexer` instance)
+    and return an iterable of tokens. Currently, this only calls
+    `lexer.get_tokens()`.
+
+def `format(tokens, formatter, outfile=None):`
+    Format a token stream (iterable of tokens) `tokens` with the
+    `formatter` (must be a `Formatter` instance). The result is
+    written to `outfile`, or if that is ``None``, returned as a
+    string.
+
+def `highlight(code, lexer, formatter, outfile=None):`
+    This is the most high-level highlighting function.
+    It combines `lex` and `format` in one function.
+
+
+Functions from `pygments.lexers`:
+
+def `get_lexer_by_name(alias, **options):`
+    Return an instance of a `Lexer` subclass that has `alias` in its
+    aliases list. The lexer is given the `options` at its
+    instantiation.
+
+    Will raise `pygments.util.ClassNotFound` if no lexer with that alias is
+    found.
+
+def `get_lexer_for_filename(fn, **options):`
+    Return a `Lexer` subclass instance that has a filename pattern
+    matching `fn`. The lexer is given the `options` at its
+    instantiation.
+
+    Will raise `pygments.util.ClassNotFound` if no lexer for that filename is
+    found.
+
+def `get_lexer_for_mimetype(mime, **options):`
+    Return a `Lexer` subclass instance that has `mime` in its mimetype
+    list. The lexer is given the `options` at its instantiation.
+
+    Will raise `pygments.util.ClassNotFound` if not lexer for that mimetype is
+    found.
+
+def `guess_lexer(text, **options):`
+    Return a `Lexer` subclass instance that's guessed from the text
+    in `text`. For that, the `analyse_text()` method of every known
+    lexer class is called with the text as argument, and the lexer
+    which returned the highest value will be instantiated and returned.
+
+    `pygments.util.ClassNotFound` is raised if no lexer thinks it can handle the
+    content.
+
+def `guess_lexer_for_filename(filename, text, **options):`
+    As `guess_lexer()`, but only lexers which have a pattern in `filenames`
+    or `alias_filenames` that matches `filename` are taken into consideration.
+
+    `pygments.util.ClassNotFound` is raised if no lexer thinks it can handle the
+    content.
+
+def `get_all_lexers():`
+    Return an iterable over all registered lexers, yielding tuples in the
+    format::
+
+    	(longname, tuple of aliases, tuple of filename patterns, tuple of mimetypes)
+
+    *New in Pygments 0.6.*
+
+
+Functions from `pygments.formatters`:
+
+def `get_formatter_by_name(alias, **options):`
+    Return an instance of a `Formatter` subclass that has `alias` in its
+    aliases list. The formatter is given the `options` at its
+    instantiation.
+
+    Will raise `pygments.util.ClassNotFound` if no formatter with that alias is
+    found.
+
+def `get_formatter_for_filename(fn, **options):`
+    Return a `Formatter` subclass instance that has a filename pattern
+    matching `fn`. The formatter is given the `options` at its
+    instantiation.
+
+    Will raise `pygments.util.ClassNotFound` if no formatter for that filename
+    is found.
+
+
+Functions from `pygments.styles`:
+
+def `get_style_by_name(name):`
+    Return a style class by its short name. The names of the builtin styles
+    are listed in `pygments.styles.STYLE_MAP`.
+
+    Will raise `pygments.util.ClassNotFound` if no style of that name is found.
+
+def `get_all_styles():`
+    Return an iterable over all registered styles, yielding their names.
+
+    *New in Pygments 0.6.*
+
+
+Lexers
+======
+
+A lexer (derived from `pygments.lexer.Lexer`) has the following functions:
+
+def `__init__(self, **options):`
+    The constructor. Takes a \*\*keywords dictionary of options.
+    Every subclass must first process its own options and then call
+    the `Lexer` constructor, since it processes the `stripnl`,
+    `stripall` and `tabsize` options.
+
+    An example looks like this:
+
+    .. sourcecode:: python
+
+        def __init__(self, **options):
+            self.compress = options.get('compress', '')
+            Lexer.__init__(self, **options)
+
+    As these options must all be specifiable as strings (due to the
+    command line usage), there are various utility functions
+    available to help with that, see `Option processing`_.
+
+def `get_tokens(self, text):`
+    This method is the basic interface of a lexer. It is called by
+    the `highlight()` function. It must process the text and return an
+    iterable of ``(tokentype, value)`` pairs from `text`.
+
+    Normally, you don't need to override this method. The default
+    implementation processes the `stripnl`, `stripall` and `tabsize`
+    options and then yields all tokens from `get_tokens_unprocessed()`,
+    with the ``index`` dropped.
+
+def `get_tokens_unprocessed(self, text):`
+    This method should process the text and return an iterable of
+    ``(index, tokentype, value)`` tuples where ``index`` is the starting
+    position of the token within the input text.
+
+    This method must be overridden by subclasses.
+
+def `analyse_text(text):`
+    A static method which is called for lexer guessing. It should analyse
+    the text and return a float in the range from ``0.0`` to ``1.0``.
+    If it returns ``0.0``, the lexer will not be selected as the most
+    probable one, if it returns ``1.0``, it will be selected immediately.
+
+For a list of known tokens have a look at the `Tokens`_ page.
+
+A lexer also can have the following attributes (in fact, they are mandatory
+except `alias_filenames`) that are used by the builtin lookup mechanism.
+
+`name`
+    Full name for the lexer, in human-readable form.
+
+`aliases`
+    A list of short, unique identifiers that can be used to lookup
+    the lexer from a list, e.g. using `get_lexer_by_name()`.
+
+`filenames`
+    A list of `fnmatch` patterns that match filenames which contain
+    content for this lexer. The patterns in this list should be unique among
+    all lexers.
+
+`alias_filenames`
+    A list of `fnmatch` patterns that match filenames which may or may not
+    contain content for this lexer. This list is used by the
+    `guess_lexer_for_filename()` function, to determine which lexers are
+    then included in guessing the correct one. That means that e.g. every
+    lexer for HTML and a template language should include ``\*.html`` in
+    this list.
+
+`mimetypes`
+    A list of MIME types for content that can be lexed with this
+    lexer.
+
+
+.. _Tokens: tokens.txt
+
+
+Formatters
+==========
+
+A formatter (derived from `pygments.formatter.Formatter`) has the following
+functions:
+
+def `__init__(self, **options):`
+    As with lexers, this constructor processes options and then must call
+    the base class `__init__`.
+
+    The `Formatter` class recognizes the options `style`, `full` and
+    `title`. It is up to the formatter class whether it uses them.
+
+def `get_style_defs(self, arg=''):`
+    This method must return statements or declarations suitable to define
+    the current style for subsequent highlighted text (e.g. CSS classes
+    in the `HTMLFormatter`).
+
+    The optional argument `arg` can be used to modify the generation and
+    is formatter dependent (it is standardized because it can be given on
+    the command line).
+
+    This method is called by the ``-S`` `command-line option`_, the `arg`
+    is then given by the ``-a`` option.
+
+def `format(self, tokensource, outfile):`
+    This method must format the tokens from the `tokensource` iterable and
+    write the formatted version to the file object `outfile`.
+
+    Formatter options can control how exactly the tokens are converted.
+
+.. _command-line option: cmdline.txt
+
+A formatter must have the following attributes that are used by the
+builtin lookup mechanism. (*New in Pygments 0.7.*)
+
+`name`
+    Full name for the formatter, in human-readable form.
+
+`aliases`
+    A list of short, unique identifiers that can be used to lookup
+    the formatter from a list, e.g. using `get_formatter_by_name()`.
+
+`filenames`
+    A list of `fnmatch` patterns that match filenames for which this formatter
+    can produce output. The patterns in this list should be unique among
+    all formatters.
+
+
+Option processing
+=================
+
+The `pygments.util` module has some utility functions usable for option
+processing:
+
+class `OptionError`
+    This exception will be raised by all option processing functions if
+    the type or value of the argument is not correct.
+
+def `get_bool_opt(options, optname, default=None):`
+    Interpret the key `optname` from the dictionary `options`
+    as a boolean and return it. Return `default` if `optname`
+    is not in `options`.
+
+    The valid string values for ``True`` are ``1``, ``yes``,
+    ``true`` and ``on``, the ones for ``False`` are ``0``,
+    ``no``, ``false`` and ``off`` (matched case-insensitively).
+
+def `get_int_opt(options, optname, default=None):`
+    As `get_bool_opt`, but interpret the value as an integer.
+
+def `get_list_opt(options, optname, default=None):`
+    If the key `optname` from the dictionary `options` is a string,
+    split it at whitespace and return it. If it is already a list
+    or a tuple, it is returned as a list.
+
+def `get_choice_opt(options, optname, allowed, default=None):`
+    If the key `optname` from the dictionary is not in the sequence
+    `allowed`, raise an error, otherwise return it. *New in Pygments 0.8.*

data/vendor/pygments-main/docs/src/authors.txt

@@ -0,0 +1,5 @@
+=======
+Authors
+=======
+
+[authors]

data/vendor/pygments-main/docs/src/changelog.txt

@@ -0,0 +1,5 @@
+=========
+Changelog
+=========
+
+[changelog]

data/vendor/pygments-main/docs/src/cmdline.txt

@@ -0,0 +1,147 @@
+.. -*- mode: rst -*-
+
+======================
+Command Line Interface
+======================
+
+You can use Pygments from the shell, provided you installed the `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
+`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 `a particular formatter`_, look for
+the `arg` argument for the formatter's `get_style_defs()` method.
+
+
+Getting lexer names
+-------------------
+
+*New in Pygments 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.
+
+
+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
+-------------------
+
+*New in Pygments 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 don't give an encoding and have given an output file, the default
+  encoding for lexer and formatter is ``latin1`` (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`).
+
+
+.. _a particular formatter: formatters.txt