はじめに & クイックスタート¶

Pygments へようこそ！このドキュメントでは、基本的な概念と用語を説明し、ライブラリの使用方法の例をいくつか示します。

アーキテクチャ¶

コードのハイライト表示を連携して行う 4 種類のコンポーネントがあります。

Lexer は、ソースコードをトークンに分割します。トークンとは、テキストが意味的に何を表しているか（キーワード、文字列、コメントなど）を決定するトークンタイプを持つソースの断片です。Pygments がサポートするすべての言語またはマークアップ形式に Lexer があります。
トークンストリームは、フィルタを通してパイプ処理できます。フィルタは通常、トークンタイプまたはテキストフラグメントを変更します（例：すべてのキーワードを大文字にする）。
次に、Formatter はトークンストリームを受け取り、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">&quot;Hello World&quot;</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 という 4 番目の引数をサポートしています。指定する場合は、ファイルオブジェクトである必要があります。フォーマットされた出力は、文字列として返される代わりに、このファイルに書き込まれます。

Lexer と Formatter はどちらもオプションをサポートしています。オプションは、クラスまたはルックアップメソッドへのキーワード引数として渡されます。

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 オプション）、Formatter は行番号を出力し（linenos オプション）、ラップする <div> のクラスを source に設定します（highlight の代わりに）。

重要なオプションは次のとおりです。

encodingLexer と Formatter 用: Pygments は内部で Unicode 文字列を使用するため、これはバイト文字列との変換に使用するエンコーディングを決定します。
styleFormatter 用: 出力時に使用するスタイルの名前。

組み込みの Lexer と Formatter、およびそれらのオプションの概要については、Lexer と Formatter のリストをご覧ください。

フィルタに関するドキュメントについては、このページを参照してください。

Lexer と Formatter の検索¶

組み込みの 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 に渡されます。

Formatter にも同様の API があります。 get_formatter_by_name() と get_formatter_for_filename() を pygments.formatters モジュールから使用してください。

Lexer の推測¶

ファイルの内容がわからない場合、または .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 には、プライマリとセカンダリの 2 つの異なるファイル名パターンリストがあります。 get_lexer_for_filename() 関数は、プライマリリストのみを使用します。プライマリリストのエントリは、すべての Lexer で一意であると想定されています。ただし、guess_lexer_for_filename() は、最初にすべての Lexer をループ処理し、ファイル名が一致する場合、プライマリとセカンダリのファイル名パターンを調べます。一致する Lexer が 1 つだけの場合、それが返されます。それ以外の場合は、guess_lexer() の推測メカニズムが、一致する Lexer と共に使用されます。

通常どおり、これらの関数へのキーワード引数は、作成された Lexer にオプションとして渡されます。

コマンドラインの使い方¶

pygmentize スクリプトを使用して、コマンドラインから Pygments を使用できます。

$ pygmentize test.py

は、Python ファイル test.py を ANSI エスケープシーケンス（別名ターミナルカラー）を使用してハイライト表示し、結果を標準出力に出力します。

HTML を出力するには、-f オプションを使用します。

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

test.py の HTML ハイライトバージョンを test.html ファイルに書き込みます。完全な HTML ドキュメントが必要な場合は、「full」オプションを使用してください。これは 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 はスタイル名です。

その他のオプションとテクニックについては、コマンドラインリファレンスを参照してください。

目次

前のトピック

次のトピック

このページ