File: formatters.html

package info (click to toggle)
pygments 0.10-1
links: PTS, VCS
area: main
in suites: lenny
size: 3,748 kB
ctags: 3,621
sloc: python: 15,151; ansic: 3,408; pascal: 2,750; sh: 2,244; ruby: 2,130; lisp: 1,839; xml: 1,797; java: 1,742; cpp: 1,549; ml: 831; haskell: 721; csh: 681; f90: 451; perl: 375; php: 252; cs: 225; erlang: 104; makefile: 84; jsp: 21
file content (807 lines) | stat: -rw-r--r-- 43,917 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <title>Available formatters &mdash; Pygments</title>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">
  <style type="text/css">
    body {
    background-color: #f2f2f2;
    margin: 0;
    padding: 0;
    font-family: 'Georgia', serif;
    color: #111;
}

#content {
    background-color: white;
    padding: 20px;
    margin: 20px auto 20px auto;
    max-width: 800px;
    border: 4px solid #ddd;
}

h1 {
    font-weight: normal;
    font-size: 40px;
    color: #09839A;
}

h2 {
    font-weight: normal;
    font-size: 30px;
    color: #C73F00;
}

h1.heading {
    margin: 0 0 30px 0;
}

h2.subheading {
    margin: -30px 0 0 45px;
}

h3 {
    margin-top: 30px;
}

table.docutils {
    border-collapse: collapse;
    border: 2px solid #aaa;
    margin: 0.5em 1.5em 0.5em 1.5em;
}

table.docutils td {
    padding: 2px;
    border: 1px solid #ddd;
}

p, li, dd, dt, blockquote {
    font-size: 15px;
    color: #333;
}

p {
    line-height: 150%;
    margin-bottom: 0;
    margin-top: 10px;
}

hr {
    border-top: 1px solid #ccc;
    border-bottom: 0;
    border-right: 0;
    border-left: 0;
    margin-bottom: 10px;
    margin-top: 20px;
}

dl {
    margin-left: 10px;
}

li, dt {
    margin-top: 5px;
}

dt {
    font-weight: bold;
}

th {
    text-align: left;
}

a {
    color: #990000;
}

a:hover {
    color: #c73f00;
}

pre {
    background-color: #f9f9f9;
    border-top: 1px solid #ccc;
    border-bottom: 1px solid #ccc;
    padding: 5px;
    font-size: 13px;
    font-family: Bitstream Vera Sans Mono,monospace;
}

tt {
    font-size: 13px;
    font-family: Bitstream Vera Sans Mono,monospace;
    color: black;
    padding: 1px 2px 1px 2px;
    background-color: #f0f0f0;
}

cite {
    /* abusing <cite>, it's generated by ReST for `x` */
    font-size: 13px;
    font-family: Bitstream Vera Sans Mono,monospace;
    font-weight: bold;
    font-style: normal;
}

#backlink {
    float: right;
    font-size: 11px;
    color: #888;
}

div.toc {
    margin: 0 0 10px 0;
}

