命令列介面

你可以從 shell 使用 Pygments，前提是你已安裝 pygmentize 指令碼

$ pygmentize test.py
print "Hello World"

會將檔案 test.py 列印到標準輸出，使用 Python 詞法分析器 (從檔案名稱副檔名推斷) 和終端格式器 (因為你沒有給定明確的格式器名稱)。

注意

如果你在 Windows 上，可能需要額外的工具才能使彩色輸出在終端機中運作。你可以透過安裝帶有 windows-terminal 額外功能的 Pygments (例如，pip install pygments[windows-terminal]) 來確保 Pygments 已安裝 Windows 主控台色彩支援。

pygmentize 會嘗試偵測終端機支援的最大色彩數量。16 種色彩和 256 種色彩的色彩格式器之間差異很大，但 256 種色彩和 1600 萬種色彩的色彩格式器之間的差異較不顯著。

以下是它如何偵測終端機支援的最大色彩數量。如果 COLORTERM 環境變數設定為 truecolor 或 24bit，它將使用 1600 萬種色彩表示法 (例如 terminal16m)。接下來，它會嘗試在環境變數 TERM 中的任何位置找到 256，它會使用 256 色表示法 (例如 terminal256)。如果找不到以上任一項，它會回復為 16 色表示法 (例如 terminal)。

如果你想要 HTML 輸出

$ pygmentize -f html -l python -o test.html test.py

如你所見，-l 選項明確選擇詞法分析器。如上所述，如果你給定一個輸入檔案名稱，並且它具有 Pygments 辨識的副檔名，你可以省略此選項。

-o 選項給定輸出檔案名稱。如果未給定，則輸出會寫入標準輸出。

-f 選項選擇格式器 (如同 -l 一樣，如果給定輸出檔案名稱且具有支援的副檔名，則可以省略它)。如果未給定輸出檔案名稱且省略 -f，則會使用 TerminalFormatter。

因此，以上命令也可以給定為

$ pygmentize -o test.html test.py

若要建立完整的 HTML 文件，包括行號和樣式表 (使用 "emacs" 樣式)，將 Python 檔案 test.py 高亮顯示到 test.html

$ pygmentize -O full,style=emacs,linenos=1 -o test.html test.py

選項與篩選器

可以使用 -O 選項給定詞法分析器和格式器選項

$ pygmentize -f html -O style=colorful,linenos=1 -l python test.py

如果選項字串包含任何特殊 shell 字元 (例如空格或展開萬用字元 (如 *))，請務必將選項字串括在引號中。如果選項預期為清單值，請以空格分隔清單項目 (你必須在此情況下也引選項值，以便 shell 不會分割它)。

由於 -O 選項引數會在逗號處分割，並預期分割的值會採用 name=value 的形式，因此你無法給定包含逗號或等號的選項值。因此，提供了選項 -P (從 Pygments 0.9 開始)，其運作方式與 -O 類似，但每個 -P 只能傳遞一個選項。其值接著可以包含所有字元

$ pygmentize -P "heading=Pygments, the Python highlighter" ...

使用 -F 選項將篩選器新增至符記串流

$ pygmentize -f html -l pascal -F keywordcase:case=upper main.pas

如你所見，篩選器的選項在冒號後給定。至於 -O，篩選器名稱和選項必須是一個 shell 字，因此冒號周圍可能沒有任何空格。

產生樣式

格式器通常不會輸出完整的樣式資訊。例如，HTML 格式器預設只會輸出具有 class 屬性的 <span> 標籤。因此，有一個特殊的 -S 選項用於產生樣式定義。用法如下

$ pygmentize -f html -S colorful -a .syntax

會為 "colorful" 樣式產生 CSS 樣式表 (因為你選擇了 HTML 格式器)，並將 ".syntax" 選取器加到所有樣式規則之前。

如需解釋 -a 對於特定格式器的意義，請尋找格式器的 .get_style_defs() 方法的 arg 引數。

取得詞法分析器名稱

新增於 1.0 版。

-N 選項會推測給定檔案名稱的詞法分析器名稱，因此

$ pygmentize -N setup.py

會列印出 python。它不會高亮顯示任何內容。如果該檔案名稱沒有已知的特定詞法分析器，則會列印 text。

此外，還有 -C 選項，其與 -N 類似，不同之處在於它會僅根據來自標準輸入的給定內容列印出詞法分析器名稱。

從檔案內容推測詞法分析器

-g 選項會嘗試從檔案內容推測正確的詞法分析器，如果無法推測出任何內容，則會以純文字傳遞。此選項也會在文字中尋找 Vim 模型行，以及 *某些* 語言的 shebang。用法如下

$ pygmentize -g setup.py

但請注意，此選項不是很可靠，如果 Pygments 無法從檔案的副檔名推測出正確的詞法分析器，則可能應該僅使用此選項。

高亮顯示 stdin 直到 EOF

-s 選項會一次處理一行，直到 EOF，而不是等待處理整個檔案。這僅適用於 stdin、僅適用於沒有跨行結構的詞法分析器，並且適用於來自 tail -f 的串流輸入。用法如下

$ tail -f sql.log | pygmentize -s -l sql

自訂詞法分析器與格式器

新增於 2.2 版。

-x 旗標允許從相對於目前目錄的檔案載入自訂詞法分析器和格式器。建立一個包含名為 CustomLexer 或 CustomFormatter 的類別的檔案，然後在命令列中指定它

$ pygmentize -l your_lexer.py -f your_formatter.py -x

你也可以用冒號指定類別的名稱

$ pygmentize -l your_lexer.py:SomeLexer -x

如需更多資訊，請參閱Pygments 關於詞法分析器開發的文件。

取得說明

-L 選項會列出詞法分析器、格式器及其簡短名稱和支援的檔案名稱副檔名、樣式和篩選器。如果你只想查看一個類別，請將其作為引數給定

$ pygmentize -L filters

將只會列出所有已安裝的篩選器。

新增於 2.11 版。

--json 選項可以與 -L 選項結合使用，以 JSON 格式輸出其內容。因此，若要以 JSON 格式列印所有已安裝的樣式及其描述，請使用命令

$ pygmentize -L styles --json

-H 選項會為你提供有關詞法分析器、格式器或篩選器的詳細資訊 (與本文件中找到的資訊相同)。用法如下

$ pygmentize -H formatter html

將會列印 HTML 格式器的說明，而

$ pygmentize -H lexer python

將會列印 Python 詞法分析器的說明，依此類推。

關於編碼的注意事項

新增於 0.9 版。

Pygments 會嘗試在格式化過程中智慧地處理編碼

  • 如果你給定 encoding 選項，它將會被用作輸入和輸出編碼。

  • 如果你給定 outencoding 選項，它將會覆寫 encoding 作為輸出編碼。

  • 如果您提供 inencoding 選項，它會覆寫 encoding 作為輸入編碼。

  • 如果您沒有提供編碼，且已提供輸出檔案，則詞法分析器和格式化器的預設編碼為終端機編碼或系統的預設地區編碼。在最後手段，會使用 latin1 （這會直接傳遞所有非 ASCII 字元）。

  • 如果您沒有提供編碼，且也沒有提供輸出檔案（這表示輸出會寫入到主控台），則詞法分析器和格式化器的預設編碼為終端機編碼（sys.stdout.encoding）。