##
12.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 引数を偽に設定することができます。