<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Available formatters — 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 .hll { background-color: #ffffcc }
.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 .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.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">« 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" id="common-options">
<h3>Common options</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">"utf-8"</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">None</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">meta
<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">""</tt> or <tt class="docutils literal">None</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">None</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">"guess"</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" id="formatter-classes">
<h3>Formatter classes</h3>
<p>All these classes are importable from <cite>pygments.formatters</cite>.</p>
<div class="section" id="bbcodeformatter">
<h4><cite>BBCodeFormatter</cite></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">monofont</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">'default'</tt>).</dd>
<dt><cite>codetag</cite></dt>
<dd>If set to true, put the output into <tt class="docutils literal">[code]</tt> tags (default:
<tt class="docutils literal">false</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">false</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" id="bmpimageformatter">
<h4><cite>BmpImageFormatter</cite></h4>
<blockquote>
<p>Create a bitmap image from source code. This uses the Python Imaging Library to
generate a pixmap from the source code.</p>
<p><em>New in Pygments 1.0.</em> (You could create bitmap images before by passing a
suitable <cite>image_format</cite> option to the <cite>ImageFormatter</cite>.)</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">bmp, bitmap</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.bmp</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="gifimageformatter">
<h4><cite>GifImageFormatter</cite></h4>
<blockquote>
<p>Create a GIF image from source code. This uses the Python Imaging Library to
generate a pixmap from the source code.</p>
<p><em>New in Pygments 1.0.</em> (You could create GIF images before by passing a
suitable <cite>image_format</cite> option to the <cite>ImageFormatter</cite>.)</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">gif</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.gif</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="htmlformatter">
<h4><cite>HtmlFormatter</cite></h4>
<blockquote>
<p>Format tokens as HTML 4 <tt class="docutils literal"><span></tt> tags within a <tt class="docutils literal"><pre></tt> tag, wrapped
in a <tt class="docutils literal"><div></tt> tag. The <tt class="docutils literal"><div></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">"table"</tt>, the <tt class="docutils literal"><pre></tt> is
additionally wrapped inside a <tt class="docutils literal"><table></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"><div</span> <span class="na">class=</span><span class="s">"highlight"</span> <span class="nt">></span>
<span class="nt"><table><tr></span>
<span class="nt"><td</span> <span class="na">class=</span><span class="s">"linenos"</span> <span class="na">title=</span><span class="s">"click to toggle"</span>
<span class="na">onclick=</span><span class="s">"with (this.firstChild.style)</span>
<span class="s"> { display = (display == '') ? 'none' : '' }"</span><span class="nt">></span>
<span class="nt"><pre></span>1
2<span class="nt"></pre></span>
<span class="nt"></td></span>
<span class="nt"><td</span> <span class="na">class=</span><span class="s">"code"</span><span class="nt">></span>
<span class="nt"><pre><span</span> <span class="na">class=</span><span class="s">"Ke"</span><span class="nt">></span>def <span class="nt"></span><span</span> <span class="na">class=</span><span class="s">"NaFu"</span><span class="nt">></span>foo<span class="nt"></span></span>(bar):
<span class="nt"><span</span> <span class="na">class=</span><span class="s">"Ke"</span><span class="nt">></span>pass<span class="nt"></span></span>
<span class="nt"></pre></span>
<span class="nt"></td></span>
<span class="nt"></tr></table></div></span>
</pre></div>
<p>(whitespace added to improve clarity).</p>
<p>Wrapping can be disabled using the <cite>nowrap</cite> option.</p>
<p>A list of lines can be specified using the <cite>hl_lines</cite> option to make these
lines highlighted (as of Pygments 0.11).</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"><style></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">'div.syntax pre'</span><span class="p">,</span> <span class="s">'pre.syntax'</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">True</tt>, don't wrap the tokens at all, not even inside a <tt class="docutils literal"><pre></tt>
tag. This disables most other options (default: <tt class="docutils literal">False</tt>).</dd>
<dt><cite>full</cite></dt>
<dd>Tells the formatter to output a "full" document, i.e. a complete
self-contained document (default: <tt class="docutils literal">False</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">''</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">'default'</tt>). This option has no effect if the <cite>cssfile</cite>
and <cite>noclobber_cssfile</cite> option are given and the file specified in
<cite>cssfile</cite> exists.</dd>
<dt><cite>noclasses</cite></dt>
<dd>If set to true, token <tt class="docutils literal"><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">False</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"><div></tt> tag (default: <tt class="docutils literal">'highlight'</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">'table'</tt> line numbers, the
wrapping table will have a CSS class of this string plus <tt class="docutils literal">'table'</tt>,
the default is accordingly <tt class="docutils literal">'highlighttable'</tt>.</p>
</dd>
<dt><cite>cssstyles</cite></dt>
<dd>Inline CSS styles for the wrapping <tt class="docutils literal"><div></tt> tag (default: <tt class="docutils literal">''</tt>).</dd>
<dt><cite>prestyles</cite></dt>
<dd>Inline CSS styles for the <tt class="docutils literal"><pre></tt> tag (default: <tt class="docutils literal">''</tt>). <em>New in
Pygments 0.11.</em></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>noclobber_cssfile</cite></dt>
<dd>If <cite>cssfile</cite> is given and the specified file exists, the css file will
not be overwritten. This allows the use of the <cite>full</cite> option in
combination with a user specified css file. Default is <tt class="docutils literal">False</tt>.
<em>New in Pygments 1.1.</em></dd>
<dt><cite>linenos</cite></dt>
<dd><p class="first">If set to <tt class="docutils literal">'table'</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">'inline'</tt>, the line numbers will be
integrated in the <tt class="docutils literal"><pre></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">'inline'</tt> means the same as <tt class="docutils literal">'table'</tt> (in particular, that
means also <tt class="docutils literal">True</tt>).</p>
<p>The default value is <tt class="docutils literal">False</tt>, which means no line numbers at all.</p>
<p class="last"><strong>Note:</strong> with the default ("table") 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"><pre></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>
125%</tt>).</p>
</dd>
<dt><cite>hl_lines</cite></dt>
<dd>Specify a list of lines to be highlighted. <em>New in Pygments 0.11.</em></dd>
<dt><cite>linenostart</cite></dt>
<dd>The line number for the first line (default: <tt class="docutils literal">1</tt>).</dd>
<dt><cite>linenostep</cite></dt>
<dd>If set to a number n > 1, only every nth line number is printed.</dd>
<dt><cite>linenospecial</cite></dt>
<dd>If set to a number n > 0, every nth line number is given the CSS
class <tt class="docutils literal">"special"</tt> (default: <tt class="docutils literal">0</tt>).</dd>
<dt><cite>nobackground</cite></dt>
<dd>If set to <tt class="docutils literal">True</tt>, the formatter won't output the background color
for the wrapping element (this automatically defaults to <tt class="docutils literal">False</tt>
when there is no wrapping element [eg: no argument for the
<cite>get_syntax_defs</cite> method given]) (default: <tt class="docutils literal">False</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">"\n"</tt>,
which is enough to break a line inside <tt class="docutils literal"><pre></tt> tags, but you can
e.g. set it to <tt class="docutils literal">"<br>"</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">foo</tt>, the formatter will wrap each
output line in an anchor tag with a <tt class="docutils literal">name</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>
<dt><cite>anchorlinenos</cite></dt>
<dd>If set to <cite>True</cite>, will wrap line numbers in <a> tags. Used in
combination with <cite>linenos</cite> and <cite>lineanchors</cite>.</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">(1,
line)</tt>, where the <tt class="docutils literal">1</tt> indicates that the <tt class="docutils literal">line</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">(1, line)</tt>, and/or by yielding other HTML
code before or after the lines, with <tt class="docutils literal">(0, html)</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"><div></tt> and a <tt class="docutils literal"><pre></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="mi">0</span><span class="p">,</span> <span class="s">'<code>'</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="mi">1</span><span class="p">:</span>
<span class="c"># it's a line of formatted code</span>
<span class="n">t</span> <span class="o">+=</span> <span class="s">'<br>'</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="mi">0</span><span class="p">,</span> <span class="s">'</code>'</span>
</pre></div>
<p>This results in wrapping the formatted lines with a <tt class="docutils literal"><code></tt> tag, where the
source lines are broken using <tt class="docutils literal"><br></tt> tags.</p>
<p>After calling <cite>wrap()</cite>, the <cite>format()</cite> method also adds the "line numbers"
and/or "full document" 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" id="imageformatter">
<h4><cite>ImageFormatter</cite></h4>
<blockquote>
<p>Create a PNG 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>"PNG" (default)</li>
<li>"JPEG"</li>
<li>"BMP"</li>
<li>"GIF"</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: "Bitstream Vera Sans Mono"</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_start</cite></dt>
<dd><p class="first">The line number of the first line.</p>
<p class="last">Default: 1</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 "#123456" format) of the line number bar, or
None to use the style background color.</p>
<p class="last">Default: "#eed"</p>
</dd>
<dt><cite>line_number_fg</cite></dt>
<dd><p class="first">The text color of the line numbers (in "#123456"-like format).</p>
<p class="last">Default: "#886"</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>
<dt><cite>hl_lines</cite></dt>
<dd><p class="first">Specify a list of lines to be highlighted. <em>New in Pygments 1.2.</em></p>
<p class="last">Default: empty list</p>
</dd>
<dt><cite>hl_color</cite></dt>
<dd><p class="first">Specify the color for highlighting lines. <em>New in Pygments 1.2.</em></p>
<p class="last">Default: highlight color of the selected style</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</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.png</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="jpgimageformatter">
<h4><cite>JpgImageFormatter</cite></h4>
<blockquote>
<p>Create a JPEG image from source code. This uses the Python Imaging Library to
generate a pixmap from the source code.</p>
<p><em>New in Pygments 1.0.</em> (You could create JPEG images before by passing a
suitable <cite>image_format</cite> option to the <cite>ImageFormatter</cite>.)</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">jpg, jpeg</td>
</tr>
<tr class="field"><th class="field-name">Filename patterns:</th><td class="field-body">*.jpg</td>
</tr>
</tbody>
</table>
</blockquote>
</div>
<div class="section" id="latexformatter">
<h4><cite>LatexFormatter</cite></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">Verbatim</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="k">\\</span><span class="nb">{</span><span class="k">\}</span>]
<span class="k">\PY</span><span class="nb">{</span>k<span class="nb">}{</span>def <span class="nb">}</span><span class="k">\PY</span><span class="nb">{</span>n+nf<span class="nb">}{</span>foo<span class="nb">}</span>(<span class="k">\PY</span><span class="nb">{</span>n<span class="nb">}{</span>bar<span class="nb">}</span>):
<span class="k">\PY</span><span class="nb">{</span>k<span class="nb">}{</span>pass<span class="nb">}</span>
<span class="k">\end</span><span class="nb">{</span>Verbatim<span class="nb">}</span>
</pre></div>
<p>The special command used here (<tt class="docutils literal">\PY</tt>) and all the other macros it needs
are output by 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">\def</tt> commands defining the macros needed inside the
<tt class="docutils literal">Verbatim</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">'default'</tt>).</dd>
<dt><cite>full</cite></dt>
<dd>Tells the formatter to output a "full" document, i.e. a complete
self-contained document (default: <tt class="docutils literal">False</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">''</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">'article'</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">\usepackage</tt> (default: <tt class="docutils literal">''</tt>).</dd>
<dt><cite>linenos</cite></dt>
<dd>If set to <tt class="docutils literal">True</tt>, output line numbers (default: <tt class="docutils literal">False</tt>).</dd>
<dt><cite>linenostart</cite></dt>
<dd>The line number for the first line (default: <tt class="docutils literal">1</tt>).</dd>
<dt><cite>linenostep</cite></dt>
<dd>If set to a number n > 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">''</tt>).</dd>
<dt><cite>commandprefix</cite></dt>
<dd><p class="first">The LaTeX commands used to produce colored output are constructed
using this prefix and some letters (default: <tt class="docutils literal">'PY'</tt>).
<em>New in Pygments 0.7.</em></p>
<p class="last"><em>New in Pygments 0.10:</em> the default is now <tt class="docutils literal">'PY'</tt> instead of <tt class="docutils literal">'C'</tt>.</p>
</dd>
<dt><cite>texcomments</cite></dt>
<dd>If set to <tt class="docutils literal">True</tt>, enables LaTeX comment lines. That is, LaTex markup
in comment tokens is not escaped so that LaTeX can render it (default:
<tt class="docutils literal">False</tt>). <em>New in Pygments 1.2.</em></dd>
<dt><cite>mathescape</cite></dt>
<dd>If set to <tt class="docutils literal">True</tt>, enables LaTeX math mode escape in comments. That
is, <tt class="docutils literal"><span class="pre">'$...$'</span></tt> inside a comment will trigger math mode (default:
<tt class="docutils literal">False</tt>). <em>New in Pygments 1.2.</em></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" id="nullformatter">
<h4><cite>NullFormatter</cite></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 class="section" id="rawtokenformatter">
<h4><cite>RawTokenFormatter</cite></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<TAB>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 external" href="./lexers.html">lexer list</a>.</p>
<p>Only two options are accepted:</p>
<dl class="docutils">
<dt><cite>compress</cite></dt>
<dd>If set to <tt class="docutils literal">'gz'</tt> or <tt class="docutils literal">'bz2'</tt>, compress the output with the given
compression algorithm after encoding (default: <tt class="docutils literal">''</tt>).</dd>
<dt><cite>error_color</cite></dt>
<dd>If set to a color name, highlight error tokens using that color. If
set but with no value, defaults to <tt class="docutils literal">'red'</tt>.
<em>New in Pygments 0.11.</em></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" id="rtfformatter">
<h4><cite>RtfFormatter</cite></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">'default'</tt>).</dd>
<dt><cite>fontface</cite></dt>
<dd>The used font famliy, for example <tt class="docutils literal">Bitstream Vera Sans</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" id="svgformatter">
<h4><cite>SvgFormatter</cite></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"><text></tt> element with explicit <tt class="docutils literal">x</tt> and <tt class="docutils literal">y</tt>
coordinates containing <tt class="docutils literal"><tspan></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"><svg></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"><text></tt> elements in <tt class="docutils literal"><span class="pre"><svg><g></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">False</tt>.</dd>
<dt><cite>fontfamily</cite></dt>
<dd>The value to give the wrapping <tt class="docutils literal"><g></tt> element's <tt class="docutils literal"><span class="pre">font-family</span></tt>
attribute, defaults to <tt class="docutils literal">"monospace"</tt>.</dd>
<dt><cite>fontsize</cite></dt>
<dd>The value to give the wrapping <tt class="docutils literal"><g></tt> element's <tt class="docutils literal"><span class="pre">font-size</span></tt>
attribute, defaults to <tt class="docutils literal">"14px"</tt>.</dd>
<dt><cite>xoffset</cite></dt>
<dd>Starting offset in X direction, defaults to <tt class="docutils literal">0</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">20</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">25</tt> else.</dd>
<dt><cite>spacehack</cite></dt>
<dd>Convert spaces in the source to <tt class="docutils literal">&#160;</tt>, which are non-breaking
spaces. SVG provides the <tt class="docutils literal">xml:space</tt> attribute to control how
whitespace inside tags is handled, in theory, the <tt class="docutils literal">preserve</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">True</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" id="terminal256formatter">
<h4><cite>Terminal256Formatter</cite></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">'default'</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" id="terminalformatter">
<h4><cite>TerminalFormatter</cite></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">"light"</tt> or <tt class="docutils literal">"dark"</tt> depending on the terminal's background
(default: <tt class="docutils literal">"light"</tt>).</dd>
<dt><cite>colorscheme</cite></dt>
<dd>A dictionary mapping token types to (lightbg, darkbg) color names or
<tt class="docutils literal">None</tt> (default: <tt class="docutils literal">None</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>
</div>
</body>
<!-- generated on: 2011-01-03 18:05:48.500791
file id: formatters -->
</html>
