[svn] Quite a few things:

- new pygmentize options, -F for filters and -H for detail help.
- an automatically-created formatter map
- better HTML formatter subclassing

8 files changed, 139 insertions, 61 deletions

diff --git a/pygments/formatters/__init__.py b/pygments/formatters/__init__.py
index 2fc55878..397f5027 100644
--- a/pygments/formatters/__init__.py
+++ b/pygments/formatters/__init__.py
@@ -9,79 +9,54 @@
     :license: BSD, see LICENSE for more details.
 """
 import os.path
-from pygments.formatters.html import HtmlFormatter
-from pygments.formatters.terminal import TerminalFormatter
-from pygments.formatters.latex import LatexFormatter
-from pygments.formatters.rtf import RtfFormatter
-from pygments.formatters.bbcode import BBCodeFormatter
-from pygments.formatters.other import NullFormatter, RawTokenFormatter
-from pygments.plugin import find_plugin_formatters
-
-
-def _doc_desc(obj):
-    if not obj.__doc__:
-        return ''
-    res = []
-    for line in obj.__doc__.strip().splitlines():
-        if line.strip():
-            res.append(" " + line.strip())
-        else:
-            break
-    return ''.join(res)
+import fnmatch
 
+from pygments.formatters._mapping import FORMATTERS
+from pygments.plugin import find_plugin_formatters
+from pygments.util import docstring_headline, ClassNotFound
 
-#: Map formatter classes to ``(longname, names, file extensions, descr)``.
-FORMATTERS = {
-    HtmlFormatter:        ('HTML', ('html',), ('.htm', '.html'),
-                           _doc_desc(HtmlFormatter)),
-    LatexFormatter:       ('LaTeX', ('latex', 'tex'), ('.tex',),
-                           _doc_desc(LatexFormatter)),
-    RtfFormatter:         ('RTF', ('rtf',), ('.rtf',),
-                           _doc_desc(RtfFormatter)),
-    TerminalFormatter:    ('Terminal', ('terminal', 'console'), (),
-                           _doc_desc(TerminalFormatter)),
-    BBCodeFormatter:      ('BBcode', ('bbcode', 'bb'), (),
-                           _doc_desc(BBCodeFormatter)),
-    RawTokenFormatter:    ('Raw tokens', ('raw', 'tokens'), ('.raw',),
-                           _doc_desc(RawTokenFormatter)),
-    NullFormatter:        ('Text only', ('text', 'null'), ('.txt',),
-                           _doc_desc(NullFormatter)),
-}
+ns = globals()
+for cls in FORMATTERS:
+    ns[cls.__name__] = cls
 
+__all__ = ['get_formatter_by_name', 'get_formatter_for_filename',
+           'get_all_formatters'] + [cls.__name__ for cls in FORMATTERS]
+           
 
-_formatter_cache = {}
+_formatter_alias_cache = {}
+_formatter_filename_cache = []
 
 def _init_formatter_cache():
-    if _formatter_cache:
+    if _formatter_alias_cache:
         return
-    for cls, info in FORMATTERS.iteritems():
-        for alias in info[1]:
-            _formatter_cache[alias] = cls
-        for ext in info[2]:
-            _formatter_cache["/"+ext] = cls
-    for name, cls in find_plugin_formatters():
-        _formatter_cache[name] = cls
+    for cls in get_all_formatters():
+        for alias in cls.aliases:
+            _formatter_alias_cache[alias] = cls
+        for fn in cls.filenames:
+            _formatter_filename_cache.append((fn, cls))
+
+
+def find_formatter_class(name):
+    _init_formatter_cache()
+    cls = _formatter_alias_cache.get(name, None)
+    return cls
 
 
 def get_formatter_by_name(name, **options):
     _init_formatter_cache()
-    cls = _formatter_cache.get(name, None)
+    cls = _formatter_alias_cache.get(name, None)
     if not cls:
-        raise ValueError("No formatter found for name %r" % name)
+        raise ClassNotFound("No formatter found for name %r" % name)
     return cls(**options)
 
 
 def get_formatter_for_filename(fn, **options):
     _init_formatter_cache()
-    # try by filename extension
-    cls = _formatter_cache.get("/"+os.path.splitext(fn)[1], None)
-    if cls:
-        return cls(**options)
-    # try by whole file name
-    cls = _formatter_cache.get("/"+os.path.basename(fn), None)
-    if not cls:
-        raise ValueError("No formatter found for file name %r" % fn)
-    return cls(**options)
+    fn = os.path.basename(fn)
+    for pattern, cls in _formatter_filename_cache:
+        if fnmatch.fnmatch(fn, pattern):
+            return cls(**options)
+    raise ClassNotFound("No formatter found for file name %r" % fn)
 
 
 def get_all_formatters():
diff --git a/pygments/formatters/_mapping.py b/pygments/formatters/_mapping.py
new file mode 100755
index 00000000..03e3c10f
--- /dev/null
+++ b/pygments/formatters/_mapping.py
@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+"""
+    pygments.formatters._mapping
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Formatter mapping defintions. This file is generated by itself. Everytime
+    you change something on a builtin formatter defintion, run this script from
+    the formatters folder to update it.
+
+    Do not alter the FORMATTERS dictionary by hand.
+
+    :copyright: 2006-2007 by Armin Ronacher, Georg Brandl.
+    :license: BSD, see LICENSE for more details.
+"""
+
+from pygments.util import docstring_headline
+
+# start
+from pygments.formatters.bbcode import BBCodeFormatter
+from pygments.formatters.html import HtmlFormatter
+from pygments.formatters.latex import LatexFormatter
+from pygments.formatters.other import NullFormatter
+from pygments.formatters.other import RawTokenFormatter
+from pygments.formatters.rtf import RtfFormatter
+from pygments.formatters.terminal import TerminalFormatter
+
+FORMATTERS = {
+    BBCodeFormatter: ('BBCode', ('bbcode', 'bb'), (), 'Format tokens with BBcodes. These formatting codes are used by many bulletin boards, so you can highlight your sourcecode with pygments before posting it there.'),
+    HtmlFormatter: ('HTML', ('html',), ('*.html', '*.htm'), "Format tokens as HTML 4 ``<span>`` tags within a ``<pre>`` tag, wrapped in a ``<div>`` tag. The ``<div>``'s CSS class can be set by the `cssclass` option."),
+    LatexFormatter: ('LaTeX', ('latex', 'tex'), ('*.tex',), 'Format tokens as LaTeX code. This needs the `fancyvrb` and `color` standard packages.'),
+    NullFormatter: ('Text only', ('text', 'null'), ('*.txt',), 'Output the text unchanged without any formatting.'),
+    RawTokenFormatter: ('Raw tokens', ('raw', 'tokens'), ('*.raw',), 'Format tokens as a raw representation for storing token streams.'),
+    RtfFormatter: ('RTF', ('rtf',), ('*.rtf',), 'Format tokens as RTF markup. This formatter automatically outputs full RTF documents with color information and other useful stuff. Perfect for Copy and Paste into Microsoft\xc2\xae Word\xc2\xae documents.'),
+    TerminalFormatter: ('Terminal', ('terminal', 'console'), (), 'Format tokens with ANSI color sequences, for output in a text console. Color sequences are terminated at newlines, so that paging the output works correctly.')
+}
+
+if __name__ == '__main__':
+    import sys
+    import os
+
+    # lookup formatters
+    found_formatters = []
+    imports = []
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
+    for filename in os.listdir('.'):
+        if filename.endswith('.py') and not filename.startswith('_'):
+            module_name = 'pygments.formatters.%s' % filename[:-3]
+            print module_name
+            module = __import__(module_name, None, None, [''])
+            for formatter_name in module.__all__:
+                imports.append((module_name, formatter_name))
+                formatter = getattr(module, formatter_name)
+                found_formatters.append(
+                    '%s: %r' % (formatter_name,
+                                (formatter.name,
+                                 tuple(formatter.aliases),
+                                 tuple(formatter.filenames),
+                                 docstring_headline(formatter))))
+    # sort them, that should make the diff files for svn smaller
+    found_formatters.sort()
+    imports.sort()
+
+    # extract useful sourcecode from this file
+    f = file(__file__)
+    try:
+        content = f.read()
+    finally:
+        f.close()
+    header = content[:content.find('# start')]
+    footer = content[content.find("if __name__ == '__main__':"):]
+
+    # write new file
+    f = file(__file__, 'w')
+    f.write(header)
+    f.write('# start\n')
+    f.write('\n'.join(['from %s import %s' % imp for imp in imports]))
+    f.write('\n\n')
+    f.write('FORMATTERS = {\n    %s\n}\n\n' % ',\n    '.join(found_formatters))
+    f.write(footer)
+    f.close()
diff --git a/pygments/formatters/bbcode.py b/pygments/formatters/bbcode.py
index 57112d77..0496b463 100644
--- a/pygments/formatters/bbcode.py
+++ b/pygments/formatters/bbcode.py
@@ -18,7 +18,7 @@ __all__ = ['BBCodeFormatter']
 
 class BBCodeFormatter(Formatter):
     """
