介绍和快速入门¶
欢迎来到Pygments!本文档解释了基本概念和术语,并给出了一些如何使用库的示例。
建筑¶
有四种类型的组件一起工作,突出显示一段代码:
A 莱克塞 将源拆分为标记、具有标记类型的源片段,这些标记类型决定文本在语义上表示什么(例如关键字、字符串或注释)。Pygments支持的每种语言或标记格式都有一个lexer。
令牌流可以通过管道传输 过滤器 ,通常修改标记类型或文本片段,例如将所有关键字大写。
A 格式化程序 然后获取令牌流并以HTML、LaTex或RTF等格式将其写入输出文件。
在写入输出时, 风格 确定如何突出显示所有不同的标记类型。它将它们映射为“红色和粗体”等属性。
例子¶
下面是一个突出显示python代码的小示例:
from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter
code = 'print "Hello World"'
print(highlight(code, PythonLexer(), HtmlFormatter()))
打印的内容如下:
<div class="highlight">
<pre><span class="k">print</span> <span class="s">"Hello World"</span></pre>
</div>
如您所见,Pygment使用CSS类(默认情况下,但您可以更改它)而不是内联样式,以避免反复输出多余的样式信息。包含输出中可能使用的所有CSS类的CSS样式表可以通过以下方式生成:
print(HtmlFormatter().get_style_defs('.highlight'))
的论据 get_style_defs()
用作附加的css选择器:输出可能如下所示:
.highlight .k { color: #AA22FF; font-weight: bold }
.highlight .s { color: #BB4444 }
...
选项¶
这个 highlight()
函数支持第四个参数,称为 outfile ,则它必须是文件对象(如果给定)。然后,格式化的输出将被写入此文件,而不是作为字符串返回。
lexer和格式化程序都支持选项。它们作为关键字参数提供给类或查找方法:
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter
lexer = get_lexer_by_name("python", stripall=True)
formatter = HtmlFormatter(linenos=True, cssclass="source")
result = highlight(code, lexer, formatter)
这使得lexer从输入中去掉所有的前导和尾随空格 (stripall 选项),让格式化程序输出行号 (linenos 选项),并设置包装 <div>
班到 source
而不是 highlight
)
重要选项包括:
- encoding对于lexer和格式化程序
由于Pygments在内部使用Unicode字符串,因此这决定了将使用哪种编码来转换字节字符串或从字节字符串转换。
- style格式化程序
写入输出时要使用的样式的名称。
有关内置lexer和格式化程序及其选项的概述,请访问 lexer 和 formatters 列表。
有关过滤器的文档,请参阅 this page .
lexer和格式化程序查找¶
如果要按其别名或文件名查找内置lexer,可以使用以下方法之一:
>>> from pygments.lexers import (get_lexer_by_name,
... get_lexer_for_filename, get_lexer_for_mimetype)
>>> get_lexer_by_name('python')
<pygments.lexers.PythonLexer>
>>> get_lexer_for_filename('spam.rb')
<pygments.lexers.RubyLexer>
>>> get_lexer_for_mimetype('text/x-perl')
<pygments.lexers.PerlLexer>
所有这些函数都接受关键字参数;它们将作为选项传递给lexer。
格式化程序也可以使用类似的API:使用 get_formatter_by_name()
和 get_formatter_for_filename()
从 pygments.formatters
用于此目的的模块。
猜测词法¶
如果不知道文件的内容,或者希望突出显示扩展名不明确的文件,例如 .html
(可以包含纯HTML或某些模板标记),使用以下函数:
>>> from pygments.lexers import guess_lexer, guess_lexer_for_filename
>>> guess_lexer('#!/usr/bin/python\nprint "Hello World!"')
<pygments.lexers.PythonLexer>
>>> guess_lexer_for_filename('test.py', 'print "Hello World!"')
<pygments.lexers.PythonLexer>
.guess_lexer()
将给定内容传递给Lexer类的 analyse_text()
方法,并返回它为其返回最高数字的那个。
所有的lexer都有两个不同的文件名模式列表:第一个和第二个。这个 get_lexer_for_filename()
函数只使用主列表,其条目在所有lexer中都应该是唯一的。 guess_lexer_for_filename()
但是,首先将遍历所有lexer,并查看主文件名模式和辅助文件名模式(如果文件名匹配)。如果只有一个lexer匹配,则返回,否则返回 guess_lexer()
与匹配的lexer一起使用。
和往常一样,这些函数的关键字参数作为选项提供给创建的lexer。
命令行用法¶
您可以使用命令行中的Pygment, pygmentize 脚本::
$ pygmentize test.py
将使用ansi转义序列(a.k.a.终端颜色)突出显示python文件test.py,并将结果打印到标准输出。
要输出HTML,请使用 -f
选项:
$ pygmentize -f html -o test.html test.py
将突出显示的test.py版本的html写入文件test.html。请注意,它只是一个HTML片段,如果需要完整的HTML文档,请使用“完整”选项:
$ pygmentize -f html -O full -o test.html test.py
这将生成包含样式表的完整HTML文档。
可以使用 -O style=<name>
.
如果需要使用Pygments CSS类为现有HTML文件创建样式表,则可以使用以下方式创建样式表:
$ pygmentize -S default -f html > style.css
在哪里? default
是样式名。
更多选项和技巧可以在 command line reference 。