diff options
Diffstat (limited to 'pygments/formatters/html.py')
| -rw-r--r-- | pygments/formatters/html.py | 75 |
1 files changed, 73 insertions, 2 deletions
diff --git a/pygments/formatters/html.py b/pygments/formatters/html.py index 85a16ff8..06096930 100644 --- a/pygments/formatters/html.py +++ b/pygments/formatters/html.py @@ -5,18 +5,23 @@ Formatter for HTML output. - :copyright: Copyright 2006-2012 by the Pygments team, see AUTHORS. + :copyright: Copyright 2006-2013 by the Pygments team, see AUTHORS. :license: BSD, see LICENSE for details. """ import os import sys +import os.path import StringIO from pygments.formatter import Formatter from pygments.token import Token, Text, STANDARD_TYPES from pygments.util import get_bool_opt, get_int_opt, get_list_opt, bytes +try: + import ctags +except ImportError: + ctags = None __all__ = ['HtmlFormatter'] @@ -141,6 +146,12 @@ class HtmlFormatter(Formatter): the style definitions inside a ``<style>`` tag, or in a separate file if the `cssfile` option is given. + When `tagsfile` is set to the path of a ctags index file, it is used to + generate hyperlinks from names to their definition. You must enable + `anchorlines` and run ctags with the `-n` option for this to work. The + `python-ctags` module from PyPI must be installed to use this feature; + otherwise a `RuntimeError` will be raised. + The `get_style_defs(arg='')` method of a `HtmlFormatter` returns a string containing CSS rules for the CSS classes used by the formatter. The argument `arg` can be used to specify additional CSS selectors that @@ -282,10 +293,27 @@ class HtmlFormatter(Formatter): output line in an anchor tag with a ``name`` of ``foo-linenumber``. This allows easy linking to certain lines. *New in Pygments 0.9.* + `linespans` + If set to a nonempty string, e.g. ``foo``, the formatter will wrap each + output line in a span tag with an ``id`` of ``foo-linenumber``. + This allows easy access to lines via javascript. *New in Pygments 1.6.* + `anchorlinenos` If set to `True`, will wrap line numbers in <a> tags. Used in combination with `linenos` and `lineanchors`. + `tagsfile` + If set to the path of a ctags file, wrap names in anchor tags that + link to their definitions. `lineanchors` should be used, and the + tags file should specify line numbers (see the `-n` option to ctags). + *New in Pygments 1.6.* + + `tagurlformat` + A string formatting pattern used to generate links to ctags definitions. + Available variables are `%(path)s`, `%(fname)s` and `%(fext)s`. + Defaults to an empty string, resulting in just `#prefix-number` links. + *New in Pygments 1.6.* + **Subclassing the HTML formatter** @@ -351,6 +379,14 @@ class HtmlFormatter(Formatter): self.prestyles = self._decodeifneeded(options.get('prestyles', '')) self.cssfile = self._decodeifneeded(options.get('cssfile', '')) self.noclobber_cssfile = get_bool_opt(options, 'noclobber_cssfile', False) + self.tagsfile = self._decodeifneeded(options.get('tagsfile', '')) + self.tagurlformat = self._decodeifneeded(options.get('tagurlformat', '')) + + if self.tagsfile: + if not ctags: + raise RuntimeError('The "ctags" package must to be installed ' + 'to be able to use the "tagsfile" feature.') + self._ctags = ctags.CTags(self.tagsfile) linenos = options.get('linenos', False) if linenos == 'inline': @@ -366,6 +402,7 @@ class HtmlFormatter(Formatter): self.nobackground = get_bool_opt(options, 'nobackground', False) self.lineseparator = options.get('lineseparator', '\n') self.lineanchors = options.get('lineanchors', '') + self.linespans = options.get('linespans', '') self.anchorlinenos = options.get('anchorlinenos', False) self.hl_lines = set() for lineno in get_list_opt(options, 'hl_lines', []): @@ -596,7 +633,8 @@ class HtmlFormatter(Formatter): def _wrap_lineanchors(self, inner): s = self.lineanchors - i = self.linenostart - 1 # subtract 1 since we have to increment i *before* yielding + i = self.linenostart - 1 # subtract 1 since we have to increment i + # *before* yielding for t, line in inner: if t: i += 1 @@ -604,6 +642,16 @@ class HtmlFormatter(Formatter): else: yield 0, line + def _wrap_linespans(self, inner): + s = self.linespans + i = self.linenostart - 1 + for t, line in inner: + if t: + i += 1 + yield 1, '<span id="%s-%d">%s</span>' % (s, i, line) + else: + yield 0, line + def _wrap_div(self, inner): style = [] if (self.noclasses and not self.nobackground and @@ -643,6 +691,7 @@ class HtmlFormatter(Formatter): getcls = self.ttype2class.get c2s = self.class2style escape_table = _escape_html_table + tagsfile = self.tagsfile lspan = '' line = '' @@ -659,6 +708,19 @@ class HtmlFormatter(Formatter): parts = value.translate(escape_table).split('\n') + if tagsfile and ttype in Token.Name: + filename, linenumber = self._lookup_ctag(value) + if linenumber: + base, filename = os.path.split(filename) + if base: + base += '/' + filename, extension = os.path.splitext(filename) + url = self.tagurlformat % {'path': base, 'fname': filename, + 'fext': extension} + parts[0] = "<a href=\"%s#%s-%d\">%s" % \ + (url, self.lineanchors, linenumber, parts[0]) + parts[-1] = parts[-1] + "</a>" + # for all but the last line for part in parts[:-1]: if line: @@ -688,6 +750,13 @@ class HtmlFormatter(Formatter): if line: yield 1, line + (lspan and '</span>') + lsep + def _lookup_ctag(self, token): + entry = ctags.TagEntry() + if self._ctags.find(entry, token, 0): + return entry['file'], entry['lineNumber'] + else: + return None, None + def _highlight_lines(self, tokensource): """ Highlighted the lines specified in the `hl_lines` option by @@ -740,6 +809,8 @@ class HtmlFormatter(Formatter): source = self._wrap_inlinelinenos(source) if self.lineanchors: source = self._wrap_lineanchors(source) + if self.linespans: + source = self._wrap_linespans(source) source = self.wrap(source, outfile) if self.linenos == 1: source = self._wrap_tablelinenos(source) |