33.1.1 formatter インタフェース

formatter を作成するためのインタフェースは、インスタンス化しようとする個々の formatter クラスに依存します。以下で解説するのは、インスタンス化された全ての formatter がサポートしなければならないインタフェースです。

モジュールレベルではデータ要素を一つ定義しています:

AS_IS: 後に述べる push_font() メソッドでフォント指定をする時に使える値です。また、その他の push_property() メソッドの新しい値として使うことができます。
AS_IS の値をスタックに置くと、どのプロパティが変更されたかの追跡を行わずに、対応する pop_property() メソッドが呼び出されるようになります。

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

writer: formatter とやり取りを行う writer インスタンスです。

end_paragraph( blanklines): 開かれている段落があれば閉じ、次の段落との間に少なくとも blanklines が挿入されるようにします。

add_line_break( ): 強制改行挿入します。既に強制改行がある場合は挿入しません。論理的な段落は中断しません。

add_hor_rule( *args, **kw): 出力に水平罫線を挿入します。現在の段落に何らかのデータがある場合、強制改行が挿入されますが、論理的な段落は中断しません。引数とキーワードは writer の send_line_break() メソッドに渡されます。

add_flowing_data( data): 空白を折りたたんで書式化しなければならないデータを提供します。空白の折りたたみでは、直前や直後の add_flowing_data 呼び出しに入っている空白も考慮されます。このメソッドに渡されたデータは出力デバイスで行末の折り返し (word-wrap) されるものと想定されています。出力デバイスでの要求やフォント情報に応じて、writer オブジェクトでも何らかの行末折り返しが行われなければならないので注意してください。

add_literal_data( data): 変更を加えずに writer に渡さなければならないデータを提供します。改行およびタブを含む空白を data の値にしても問題ありません。

add_label_data( format, counter)

現在の左マージン位置の左側に配置されるラベルを挿入します。このラベルは箇条書き、数字つき箇条書きの書式を構築する際に使われます。 format の値が文字列の場合、整数の値 counter の書式指定として解釈されます。

format の値が文字列の場合、整数の値をとる counter の書式化指定として解釈されます。書式化された文字列はラベルの値になります; format が文字列でない場合、ラベルの値として直接使われます。ラベルの値は writer の send_label_data() メソッドの唯一の引数として渡されます。非文字列のラベル値をどう解釈するかは関連付けられた writer に依存します。

書式化指定は文字列からなり、 counter の値と合わせてラベルの値を算出するために使われます。書式文字列の各文字はラベル値にコピーされます。このときいくつかの文字は counter 値を変換を指すものとして認識されます。特に、文字 "1" はアラビア数字の counter 値を表し、 "A" と "a" はそれぞれ大文字および小文字のアルファベットによる counter 値を表し、"I" と "i" はそれぞれ大文字および小文字のローマ数字による counter 値を表します。アルファベットおよびローマ字数字への変換の際には、counter の値はゼロ以上である必要があるので注意してください。

flush_softspace( ): 以前の add_flowing_data() 呼び出しでバッファされている出力待ちの空白を、関連付けられている writer オブジェクトに送信します。このメソッドは writer オブジェクトに対するあらゆる直接操作の前に呼び出さなければなりません。

push_alignment( align): 新たな字揃え (alignment) 設定を字揃えスタックの上にプッシュします。変更を行いたくない場合には AS_IS にすることができます。字揃え設定値が以前の設定から変更された場合、writer の new_alignment() メソッドが align の値と共に呼び出されます。

pop_alignment( ): 以前の字揃え設定を復元します。

push_font( (size, italic, bold, teletype)): writer オブジェクトのフォントプロパティのうち、一部または全てを変更します。 AS_IS に設定されていないプロパティは引数で渡された値に設定され、その他の値は現在の設定を維持します。writer の new_font() メソッドは完全に設定解決されたフォント指定で呼び出されます。

pop_font( ): 以前のフォント設定を復元します。

push_margin( margin): 左マージンのインデント数を一つ増やし、論理タグ margin を新たなインデントに関連付けます。マージンレベルの初期値は 0 です。変更された論理タグの値は真値とならなければなりません; AS_IS 以外の偽の値はマージンの変更としては不適切です。

pop_margin( ): 以前のマージン設定を復元します。

push_style( *styles): 任意のスタイル指定をスタックにプッシュします。全てのスタイルはスタイルスタックに順番にプッシュされます。AS_IS 値を含み、スタック全体を表すタプルは writer の new_styles() メソッドに渡されます。

pop_style( [n = 1]): push_style() に渡された最新 n 個のスタイル指定をポップします。AS_IS 値を含み、変更されたスタックを表すタプルは writer の new_styles() メソッドに渡されます。

set_spacing( spacing): writer の割り付けスタイル (spacing style) を設定します。

assert_line_data( [flag = 1]): 現在の段落にデータが予期せず追加されたことを formatter に知らせます。このメソッドは writer を直接操作した際に使わなければなりません。 writer 操作の結果、出力の末尾が強制改行となった場合、オプションの flag 引数を偽に設定することができます。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。