-    Formats tokens with BBcodes. These formatting codes are used by many
+    Format tokens with BBcodes. These formatting codes are used by many
     bulletin boards, so you can highlight your sourcecode with pygments before
     posting it there.
 
@@ -41,6 +41,9 @@ class BBCodeFormatter(Formatter):
         If set to true, add a tag to show the code with a monospace font
         (default: ``false``).
     """
+    name = 'BBCode'
+    aliases = ['bbcode', 'bb']
+    filenames = []
 
     def __init__(self, **options):
         Formatter.__init__(self, **options)
diff --git a/pygments/formatters/html.py b/pygments/formatters/html.py
index d5e9c3f7..01a9edf9 100644
--- a/pygments/formatters/html.py
+++ b/pygments/formatters/html.py
@@ -99,7 +99,7 @@ td.linenos { background-color: #f0f0f0; padding-right: 10px; }
 
 
 class HtmlFormatter(Formatter):
-    """
+    r"""
     Format tokens as HTML 4 ``<span>`` tags within a ``<pre>`` tag, wrapped
     in a ``<div>`` tag. The ``<div>``'s CSS class can be set by the `cssclass`
     option.
@@ -254,6 +254,10 @@ class HtmlFormatter(Formatter):
     and/or "full document" wrappers if the respective options are set.
     """
 
