11.12.1 Formatterのインタフェース

11.12.1 Formatter のインタフェース

formatterを生成するインタフェースはインスタンスが生成された特定のformatterに依存しています。以下に示すインタフェースは全てのformatterが最初から提供しなくてはならないインタフェースです。

データ要素はモジュールレベルで定義されます:

AS_IS: フォントを表現するのに使われる値であり、この値は以下で説明してあるpush_font()メソッドまたは push_property ()メソッドに新しい値として渡されます。 AS_ISの値をpush_property()を呼んで設定したら、属性の変更に関わらず、後からpop_property()メソッドを呼ばなくてはなりません。

以下の属性はformatterインスタンスオブジェクトとして定義されています:

end_paragraph (blanklines): 全てのパラグラフを閉じます。次のパラグラフの前に少なくとも値(blanklines)の数の空行を挿入します。

add_hor_rule (*args, **kw): 出力に横方向の位置のルールを挿入します。現在のパラグラフにデータがあるなら、hard breakを挿入し、そうでなければ、論理パラグラフはbreakしません。引数とキーワードはwriterのsend_line_break ()メソッドに渡します。

add_flowing_data (data): collapsed(つぶれた？）whitespaceで書式化されたデータを提供します。 whitespaceのcollapseが実行されるとき、前述のwhitespaceとadd_flowing_data()の連続した呼びだしは同様に考慮されています。このメソッドに渡されるデータは出力デバイスにword-wrappedになると予想されます。すべてのword-wrappedはデバイスとフォント情報に依存するためwriterオブジェクトで実行されなくてはなりません。

add_literal_data (data): writerへ変更しないでデータを渡します。引数で指定されたdataの中に改行やタブを含むwhitespaceも正常に処理します。

add_label_data (format, counter): 現在の左マージンの左にラベルを配置するよう挿入します。これは中丸や番号のリストを作成するのに使用します。引数のformatが文字列である場合、引数のcounterに対する書式として逐次実行します。引数のcounterは整数でなくてはなりません。引数のformatが文字列でない場合、この書式化の結果を直接ラベルとして使用します。ラベルはwriterのsend_label_data()メソッドに１つだけの引数として渡します。文字列でないラベルのインプリメントは連携するwriterに依存します。
書式は引数のcounterと組み合わせた文字列のラベルを生成するのに使用します。 formatの文字列に含まれるそれぞれの文字はラベルにコピーします。いくつかの文字はcounterの変換を示すものと解釈します。特に、文字の"1"はアラビア数字としてcounterのformatterを示し、文字"A"と"a"はそれぞれ大文字と小文字の場合にcounterのアルファベットの表現を示し、文字"I"と"i"は大文字と小文字の場合にcounterのローマ数字を示します。アルファベットとローマ数字の変換は０以上のcounterでなくてはなりません。

flush_softspace (): 以前の呼びだしでadd_flowing_data ()にバッファリングされているwhitespaceを連携するwriterオブジェクトに送ります。 writerオブジェクトで直接操作する前にまず最初に呼び出さなくてはなりません。

push_alignment (align): アラインメントスタックに新しいアラインメントを設定します。変更が必要ない場合、AS_ISです。アラインメントを以前の設定から変えたい場合はwriterのnew_alignment ()メソッドを一緒に呼び出します。

push_font ((size, italic, bold, teletype)): writerオブジェクトのいくつかもしくは全てのフォント属性を変更します。 AS_ISに設定されていない属性は他で現状の設定を変更しているとき渡される値に設定します。 writerのnew_fontメソッドは完全に解決されたフォント表現で呼び出します。

push_margin (margin): 左のマージンのインデントの数をmarginで指定された量増やします。新しいインデントは論理タグmarginに関係します。最初のマージンレベルは０です。論理タグの変更された値は正しい値でなくてはなりません。誤った値ではマージンを変更できず、AS_ISとなります。

push_style (*styles): 任意の型の表現をいくらでも積み上げられます。全ての型は順番に型のスタックに積み上げられます。タプルはAS_ISの値を含む完全なスタックをあらわし、writerのnew_styles ()メソッドに渡されます。

pop_style ([n = 1]): 最後のpush_style ()に渡されたn個の型表現を戻します。タプルの表現はAS_ISを含むスタックを変えます。それはwriterのnew_styles ()メソッドに渡されます。

assert_line_data ([flag = 1]): 現在のパラグラフの外にformatterによってデータが追加されたことを通知します。 writerが直接操作するとき使用します。出力の終わりにhard line breakをwriterが提供する場合引数のflagはFalseに設定します。

guido@python.org