簡介與快速入門¶
歡迎使用 Pygments！本文說明基本概念與術語，並提供一些如何使用這個函式庫的範例。
架構¶
程式碼片段的語法突顯由四種類型的元件協同運作完成
詞法分析器 (lexer) 將原始碼拆解成語彙單元 (token)，即具有語彙單元類型 (token type) 的原始碼片段，語彙單元類型決定了文字在語義上的含義（例如，關鍵字、字串或註解）。Pygments 支援的每種語言或標記格式都有對應的詞法分析器。
語彙單元流可以通過篩選器 (filters) 管道處理，篩選器通常會修改語彙單元類型或文字片段，例如，將所有關鍵字轉為大寫。
接著，格式化器 (formatter) 取得語彙單元流，並以 HTML、LaTeX 或 RTF 等格式寫入輸出檔案。
在寫入輸出時，樣式 (style) 決定如何突顯所有不同的語彙單元類型。它將它們映射到「紅色且粗體」等屬性。
範例¶
以下是突顯 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>
如您所見，Pygments 預設使用 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* 的參數，如果給定，它必須是一個檔案物件。格式化後的輸出將會寫入到這個檔案，而不是以字串的形式傳回。
詞法分析器和格式化器都支援選項。它們以關鍵字引數的形式傳遞給類別或查詢方法
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)
這使得詞法分析器從輸入中移除所有開頭和結尾的空白 ( stripall 選項 )，讓格式化器輸出列號 ( linenos 選項 )，並將包裝 <div> 的類別設定為 source （而不是 highlight）。
重要的選項包括
- encoding用於詞法分析器和格式化器
由於 Pygments 在內部使用 Unicode 字串，因此這會決定從位元組字串轉換或轉換成位元組字串時使用的編碼。
- style用於格式化器
輸出時要使用的樣式名稱。
如需內建詞法分析器和格式化器及其選項的概觀，請瀏覽 詞法分析器 和 格式化器 清單。
有關篩選器的文件，請參閱 此頁面。
詞法分析器與格式化器查詢¶
如果您想通過別名或檔名查詢內建的詞法分析器，可以使用以下方法之一
>>> 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>
所有這些函式都接受關鍵字引數；它們會作為選項傳遞給詞法分析器。
格式化器也有類似的 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() 將給定的內容傳遞給詞法分析器類別的 analyse_text() 方法，並傳回該方法傳回最高數字的方法。
所有詞法分析器都有兩個不同的檔名模式清單：主要清單和次要清單。get_lexer_for_filename() 函式僅使用主要清單，其項目在所有詞法分析器中應該是唯一的。guess_lexer_for_filename() 然而，如果檔名匹配，則會先循環遍歷所有詞法分析器，並查看主要和次要檔名模式。如果只有一個詞法分析器匹配，則傳回該詞法分析器，否則會使用 guess_lexer() 的猜測機制來處理匹配的詞法分析器。
如同往常一樣，這些函式的關鍵字引數會作為選項提供給建立的詞法分析器。
命令列用法¶
您可以使用命令列中的 Pygments，使用 pygmentize 腳本
$ pygmentize test.py
這將使用 ANSI 跳脫序列 ( 又稱終端機顏色 ) 突顯 Python 檔案 test.py，並將結果列印到標準輸出。
若要輸出 HTML，請使用 -f 選項
$ pygmentize -f html -o test.html test.py
這會將 test.py 的 HTML 突顯版本寫入檔案 test.html。請注意，這只會是 HTML 片段，如果您想要完整的 HTML 文件，請使用「full」選項
$ pygmentize -f html -O full -o test.html test.py
這將產生一個包含樣式表的完整 HTML 文件。
可以使用 -O style=<name> 選取樣式。
如果您需要現有 HTML 檔案的樣式表，並使用 Pygments CSS 類別，則可以使用以下方式建立：
$ pygmentize -S default -f html > style.css
其中 default 是樣式名稱。
您可以在 命令列參考 中找到更多選項和技巧。