div.toc h2 {
    font-size: 20px;
}
.syntax  { background: #ffffff; }
.syntax .c { color: #888888 } /* Comment */
.syntax .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.syntax .k { color: #008800; font-weight: bold } /* Keyword */
.syntax .cm { color: #888888 } /* Comment.Multiline */
.syntax .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.syntax .c1 { color: #888888 } /* Comment.Single */
.syntax .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.syntax .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.syntax .ge { font-style: italic } /* Generic.Emph */
.syntax .gr { color: #aa0000 } /* Generic.Error */
.syntax .gh { color: #303030 } /* Generic.Heading */
.syntax .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.syntax .go { color: #888888 } /* Generic.Output */
.syntax .gp { color: #555555 } /* Generic.Prompt */
.syntax .gs { font-weight: bold } /* Generic.Strong */
.syntax .gu { color: #606060 } /* Generic.Subheading */
.syntax .gt { color: #aa0000 } /* Generic.Traceback */
.syntax .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.syntax .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.syntax .kp { color: #008800 } /* Keyword.Pseudo */
.syntax .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.syntax .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.syntax .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.syntax .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.syntax .na { color: #336699 } /* Name.Attribute */
.syntax .nb { color: #003388 } /* Name.Builtin */
.syntax .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.syntax .no { color: #003366; font-weight: bold } /* Name.Constant */
.syntax .nd { color: #555555 } /* Name.Decorator */
.syntax .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.syntax .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.syntax .nl { color: #336699; font-style: italic } /* Name.Label */
.syntax .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.syntax .py { color: #336699; font-weight: bold } /* Name.Property */
.syntax .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.syntax .nv { color: #336699 } /* Name.Variable */
.syntax .ow { color: #008800 } /* Operator.Word */
.syntax .w { color: #bbbbbb } /* Text.Whitespace */
.syntax .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.syntax .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.syntax .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.syntax .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.syntax .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.syntax .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.syntax .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.syntax .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.syntax .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.syntax .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.syntax .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.syntax .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.syntax .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.syntax .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.syntax .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.syntax .bp { color: #003388 } /* Name.Builtin.Pseudo */
.syntax .vc { color: #336699 } /* Name.Variable.Class */
.syntax .vg { color: #dd7700 } /* Name.Variable.Global */
.syntax .vi { color: #3333bb } /* Name.Variable.Instance */
.syntax .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
  </style>
</head>
<body>
  <div id="content">
    <h1 class="heading">Pygments</h1>
    <h2 class="subheading">Available formatters</h2>
    
      <a id="backlink" href="index.html">&laquo; Back To Index</a>
    
    
      <div class="toc">
        <h2>Contents</h2>
        <ul class="contents">
        
          <li><a href="#common-options">Common options</a></li>
        
          <li><a href="#formatter-classes">Formatter classes</a></li>
        
        </ul>
      </div>
    
    <!-- -*- mode: rst -*- -->
<p>This page lists all builtin formatters.</p>
<div class="section">
<h3><a id="common-options" name="common-options">Common options</a></h3>
<p>All formatters support these options:</p>
<dl class="docutils">
<dt><cite>encoding</cite></dt>
<dd><p class="first"><em>New in Pygments 0.6.</em></p>
<p>If given, must be an encoding name (such as <tt class="docutils literal"><span class="pre">&quot;utf-8&quot;</span></tt>). This will
be used to convert the token strings (which are Unicode strings)
to byte strings in the output (default: <tt class="docutils literal"><span class="pre">None</span></tt>).
It will also be written in an encoding declaration suitable for the
document format if the <cite>full</cite> option is given (e.g. a <tt class="docutils literal"><span class="pre">meta</span>
<span class="pre">content-type</span></tt> directive in HTML or an invocation of the <cite>inputenc</cite>
package in LaTeX).</p>
<p class="last">If this is <tt class="docutils literal"><span class="pre">&quot;&quot;</span></tt> or <tt class="docutils literal"><span class="pre">None</span></tt>, Unicode strings will be written
to the output file, which most file-like objects do not support.
For example, <cite>pygments.highlight()</cite> will return a Unicode string if
called with no <cite>outfile</cite> argument and a formatter that has <cite>encoding</cite>
set to <tt class="docutils literal"><span class="pre">None</span></tt> because it uses a <cite>StringIO.StringIO</cite> object that
supports Unicode arguments to <cite>write()</cite>. Using a regular file object
wouldn't work.</p>
</dd>
<dt><cite>outencoding</cite></dt>
<dd><p class="first"><em>New in Pygments 0.7.</em></p>
<p class="last">When using Pygments from the command line, any <cite>encoding</cite> option given is
passed to the lexer and the formatter. This is sometimes not desirable,
for example if you want to set the input encoding to <tt class="docutils literal"><span class="pre">&quot;guess&quot;</span></tt>.
Therefore, <cite>outencoding</cite> has been introduced which overrides <cite>encoding</cite>
for the formatter if given.</p>
</dd>
</dl>
</div>
<div class="section">
<h3><a id="formatter-classes" name="formatter-classes">Formatter classes</a></h3>
<p>All these classes are importable from <cite>pygments.formatters</cite>.</p>
<div class="section">
<h4><a id="bbcodeformatter" name="bbcodeformatter"><cite>BBCodeFormatter</cite></a></h4>
<blockquote>
<p>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.</p>
<p>This formatter has no support for background colors and borders, as there
are no common BBcode tags for that.</p>
<p>Some board systems (e.g. phpBB) don't support colors in their [code] tag,
so you can't use the highlighting together with that tag.
Text in a [code] tag usually is shown with a monospace font (which this
formatter can do with the <tt class="docutils literal"><span class="pre">monofont</span></tt> option) and no spaces (which you
need for indentation) are removed.</p>
<p>Additional options accepted:</p>
<dl class="docutils">
<dt><cite>style</cite></dt>
<dd>The style to use, can be a string or a Style subclass (default:
<tt class="docutils literal"><span class="pre">'default'</span></tt>).</dd>
<dt><cite>codetag</cite></dt>
<dd>If set to true, put the output into <tt class="docutils literal"><span class="pre">[code]</span></tt> tags (default:
<tt class="docutils literal"><span class="pre">false</span></tt>)</dd>
<dt><cite>monofont</cite></dt>
<dd>If set to true, add a tag to show the code with a monospace font
(default: <tt class="docutils literal"><span class="pre">false</span></tt>).</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">bbcode, bb</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">None</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="htmlformatter" name="htmlformatter"><cite>HtmlFormatter</cite></a></h4>
<blockquote>
<p>Format tokens as HTML 4 <tt class="docutils literal"><span class="pre">&lt;span&gt;</span></tt> tags within a <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt> tag, wrapped
in a <tt class="docutils literal"><span class="pre">&lt;div&gt;</span></tt> tag. The <tt class="docutils literal"><span class="pre">&lt;div&gt;</span></tt>'s CSS class can be set by the <cite>cssclass</cite>
option.</p>
<p>If the <cite>linenos</cite> option is set to <tt class="docutils literal"><span class="pre">&quot;table&quot;</span></tt>, the <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt> is
additionally wrapped inside a <tt class="docutils literal"><span class="pre">&lt;table&gt;</span></tt> which has one row and two
cells: one containing the line numbers and one containing the code.
Example:</p>
<div class="syntax"><pre><span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">&quot;highlight&quot;</span> <span class="nt">&gt;</span>
<span class="nt">&lt;table&gt;&lt;tr&gt;</span>
  <span class="nt">&lt;td</span> <span class="na">class=</span><span class="s">&quot;linenos&quot;</span> <span class="na">title=</span><span class="s">&quot;click to toggle&quot;</span>
    <span class="na">onclick=</span><span class="s">&quot;with (this.firstChild.style)</span>
<span class="s">             { display = (display == &#39;&#39;) ? &#39;none&#39; : &#39;&#39; }&quot;</span><span class="nt">&gt;</span>
    <span class="nt">&lt;pre&gt;</span>1
    2<span class="nt">&lt;/pre&gt;</span>
  <span class="nt">&lt;/td&gt;</span>
  <span class="nt">&lt;td</span> <span class="na">class=</span><span class="s">&quot;code&quot;</span><span class="nt">&gt;</span>
    <span class="nt">&lt;pre&gt;&lt;span</span> <span class="na">class=</span><span class="s">&quot;Ke&quot;</span><span class="nt">&gt;</span>def <span class="nt">&lt;/span&gt;&lt;span</span> <span class="na">class=</span><span class="s">&quot;NaFu&quot;</span><span class="nt">&gt;</span>foo<span class="nt">&lt;/span&gt;</span>(bar):
      <span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">&quot;Ke&quot;</span><span class="nt">&gt;</span>pass<span class="nt">&lt;/span&gt;</span>
    <span class="nt">&lt;/pre&gt;</span>
  <span class="nt">&lt;/td&gt;</span>
<span class="nt">&lt;/tr&gt;&lt;/table&gt;&lt;/div&gt;</span>
</pre></div>
<p>(whitespace added to improve clarity).</p>
<p>Wrapping can be disabled using the <cite>nowrap</cite> option.</p>
<p>With the <cite>full</cite> option, a complete HTML 4 document is output, including
the style definitions inside a <tt class="docutils literal"><span class="pre">&lt;style&gt;</span></tt> tag, or in a separate file if
the <cite>cssfile</cite> option is given.</p>
<p>The <cite>get_style_defs(arg='')</cite> method of a <cite>HtmlFormatter</cite> returns a string
containing CSS rules for the CSS classes used by the formatter. The
argument <cite>arg</cite> can be used to specify additional CSS selectors that
are prepended to the classes. A call <cite>fmter.get_style_defs('td .code')</cite>
would result in the following CSS classes:</p>
<div class="syntax"><pre><span class="nt">td</span> <span class="nc">.code</span> <span class="nc">.kw</span> <span class="p">{</span> <span class="k">font-weight</span><span class="o">:</span> <span class="k">bold</span><span class="p">;</span> <span class="k">color</span><span class="o">:</span> <span class="m">#00FF00</span> <span class="p">}</span>
<span class="nt">td</span> <span class="nc">.code</span> <span class="nc">.cm</span> <span class="p">{</span> <span class="k">color</span><span class="o">:</span> <span class="m">#999999</span> <span class="p">}</span>
<span class="o">...</span>
</pre></div>
<p>If you have Pygments 0.6 or higher, you can also pass a list or tuple to the
<cite>get_style_defs()</cite> method to request multiple prefixes for the tokens:</p>
<div class="syntax"><pre><span class="n">formatter</span><span class="o">.</span><span class="n">get_style_defs</span><span class="p">([</span><span class="s">&#39;div.syntax pre&#39;</span><span class="p">,</span> <span class="s">&#39;pre.syntax&#39;</span><span class="p">])</span>
</pre></div>
<p>The output would then look like this:</p>
<div class="syntax"><pre><span class="nt">div</span><span class="nc">.syntax</span> <span class="nt">pre</span> <span class="nc">.kw</span><span class="o">,</span>
<span class="nt">pre</span><span class="nc">.syntax</span> <span class="nc">.kw</span> <span class="p">{</span> <span class="k">font-weight</span><span class="o">:</span> <span class="k">bold</span><span class="p">;</span> <span class="k">color</span><span class="o">:</span> <span class="m">#00FF00</span> <span class="p">}</span>
<span class="nt">div</span><span class="nc">.syntax</span> <span class="nt">pre</span> <span class="nc">.cm</span><span class="o">,</span>
<span class="nt">pre</span><span class="nc">.syntax</span> <span class="nc">.cm</span> <span class="p">{</span> <span class="k">color</span><span class="o">:</span> <span class="m">#999999</span> <span class="p">}</span>
<span class="o">...</span>
</pre></div>
<p>Additional options accepted:</p>
<dl class="docutils">
<dt><cite>nowrap</cite></dt>
<dd>If set to <tt class="docutils literal"><span class="pre">True</span></tt>, don't wrap the tokens at all, not even inside a <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt>
tag. This disables most other options (default: <tt class="docutils literal"><span class="pre">False</span></tt>).</dd>
<dt><cite>full</cite></dt>
<dd>Tells the formatter to output a &quot;full&quot; document, i.e. a complete
self-contained document (default: <tt class="docutils literal"><span class="pre">False</span></tt>).</dd>
<dt><cite>title</cite></dt>
<dd>If <cite>full</cite> is true, the title that should be used to caption the
document (default: <tt class="docutils literal"><span class="pre">''</span></tt>).</dd>
<dt><cite>style</cite></dt>
<dd>The style to use, can be a string or a Style subclass (default:
<tt class="docutils literal"><span class="pre">'default'</span></tt>).</dd>
<dt><cite>noclasses</cite></dt>
<dd>If set to true, token <tt class="docutils literal"><span class="pre">&lt;span&gt;</span></tt> tags will not use CSS classes, but
inline styles. This is not recommended for larger pieces of code since
it increases output size by quite a bit (default: <tt class="docutils literal"><span class="pre">False</span></tt>).</dd>
<dt><cite>classprefix</cite></dt>
<dd>Since the token types use relatively short class names, they may clash
with some of your own class names. In this case you can use the
<cite>classprefix</cite> option to give a string to prepend to all Pygments-generated
CSS class names for token types.
Note that this option also affects the output of <cite>get_style_defs()</cite>.</dd>
<dt><cite>cssclass</cite></dt>
<dd><p class="first">CSS class for the wrapping <tt class="docutils literal"><span class="pre">&lt;div&gt;</span></tt> tag (default: <tt class="docutils literal"><span class="pre">'highlight'</span></tt>).
If you set this option, the default selector for <cite>get_style_defs()</cite>
will be this class.</p>
<p class="last"><em>New in Pygments 0.9:</em> If you select the <tt class="docutils literal"><span class="pre">'table'</span></tt> line numbers, the
wrapping table will have a CSS class of this string plus <tt class="docutils literal"><span class="pre">'table'</span></tt>,
the default is accordingly <tt class="docutils literal"><span class="pre">'highlighttable'</span></tt>.</p>
</dd>
<dt><cite>cssstyles</cite></dt>
<dd>Inline CSS styles for the wrapping <tt class="docutils literal"><span class="pre">&lt;div&gt;</span></tt> tag (default: <tt class="docutils literal"><span class="pre">''</span></tt>).</dd>
<dt><cite>cssfile</cite></dt>
<dd>If the <cite>full</cite> option is true and this option is given, it must be the
name of an external file. If the filename does not include an absolute
path, the file's path will be assumed to be relative to the main output
file's path, if the latter can be found. The stylesheet is then written
to this file instead of the HTML file. <em>New in Pygments 0.6.</em></dd>
<dt><cite>linenos</cite></dt>
<dd><p class="first">If set to <tt class="docutils literal"><span class="pre">'table'</span></tt>, output line numbers as a table with two cells,
one containing the line numbers, the other the whole code.  This is
copy-and-paste-friendly, but may cause alignment problems with some
browsers or fonts.  If set to <tt class="docutils literal"><span class="pre">'inline'</span></tt>, the line numbers will be
integrated in the <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt> tag that contains the code (that setting
is <em>new in Pygments 0.8</em>).</p>
<p>For compatibility with Pygments 0.7 and earlier, every true value
except <tt class="docutils literal"><span class="pre">'inline'</span></tt> means the same as <tt class="docutils literal"><span class="pre">'table'</span></tt> (in particular, that
means also <tt class="docutils literal"><span class="pre">True</span></tt>).</p>
<p>The default value is <tt class="docutils literal"><span class="pre">False</span></tt>, which means no line numbers at all.</p>
<p class="last"><strong>Note:</strong> with the default (&quot;table&quot;) line number mechanism, the line
numbers and code can have different line heights in Internet Explorer
unless you give the enclosing <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt> tags an explicit <tt class="docutils literal"><span class="pre">line-height</span></tt>
CSS property (you get the default line spacing with <tt class="docutils literal"><span class="pre">line-height:</span>
<span class="pre">125%</span></tt>).</p>
</dd>
<dt><cite>linenostart</cite></dt>
<dd>The line number for the first line (default: <tt class="docutils literal"><span class="pre">1</span></tt>).</dd>
<dt><cite>linenostep</cite></dt>
<dd>If set to a number n &gt; 1, only every nth line number is printed.</dd>
<dt><cite>linenospecial</cite></dt>
<dd>If set to a number n &gt; 0, every nth line number is given the CSS
class <tt class="docutils literal"><span class="pre">&quot;special&quot;</span></tt> (default: <tt class="docutils literal"><span class="pre">0</span></tt>).</dd>
<dt><cite>nobackground</cite></dt>
<dd>If set to <tt class="docutils literal"><span class="pre">True</span></tt>, the formatter won't output the background color
for the wrapping element (this automatically defaults to <tt class="docutils literal"><span class="pre">False</span></tt>
when there is no wrapping element [eg: no argument for the
<cite>get_syntax_defs</cite> method given]) (default: <tt class="docutils literal"><span class="pre">False</span></tt>). <em>New in
Pygments 0.6.</em></dd>
<dt><cite>lineseparator</cite></dt>
<dd>This string is output between lines of code. It defaults to <tt class="docutils literal"><span class="pre">&quot;\n&quot;</span></tt>,
which is enough to break a line inside <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt> tags, but you can
e.g. set it to <tt class="docutils literal"><span class="pre">&quot;&lt;br&gt;&quot;</span></tt> to get HTML line breaks. <em>New in Pygments
0.7.</em></dd>
<dt><cite>lineanchors</cite></dt>
<dd>If set to a nonempty string, e.g. <tt class="docutils literal"><span class="pre">foo</span></tt>, the formatter will wrap each
output line in an anchor tag with a <tt class="docutils literal"><span class="pre">name</span></tt> of <tt class="docutils literal"><span class="pre">foo-linenumber</span></tt>.
This allows easy linking to certain lines. <em>New in Pygments 0.9.</em></dd>
</dl>
<p><strong>Subclassing the HTML formatter</strong></p>
<p><em>New in Pygments 0.7.</em></p>
<p>The HTML formatter is now built in a way that allows easy subclassing, thus
customizing the output HTML code. The <cite>format()</cite> method calls
<cite>self._format_lines()</cite> which returns a generator that yields tuples of <tt class="docutils literal"><span class="pre">(1,</span>
<span class="pre">line)</span></tt>, where the <tt class="docutils literal"><span class="pre">1</span></tt> indicates that the <tt class="docutils literal"><span class="pre">line</span></tt> is a line of the
formatted source code.</p>
<p>If the <cite>nowrap</cite> option is set, the generator is the iterated over and the
resulting HTML is output.</p>
<p>Otherwise, <cite>format()</cite> calls <cite>self.wrap()</cite>, which wraps the generator with
other generators. These may add some HTML code to the one generated by
<cite>_format_lines()</cite>, either by modifying the lines generated by the latter,
then yielding them again with <tt class="docutils literal"><span class="pre">(1,</span> <span class="pre">line)</span></tt>, and/or by yielding other HTML
code before or after the lines, with <tt class="docutils literal"><span class="pre">(0,</span> <span class="pre">html)</span></tt>. The distinction between
source lines and other code makes it possible to wrap the generator multiple
times.</p>
<p>The default <cite>wrap()</cite> implementation adds a <tt class="docutils literal"><span class="pre">&lt;div&gt;</span></tt> and a <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt> tag.</p>
<p>A custom <cite>HtmlFormatter</cite> subclass could look like this:</p>
<div class="syntax"><pre><span class="k">class</span> <span class="nc">CodeHtmlFormatter</span><span class="p">(</span><span class="n">HtmlFormatter</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">wrap</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">source</span><span class="p">,</span> <span class="n">outfile</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_wrap_code</span><span class="p">(</span><span class="n">source</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_wrap_code</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">source</span><span class="p">):</span>
        <span class="k">yield</span> <span class="mf">0</span><span class="p">,</span> <span class="s">&#39;&lt;code&gt;&#39;</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">source</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">i</span> <span class="o">==</span> <span class="mf">1</span><span class="p">:</span>
                <span class="c"># it&#39;s a line of formatted code</span>
                <span class="n">t</span> <span class="o">+=</span> <span class="s">&#39;&lt;br&gt;&#39;</span>
            <span class="k">yield</span> <span class="n">i</span><span class="p">,</span> <span class="n">t</span>
        <span class="k">yield</span> <span class="mf">0</span><span class="p">,</span> <span class="s">&#39;&lt;/code&gt;&#39;</span>
</pre></div>
<p>This results in wrapping the formatted lines with a <tt class="docutils literal"><span class="pre">&lt;code&gt;</span></tt> tag, where the
source lines are broken using <tt class="docutils literal"><span class="pre">&lt;br&gt;</span></tt> tags.</p>
<p>After calling <cite>wrap()</cite>, the <cite>format()</cite> method also adds the &quot;line numbers&quot;
and/or &quot;full document&quot; wrappers if the respective options are set. Then, all
HTML yielded by the wrapped generator is output.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">html</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.html, *.htm</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="terminal256formatter" name="terminal256formatter"><cite>Terminal256Formatter</cite></a></h4>
<blockquote>
<p>Format tokens with ANSI color sequences, for output in a 256-color
terminal or console. Like in <cite>TerminalFormatter</cite> color sequences
are terminated at newlines, so that paging the output works correctly.</p>
<p>The formatter takes colors from a style defined by the <cite>style</cite> option
and converts them to nearest ANSI 256-color escape sequences. Bold and
underline attributes from the style are preserved (and displayed).</p>
<p><em>New in Pygments 0.9.</em></p>
<p>Options accepted:</p>
<dl class="docutils">
<dt><cite>style</cite></dt>
<dd>The style to use, can be a string or a Style subclass (default:
<tt class="docutils literal"><span class="pre">'default'</span></tt>).</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">terminal256, console256, 256</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">None</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="terminalformatter" name="terminalformatter"><cite>TerminalFormatter</cite></a></h4>
<blockquote>
<p>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.</p>
<p>The <cite>get_style_defs()</cite> method doesn't do anything special since there is
no support for common styles.</p>
<p>Options accepted:</p>
<dl class="docutils">
<dt><cite>bg</cite></dt>
<dd>Set to <tt class="docutils literal"><span class="pre">&quot;light&quot;</span></tt> or <tt class="docutils literal"><span class="pre">&quot;dark&quot;</span></tt> depending on the terminal's background
(default: <tt class="docutils literal"><span class="pre">&quot;light&quot;</span></tt>).</dd>
<dt><cite>colorscheme</cite></dt>
<dd>A dictionary mapping token types to (lightbg, darkbg) color names or
<tt class="docutils literal"><span class="pre">None</span></tt> (default: <tt class="docutils literal"><span class="pre">None</span></tt> = use builtin colorscheme).</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">terminal, console</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">None</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="latexformatter" name="latexformatter"><cite>LatexFormatter</cite></a></h4>
<blockquote>
<p>Format tokens as LaTeX code. This needs the <cite>fancyvrb</cite> and <cite>color</cite>
standard packages.</p>
<p>Without the <cite>full</cite> option, code is formatted as one <tt class="docutils literal"><span class="pre">Verbatim</span></tt>
environment, like this:</p>
<div class="syntax"><pre><span class="k">\begin</span><span class="nb">{</span>Verbatim<span class="nb">}</span>[commandchars=@<span class="sb">\[</span><span class="s">\]</span>]
@PYan[def ]@PYax[foo](bar):
    @PYan[pass]
<span class="k">\end</span><span class="nb">{</span>Verbatim<span class="nb">}</span>
</pre></div>
<p>The command sequences used here (<tt class="docutils literal"><span class="pre">&#64;PYan</span></tt> etc.) are generated from the given
<cite>style</cite> and can be retrieved using the <cite>get_style_defs</cite> method.</p>
<p>With the <cite>full</cite> option, a complete LaTeX document is output, including
the command definitions in the preamble.</p>
<p>The <cite>get_style_defs()</cite> method of a <cite>LatexFormatter</cite> returns a string
containing <tt class="docutils literal"><span class="pre">\newcommand</span></tt> commands defining the commands used inside the
<tt class="docutils literal"><span class="pre">Verbatim</span></tt> environments.</p>
<p>Additional options accepted:</p>
<dl class="docutils">
<dt><cite>style</cite></dt>
<dd>The style to use, can be a string or a Style subclass (default:
<tt class="docutils literal"><span class="pre">'default'</span></tt>).</dd>
<dt><cite>full</cite></dt>
<dd>Tells the formatter to output a &quot;full&quot; document, i.e. a complete
self-contained document (default: <tt class="docutils literal"><span class="pre">False</span></tt>).</dd>
<dt><cite>title</cite></dt>
<dd>If <cite>full</cite> is true, the title that should be used to caption the
document (default: <tt class="docutils literal"><span class="pre">''</span></tt>).</dd>
<dt><cite>docclass</cite></dt>
<dd>If the <cite>full</cite> option is enabled, this is the document class to use
(default: <tt class="docutils literal"><span class="pre">'article'</span></tt>).</dd>
<dt><cite>preamble</cite></dt>
<dd>If the <cite>full</cite> option is enabled, this can be further preamble commands,
e.g. <tt class="docutils literal"><span class="pre">\usepackage</span></tt> (default: <tt class="docutils literal"><span class="pre">''</span></tt>).</dd>
<dt><cite>linenos</cite></dt>
<dd>If set to <tt class="docutils literal"><span class="pre">True</span></tt>, output line numbers (default: <tt class="docutils literal"><span class="pre">False</span></tt>).</dd>
<dt><cite>linenostart</cite></dt>
<dd>The line number for the first line (default: <tt class="docutils literal"><span class="pre">1</span></tt>).</dd>
<dt><cite>linenostep</cite></dt>
<dd>If set to a number n &gt; 1, only every nth line number is printed.</dd>
<dt><cite>verboptions</cite></dt>
<dd>Additional options given to the Verbatim environment (see the <em>fancyvrb</em>
docs for possible values) (default: <tt class="docutils literal"><span class="pre">''</span></tt>).</dd>
<dt><cite>commandprefix</cite></dt>
<dd>The LaTeX commands used to produce colored output are constructed
using this prefix and some letters (default: <tt class="docutils literal"><span class="pre">'PY'</span></tt>).
<em>New in Pygments 0.7.</em>
<em>New in Pygments 0.10:</em> the default is now <tt class="docutils literal"><span class="pre">'PY'</span></tt> instead of <tt class="docutils literal"><span class="pre">'C'</span></tt>.</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">latex, tex</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.tex</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="imageformatter" name="imageformatter"><cite>ImageFormatter</cite></a></h4>
<blockquote>
<p>Create an image from source code. This uses the Python Imaging Library to
generate a pixmap from the source code.</p>
<p><em>New in Pygments 0.10.</em></p>
<p>Additional options accepted:</p>
<dl class="docutils">
<dt><cite>image_format</cite></dt>
<dd><p class="first">An image format to output to that is recognised by PIL, these include:</p>
<ul class="last simple">
<li>&quot;PNG&quot; (default)</li>
<li>&quot;JPEG&quot;</li>
<li>&quot;BMP&quot;</li>
<li>&quot;GIF&quot;</li>
</ul>
</dd>
<dt><cite>line_pad</cite></dt>
<dd><p class="first">The extra spacing (in pixels) between each line of text.</p>
<p class="last">Default: 2</p>
</dd>
<dt><cite>font_name</cite></dt>
<dd><p class="first">The font name to be used as the base font from which others, such as
bold and italic fonts will be generated.  This really should be a
monospace font to look sane.</p>
<p class="last">Default: &quot;Bitstream Vera Sans Mono&quot;</p>
</dd>
<dt><cite>font_size</cite></dt>
<dd><p class="first">The font size in points to be used.</p>
<p class="last">Default: 14</p>
</dd>
<dt><cite>image_pad</cite></dt>
<dd><p class="first">The padding, in pixels to be used at each edge of the resulting image.</p>
<p class="last">Default: 10</p>
</dd>
<dt><cite>line_numbers</cite></dt>
<dd><p class="first">Whether line numbers should be shown: True/False</p>
<p class="last">Default: True</p>
</dd>
<dt><cite>line_number_step</cite></dt>
<dd><p class="first">The step used when printing line numbers.</p>
<p class="last">Default: 1</p>
</dd>
<dt><cite>line_number_bg</cite></dt>
<dd><p class="first">The background colour (in &quot;#123456&quot; format) of the line number bar, or
None to use the style background color.</p>
<p class="last">Default: &quot;#eed&quot;</p>
</dd>
<dt><cite>line_number_fg</cite></dt>
<dd><p class="first">The text color of the line numbers (in &quot;#123456&quot;-like format).</p>
<p class="last">Default: &quot;#886&quot;</p>
</dd>
<dt><cite>line_number_chars</cite></dt>
<dd><p class="first">The number of columns of line numbers allowable in the line number
margin.</p>
<p class="last">Default: 2</p>
</dd>
<dt><cite>line_number_bold</cite></dt>
<dd><p class="first">Whether line numbers will be bold: True/False</p>
<p class="last">Default: False</p>
</dd>
<dt><cite>line_number_italic</cite></dt>
<dd><p class="first">Whether line numbers will be italicized: True/False</p>
<p class="last">Default: False</p>
</dd>
<dt><cite>line_number_separator</cite></dt>
<dd><p class="first">Whether a line will be drawn between the line number area and the
source code area: True/False</p>
<p class="last">Default: True</p>
</dd>
<dt><cite>line_number_pad</cite></dt>
<dd><p class="first">The horizontal padding (in pixels) between the line number margin, and
the source code area.</p>
<p class="last">Default: 6</p>
</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">img, IMG, png, jpg, gif, bmp</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.png, *.jpg, *.gif, *.bmp</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="rawtokenformatter" name="rawtokenformatter"><cite>RawTokenFormatter</cite></a></h4>
<blockquote>
<p>Format tokens as a raw representation for storing token streams.</p>
<p>The format is <tt class="docutils literal"><span class="pre">tokentype&lt;TAB&gt;repr(tokenstring)\n</span></tt>. The output can later
be converted to a token stream with the <cite>RawTokenLexer</cite>, described in the
<a class="reference" href="./lexers.html">lexer list</a>.</p>
<p>Only one option is accepted:</p>
<dl class="docutils">
<dt><cite>compress</cite></dt>
<dd>If set to <tt class="docutils literal"><span class="pre">'gz'</span></tt> or <tt class="docutils literal"><span class="pre">'bz2'</span></tt>, compress the output with the given
compression algorithm after encoding (default: <tt class="docutils literal"><span class="pre">''</span></tt>).</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">raw, tokens</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.raw</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="rtfformatter" name="rtfformatter"><cite>RtfFormatter</cite></a></h4>
<blockquote>
<p>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.</p>
<p><em>New in Pygments 0.6.</em></p>
<p>Additional options accepted:</p>
<dl class="docutils">
<dt><cite>style</cite></dt>
<dd>The style to use, can be a string or a Style subclass (default:
<tt class="docutils literal"><span class="pre">'default'</span></tt>).</dd>
<dt><cite>fontface</cite></dt>
<dd>The used font famliy, for example <tt class="docutils literal"><span class="pre">Bitstream</span> <span class="pre">Vera</span> <span class="pre">Sans</span></tt>. Defaults to
some generic font which is supposed to have fixed width.</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">rtf</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.rtf</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="svgformatter" name="svgformatter"><cite>SvgFormatter</cite></a></h4>
<blockquote>
<p>Format tokens as an SVG graphics file.  This formatter is still experimental.
Each line of code is a <tt class="docutils literal"><span class="pre">&lt;text&gt;</span></tt> element with explicit <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt>
coordinates containing <tt class="docutils literal"><span class="pre">&lt;tspan&gt;</span></tt> elements with the individual token styles.</p>
<p>By default, this formatter outputs a full SVG document including doctype
declaration and the <tt class="docutils literal"><span class="pre">&lt;svg&gt;</span></tt> root element.</p>
<p><em>New in Pygments 0.9.</em></p>
<p>Additional options accepted:</p>
<dl class="docutils">
<dt><cite>nowrap</cite></dt>
<dd>Don't wrap the SVG <tt class="docutils literal"><span class="pre">&lt;text&gt;</span></tt> elements in <tt class="docutils literal"><span class="pre">&lt;svg&gt;&lt;g&gt;</span></tt> elements and
don't add a XML declaration and a doctype.  If true, the <cite>fontfamily</cite>
and <cite>fontsize</cite> options are ignored.  Defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.</dd>
<dt><cite>fontfamily</cite></dt>
<dd>The value to give the wrapping <tt class="docutils literal"><span class="pre">&lt;g&gt;</span></tt> element's <tt class="docutils literal"><span class="pre">font-family</span></tt>
attribute, defaults to <tt class="docutils literal"><span class="pre">&quot;monospace&quot;</span></tt>.</dd>
<dt><cite>fontsize</cite></dt>
<dd>The value to give the wrapping <tt class="docutils literal"><span class="pre">&lt;g&gt;</span></tt> element's <tt class="docutils literal"><span class="pre">font-size</span></tt>
attribute, defaults to <tt class="docutils literal"><span class="pre">&quot;14px&quot;</span></tt>.</dd>
<dt><cite>xoffset</cite></dt>
<dd>Starting offset in X direction, defaults to <tt class="docutils literal"><span class="pre">0</span></tt>.</dd>
<dt><cite>yoffset</cite></dt>
<dd>Starting offset in Y direction, defaults to the font size if it is given
in pixels, or <tt class="docutils literal"><span class="pre">20</span></tt> else.  (This is necessary since text coordinates
refer to the text baseline, not the top edge.)</dd>
<dt><cite>ystep</cite></dt>
<dd>Offset to add to the Y coordinate for each subsequent line.  This should
roughly be the text size plus 5.  It defaults to that value if the text
size is given in pixels, or <tt class="docutils literal"><span class="pre">25</span></tt> else.</dd>
<dt><cite>spacehack</cite></dt>
<dd>Convert spaces in the source to <tt class="docutils literal"><span class="pre">&amp;160;</span></tt>, which are non-breaking
spaces.  SVG provides the <tt class="docutils literal"><span class="pre">xml:space</span></tt> attribute to control how
whitespace inside tags is handled, in theory, the <tt class="docutils literal"><span class="pre">preserve</span></tt> value
could be used to keep all whitespace as-is.  However, many current SVG
viewers don't obey that rule, so this option is provided as a workaround
and defaults to <tt class="docutils literal"><span class="pre">True</span></tt>.</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">svg</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.svg</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section">
<h4><a id="nullformatter" name="nullformatter"><cite>NullFormatter</cite></a></h4>
<blockquote>
<p>Output the text unchanged without any formatting.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Short names:</th><td class="field-body">text, null</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.txt</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
</div>

  </div>
</body>
<!-- generated on: 2008-05-06 18:28:10.678437
     file id: formatters -->
</html>