390 lines
19 KiB
HTML
390 lines
19 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Introduction and Quickstart — 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: #333333 } /* 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: #666666 } /* 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">Introduction and Quickstart</h2>
|
|
|
|
<a id="backlink" href="index.html">« Back To Index</a>
|
|
|
|
|
|
<div class="toc">
|
|
<h2>Contents</h2>
|
|
<ul class="contents">
|
|
|
|
<li><a href="#architecture">Architecture</a></li>
|
|
|
|
<li><a href="#example">Example</a></li>
|
|
|
|
<li><a href="#options">Options</a></li>
|
|
|
|
<li><a href="#lexer-and-formatter-lookup">Lexer and formatter lookup</a></li>
|
|
|
|
<li><a href="#guessing-lexers">Guessing lexers</a></li>
|
|
|
|
<li><a href="#command-line-usage">Command line usage</a></li>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
<!-- -*- mode: rst -*- -->
|
|
<p>Welcome to Pygments! This document explains the basic concepts and terms and
|
|
gives a few examples of how to use the library.</p>
|
|
<div class="section" id="architecture">
|
|
<h3>Architecture</h3>
|
|
<p>There are four types of components that work together highlighting a piece of
|
|
code:</p>
|
|
<ul class="simple">
|
|
<li>A <strong>lexer</strong> splits the source into tokens, fragments of the source that
|
|
have a token type that determines what the text represents semantically
|
|
(e.g., keyword, string, or comment). There is a lexer for every language
|
|
or markup format that Pygments supports.</li>
|
|
<li>The token stream can be piped through <strong>filters</strong>, which usually modify
|
|
the token types or text fragments, e.g. uppercasing all keywords.</li>
|
|
<li>A <strong>formatter</strong> then takes the token stream and writes it to an output
|
|
file, in a format such as HTML, LaTeX or RTF.</li>
|
|
<li>While writing the output, a <strong>style</strong> determines how to highlight all the
|
|
different token types. It maps them to attributes like "red and bold".</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="example">
|
|
<h3>Example</h3>
|
|
<p>Here is a small example for highlighting Python code:</p>
|
|
<div class="syntax"><pre><span class="kn">from</span> <span class="nn">pygments</span> <span class="kn">import</span> <span class="n">highlight</span>
|
|
<span class="kn">from</span> <span class="nn">pygments.lexers</span> <span class="kn">import</span> <span class="n">PythonLexer</span>
|
|
<span class="kn">from</span> <span class="nn">pygments.formatters</span> <span class="kn">import</span> <span class="n">HtmlFormatter</span>
|
|
|
|
<span class="n">code</span> <span class="o">=</span> <span class="s">'print "Hello World"'</span>
|
|
<span class="k">print</span> <span class="n">highlight</span><span class="p">(</span><span class="n">code</span><span class="p">,</span> <span class="n">PythonLexer</span><span class="p">(),</span> <span class="n">HtmlFormatter</span><span class="p">())</span>
|
|
</pre></div>
|
|
<p>which prints something like this:</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"><pre><span</span> <span class="na">class=</span><span class="s">"k"</span><span class="nt">></span>print<span class="nt"></span></span> <span class="nt"><span</span> <span class="na">class=</span><span class="s">"s"</span><span class="nt">></span><span class="ni">&quot;</span>Hello World<span class="ni">&quot;</span><span class="nt"></span></pre></span>
|
|
<span class="nt"></div></span>
|
|
</pre></div>
|
|
<p>As you can see, Pygments uses CSS classes (by default, but you can change that)
|
|
instead of inline styles in order to avoid outputting redundant style information over
|
|
and over. A CSS stylesheet that contains all CSS classes possibly used in the output
|
|
can be produced by:</p>
|
|
<div class="syntax"><pre><span class="k">print</span> <span class="n">HtmlFormatter</span><span class="p">()</span><span class="o">.</span><span class="n">get_style_defs</span><span class="p">(</span><span class="s">'.highlight'</span><span class="p">)</span>
|
|
</pre></div>
|
|
<p>The argument to <cite>get_style_defs</cite> is used as an additional CSS selector: the output
|
|
may look like this:</p>
|
|
<div class="syntax"><pre><span class="nc">.highlight</span> <span class="nc">.k</span> <span class="p">{</span> <span class="k">color</span><span class="o">:</span> <span class="m">#AA22FF</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="nc">.highlight</span> <span class="nc">.s</span> <span class="p">{</span> <span class="k">color</span><span class="o">:</span> <span class="m">#BB4444</span> <span class="p">}</span>
|
|
<span class="o">...</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="section" id="options">
|
|
<h3>Options</h3>
|
|
<p>The <cite>highlight()</cite> function supports a fourth argument called <cite>outfile</cite>, it must be
|
|
a file object if given. The formatted output will then be written to this file
|
|
instead of being returned as a string.</p>
|
|
<p>Lexers and formatters both support options. They are given to them as keyword
|
|
arguments either to the class or to the lookup method:</p>
|
|
<div class="syntax"><pre><span class="kn">from</span> <span class="nn">pygments</span> <span class="kn">import</span> <span class="n">highlight</span>
|
|
<span class="kn">from</span> <span class="nn">pygments.lexers</span> <span class="kn">import</span> <span class="n">get_lexer_by_name</span>
|
|
<span class="kn">from</span> <span class="nn">pygments.formatters</span> <span class="kn">import</span> <span class="n">HtmlFormatter</span>
|
|
|
|
<span class="n">lexer</span> <span class="o">=</span> <span class="n">get_lexer_by_name</span><span class="p">(</span><span class="s">"python"</span><span class="p">,</span> <span class="n">stripall</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
|
|
<span class="n">formatter</span> <span class="o">=</span> <span class="n">HtmlFormatter</span><span class="p">(</span><span class="n">linenos</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">cssclass</span><span class="o">=</span><span class="s">"source"</span><span class="p">)</span>
|
|
<span class="n">result</span> <span class="o">=</span> <span class="n">highlight</span><span class="p">(</span><span class="n">code</span><span class="p">,</span> <span class="n">lexer</span><span class="p">,</span> <span class="n">formatter</span><span class="p">)</span>
|
|
</pre></div>
|
|
<p>This makes the lexer strip all leading and trailing whitespace from the input
|
|
(<cite>stripall</cite> option), lets the formatter output line numbers (<cite>linenos</cite> option),
|
|
and sets the wrapping <tt class="docutils literal"><div></tt>'s class to <tt class="docutils literal">source</tt> (instead of
|
|
<tt class="docutils literal">highlight</tt>).</p>
|
|
<p>Important options include:</p>
|
|
<dl class="docutils">
|
|
<dt><cite>encoding</cite> <span class="classifier-delimiter">:</span> <span class="classifier">for lexers and formatters</span></dt>
|
|
<dd>Since Pygments uses Unicode strings internally, this determines which
|
|
encoding will be used to convert to or from byte strings.</dd>
|
|
<dt><cite>style</cite> <span class="classifier-delimiter">:</span> <span class="classifier">for formatters</span></dt>
|
|
<dd>The name of the style to use when writing the output.</dd>
|
|
</dl>
|
|
<p>For an overview of builtin lexers and formatters and their options, visit the
|
|
<a class="reference external" href="./lexers.html">lexer</a> and <a class="reference external" href="./formatters.html">formatters</a> lists.</p>
|
|
<p>For a documentation on filters, see <a class="reference external" href="./filters.html">this page</a>.</p>
|
|
</div>
|
|
<div class="section" id="lexer-and-formatter-lookup">
|
|
<h3>Lexer and formatter lookup</h3>
|
|
<p>If you want to lookup a built-in lexer by its alias or a filename, you can use
|
|
one of the following methods:</p>
|
|
<div class="syntax"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pygments.lexers</span> <span class="kn">import</span> <span class="p">(</span><span class="n">get_lexer_by_name</span><span class="p">,</span>
|
|
<span class="gp">... </span> <span class="n">get_lexer_for_filename</span><span class="p">,</span> <span class="n">get_lexer_for_mimetype</span><span class="p">)</span>
|
|
|
|
<span class="gp">>>> </span><span class="n">get_lexer_by_name</span><span class="p">(</span><span class="s">'python'</span><span class="p">)</span>
|
|
<span class="go"><pygments.lexers.PythonLexer></span>
|
|
|
|
<span class="gp">>>> </span><span class="n">get_lexer_for_filename</span><span class="p">(</span><span class="s">'spam.rb'</span><span class="p">)</span>
|
|
<span class="go"><pygments.lexers.RubyLexer></span>
|
|
|
|
<span class="gp">>>> </span><span class="n">get_lexer_for_mimetype</span><span class="p">(</span><span class="s">'text/x-perl'</span><span class="p">)</span>
|
|
<span class="go"><pygments.lexers.PerlLexer></span>
|
|
</pre></div>
|
|
<p>All these functions accept keyword arguments; they will be passed to the lexer
|
|
as options.</p>
|
|
<p>A similar API is available for formatters: use <cite>get_formatter_by_name()</cite> and
|
|
<cite>get_formatter_for_filename()</cite> from the <cite>pygments.formatters</cite> module
|
|
for this purpose.</p>
|
|
</div>
|
|
<div class="section" id="guessing-lexers">
|
|
<h3>Guessing lexers</h3>
|
|
<p>If you don't know the content of the file, or you want to highlight a file
|
|
whose extension is ambiguous, such as <tt class="docutils literal">.html</tt> (which could contain plain HTML
|
|
or some template tags), use these functions:</p>
|
|
<div class="syntax"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pygments.lexers</span> <span class="kn">import</span> <span class="n">guess_lexer</span><span class="p">,</span> <span class="n">guess_lexer_for_filename</span>
|
|
|
|
<span class="gp">>>> </span><span class="n">guess_lexer</span><span class="p">(</span><span class="s">'#!/usr/bin/python</span><span class="se">\n</span><span class="s">print "Hello World!"'</span><span class="p">)</span>
|
|
<span class="go"><pygments.lexers.PythonLexer></span>
|
|
|
|
<span class="gp">>>> </span><span class="n">guess_lexer_for_filename</span><span class="p">(</span><span class="s">'test.py'</span><span class="p">,</span> <span class="s">'print "Hello World!"'</span><span class="p">)</span>
|
|
<span class="go"><pygments.lexers.PythonLexer></span>
|
|
</pre></div>
|
|
<p><cite>guess_lexer()</cite> passes the given content to the lexer classes' <cite>analyse_text()</cite>
|
|
method and returns the one for which it returns the highest number.</p>
|
|
<p>All lexers have two different filename pattern lists: the primary and the
|
|
secondary one. The <cite>get_lexer_for_filename()</cite> function only uses the primary
|
|
list, whose entries are supposed to be unique among all lexers.
|
|
<cite>guess_lexer_for_filename()</cite>, however, will first loop through all lexers and
|
|
look at the primary and secondary filename patterns if the filename matches.
|
|
If only one lexer matches, it is returned, else the guessing mechanism of
|
|
<cite>guess_lexer()</cite> is used with the matching lexers.</p>
|
|
<p>As usual, keyword arguments to these functions are given to the created lexer
|
|
as options.</p>
|
|
</div>
|
|
<div class="section" id="command-line-usage">
|
|
<h3>Command line usage</h3>
|
|
<p>You can use Pygments from the command line, using the <cite>pygmentize</cite> script:</p>
|
|
<pre class="literal-block">
|
|
$ pygmentize test.py
|
|
</pre>
|
|
<p>will highlight the Python file test.py using ANSI escape sequences
|
|
(a.k.a. terminal colors) and print the result to standard output.</p>
|
|
<p>To output HTML, use the <tt class="docutils literal"><span class="pre">-f</span></tt> option:</p>
|
|
<pre class="literal-block">
|
|
$ pygmentize -f html -o test.html test.py
|
|
</pre>
|
|
<p>to write an HTML-highlighted version of test.py to the file test.html.
|
|
Note that it will only be a snippet of HTML, if you want a full HTML document,
|
|
use the "full" option:</p>
|
|
<pre class="literal-block">
|
|
$ pygmentize -f html -O full -o test.html test.py
|
|
</pre>
|
|
<p>This will produce a full HTML document with included stylesheet.</p>
|
|
<p>A style can be selected with <tt class="docutils literal"><span class="pre">-O</span> <span class="pre">style=<name></span></tt>.</p>
|
|
<p>If you need a stylesheet for an existing HTML file using Pygments CSS classes,
|
|
it can be created with:</p>
|
|
<pre class="literal-block">
|
|
$ pygmentize -S default -f html > style.css
|
|
</pre>
|
|
<p>where <tt class="docutils literal">default</tt> is the style name.</p>
|
|
<p>More options and tricks and be found in the <a class="reference external" href="./cmdline.html">command line reference</a>.</p>
|
|
</div>
|
|
|
|
</div>
|
|
</body>
|
|
<!-- generated on: 2013-01-09 17:48:43.152015
|
|
file id: quickstart -->
|
|
</html> |