+    name = 'HTML'
+    aliases = ['html']
+    filenames = ['*.html', '*.htm']
+
     def __init__(self, **options):
         Formatter.__init__(self, **options)
         self.nowrap = get_bool_opt(options, 'nowrap', False)
diff --git a/pygments/formatters/latex.py b/pygments/formatters/latex.py
index 22256625..a1e35c75 100644
--- a/pygments/formatters/latex.py
+++ b/pygments/formatters/latex.py
@@ -90,6 +90,9 @@ class LatexFormatter(Formatter):
         using this prefix and some letters (default: ``'C'``).
         *New in Pygments 0.7.*
     """
+    name = 'LaTeX'
+    aliases = ['latex', 'tex']
+    filenames = ['*.tex']
 
     def __init__(self, **options):
         Formatter.__init__(self, **options)
diff --git a/pygments/formatters/other.py b/pygments/formatters/other.py
index 6b70238e..d83c77ea 100644
--- a/pygments/formatters/other.py
+++ b/pygments/formatters/other.py
@@ -19,6 +19,10 @@ class NullFormatter(Formatter):
     """
     Output the text unchanged without any formatting.
     """
+    name = 'Text only'
+    aliases = ['text', 'null']
+    filenames = ['*.txt']
+    
     def format(self, tokensource, outfile):
         enc = self.encoding
         for ttype, value in tokensource:
@@ -30,7 +34,7 @@ class NullFormatter(Formatter):
 
 class RawTokenFormatter(Formatter):
     r"""
-    Formats tokens as a raw representation for storing token streams.
+    Format tokens as a raw representation for storing token streams.
 
     The format is ``tokentype<TAB>repr(tokenstring)\n``. The output can later
     be converted to a token stream with the `RawTokenLexer`, described in the
@@ -42,6 +46,9 @@ class RawTokenFormatter(Formatter):
         If set to ``'gz'`` or ``'bz2'``, compress the output with the given
         compression algorithm after encoding (default: ``''``).
     """
+    name = 'Raw tokens'
+    aliases = ['raw', 'tokens']
+    filenames = ['*.raw']
 
     unicodeoutput = False
 
diff --git a/pygments/formatters/rtf.py b/pygments/formatters/rtf.py
index c4078dd8..74538d0a 100644
--- a/pygments/formatters/rtf.py
+++ b/pygments/formatters/rtf.py
@@ -17,7 +17,7 @@ __all__ = ['RtfFormatter']
 
 class RtfFormatter(Formatter):
     """
-    Formats tokens as RTF markup. This formatter automatically outputs full RTF
+    Format tokens as RTF markup. This formatter automatically outputs full RTF
     documents with color information and other useful stuff. Perfect for Copy and
     Paste into Microsoft® Word® documents.
 
@@ -29,6 +29,9 @@ class RtfFormatter(Formatter):
         The used font famliy, for example ``Bitstream Vera Sans``. Defaults to
         some generic font which is supposed to have fixed width.
     """
+    name = 'RTF'
+    aliases = ['rtf']
+    filenames = ['*.rtf']
 
     unicodeoutput = False
 
diff --git a/pygments/formatters/terminal.py b/pygments/formatters/terminal.py
index fa030d86..cad37c7d 100644
--- a/pygments/formatters/terminal.py
+++ b/pygments/formatters/terminal.py
@@ -52,7 +52,7 @@ TERMINAL_COLORS = {
 
 class TerminalFormatter(Formatter):
     r"""
-    Formats tokens with ANSI color sequences, for output in a text console.
+    Format tokens with ANSI color sequences, for output in a text console.
     Color sequences are terminated at newlines, so that paging the output
     works correctly.
 
@@ -69,6 +69,9 @@ class TerminalFormatter(Formatter):
         A dictionary mapping token types to (lightbg, darkbg) color names or
         ``None`` (default: ``None`` = use builtin colorscheme).
     """
+    name = 'Terminal'
+    aliases = ['terminal', 'console']
+    filenames = []
 
     def __init__(self, **options):
         Formatter.__init__(self, **options)