34.1. formatter —通用输出格式

该模块支持两个接口定义，每个接口定义都有多个实现。 * formatter 接口由htmllib模块的HTMLParser类使用，而 writer *接口则是 formatter 接口所必需的。

格式化程序对象将格式化事件的抽象流程转换为写入器对象上的特定输出事件。格式化程序 Management 几种堆栈结构，以允许更改和恢复 writer 对象的各种属性；作者无需处理相对变化，也无需进行任何“变回”操作。可以pass格式化程序对象控制的特定编写器属性为水平对齐，字体和左边界缩进。提供了一种机制，该机制还支持向 Writer 提供任意，非排他的样式设置。附加接口有助于格式化不可逆的事件，例如段落分隔。

编写器对象封装设备接口。支持抽象设备(例如文件格式)以及物理设备。所提供的实现均适用于抽象设备。该接口提供了用于设置格式化程序对象 Management 的属性以及将数据插入输出中的可用机制。

34.1.1. 格式化程序接口

创建格式化程序的接口取决于要实例化的特定格式化程序类。下述接口是所有格式化程序初始化后必须支持的必需接口。

在模块级别定义了一个数据元素：

• formatter. AS_IS
  • 可以在传递给以下所述的push_font()方法的字体规范中使用的值，或作为任何其他push_property()方法的新值。按下AS_IS值可以调用相应的pop_property()方法，而不必跟踪属性是否已更改。

为格式化程序实例对象定义了以下属性：

• formatter. writer

  • 格式化程序与之交互的 writer 实例。

• formatter. end_paragraph(空白)

  • 关闭所有打开的段落，并在下一个段落之前至少插入*空格。

• formatter. add_line_break ( )

  • 如果尚不存在，请添加一个硬断行。这不会破坏逻辑段落。

• formatter. add_hor_rule( *args ， * kw *)

  • 在输出中插入水平线。如果当前段落中有数据，则插入硬break，但逻辑段落未break。参数和关键字将传递给编写者的send_line_break()方法。

• formatter. add_flowing_data(* data *)

  • 提供应使用折叠的空格格式化的数据。执行空格折叠时，也应考虑来自对add_flowing_data()的先前调用和后续调用的空格。预计传递给此方法的数据将由输出设备进行字换行。请注意，由于需要依赖设备和字体信息，因此仍然必须由 writer 对象执行任何自动换行。

• formatter. add_literal_data(* data *)

  • 提供应原样传递给编写器的数据。空格(包括换行符和制表符)在* data *的值中被认为是合法的。

• formatter. add_label_data(* format ， counter *)

  • 插入一个标签，该标签应放置在当前左边距的左侧。这应该用于构造项目符号列表或编号列表。如果* format 值为字符串，则将其解释为 counter 的格式规范，该规范应为整数。格式化的结果将成为标签的值。如果 format *不是字符串，则直接用作标签值。标签值将作为唯一的参数传递给编写者的send_label_data()方法。非字符串标签值的解释取决于相关的编写器。

格式规范是字符串，将其与计数器值结合使用以计算标签值。格式字符串中的每个字符都将复制到标签值，同时识别出一些字符以指示对计数器值的转换。具体来说，字符'1'代表阿拉伯数字形式的计数器值格式器，字符'A'和'a'分别以大写和小写字母表示计数器值的字母表示，'I'和'i'代表罗马数字的计数器值的大写字母和大写字母。小写。请注意，字母和罗马变换要求计数器值大于零。

• formatter. flush_softspace ( )

  • 将从上一次对add_flowing_data()的调用中缓冲的所有未决空白发送到关联的 writer 对象。应该在对 writer 对象进行任何直接操作之前调用此方法。

• formatter. push_alignment(* align *)

  • 将新的 Route 设置推入 Route 堆栈。如果不需要更改，则可能为AS_IS。如果从先前的设置更改了对齐值，则使用* align *值调用编写器的new_alignment()方法。

• formatter. pop_alignment ( )

  • 恢复先前的对齐方式。

• formatter. push_font((size ， italic ， bold ， teletype))

  • 更改 writer 对象的部分或全部字体属性。未设置为AS_IS的属性将设置为传入的值，而其他属性则保持其当前设置。使用完全解析的字体规范调用编写者的new_font()方法。

• formatter. pop_font ( )

  • 恢复以前的字体。

• formatter. push_margin(保证金)

  • 将逻辑标记* margin *与新的缩进关联，将左边距缩进的数量增加一个。初始保证金水平为0。逻辑标签的更改值必须为真值； AS_IS以外的其他错误值不足以更改边距。

• formatter. pop_margin ( )

  • 恢复上一个边距。

• formatter. push_style(*样式)

  • 推送任意数量的任意样式规范。所有样式均按 Sequences 推送到样式堆栈中。表示整个堆栈(包括AS_IS个值)的 Tuples 被传递到 writer 的new_styles()方法。

• formatter. pop_style([* n = 1 *])

  • 弹出传递给push_style()的最后* n *个样式规范。表示修改后的堆栈(包括AS_IS个值)的 Tuples 传递给编写者的new_styles()方法。

• formatter. set_spacing(* spacing *)

  • 设置作者的间距样式。

• formatter. assert_line_data([* flag = 1 *])

  • 通知格式化程序已将数据带外添加到当前段落中。直接对作者进行操作时应使用此方法。如果编写器的操作在输出末尾产生了强行break，则可以将可选的* flag *参数设置为 false。

34.1.2. 格式化程序实现

该模块提供了两种格式对象的实现。大多数应用程序可以使用这些类之一，而无需修改或子类化。

• 类别 formatter. NullFormatter([Writer])

  • 不执行任何操作的格式化程序。如果Ellipsis* writer *，则会创建一个NullWriter实例。 NullFormatter实例不会调用 writer 的方法。如果实现 writer 接口，则实现应从此类继承，但无需继承任何实现。
• • class * formatter. AbstractFormatter(* writer *)
  • 标准格式化程序。此实现已证明对许多作者具有广泛的适用性，并且可以在大多数情况下直接使用。它已用于实现Function齐全的 www 浏览器。

34.1.3. Writer 界面

创建编写器的接口取决于要实例化的特定编写器类。下述接口是所有编写器初始化后必须支持的必需接口。请注意，尽管大多数应用程序都可以将AbstractFormatter类用作格式化程序，但通常必须由该应用程序提供 writer。

• writer. flush ( )

  • 刷新所有缓冲的输出或设备控制事件。

• writer. new_alignment(* align *)

  • 设置对齐方式。 * align 值可以是任何对象，但按惯例是字符串或None，其中None表示应使用作者的“首选”对齐方式。常规 align *值为'left'，'center'，'right'和'justify'。

• writer. new_font(* font *)

  • 设置字体样式。 * font *的值为None，表示应使用设备的默认字体，或者为(size, italic, bold, teletype)形式的 Tuples。 Size 是一个字符串，指示应使用的字体大小；特定字符串及其解释必须由应用程序定义。 * italic ， bold 和 teletype *值是布尔值，用于指定应使用哪些字体属性。

• writer. new_margin(* margin ， level *)

  • 将边距级别设置为整数* level ，将逻辑标记设置为 margin 。逻辑标记的解释由作者决定；逻辑标记值的唯一限制是，对于 level *的非零值，它不是虚假值。

• writer. new_spacing(* spacing *)

  • 将间距样式设置为* spacing *。

• writer. new_styles(* styles *)

  • 设置其他样式。 * styles *值是任意值的 Tuples；值AS_IS应该被忽略。 * styles *Tuples 可以根据应用程序和编写器实现的要求解释为集合或堆栈。

• writer. send_line_break ( )

  • break当前行。

• writer. send_paragraph(空白)

  • 产生至少* blankline *空白行或等效行的段落分隔。 * blankline *值将是一个整数。请注意，如果需要换行，实现将在此调用之前收到对send_line_break()的调用。此方法不应包括结束段落的最后一行。它仅负责段落之间的垂直间距。

• writer. send_hor_rule( *args ， * kw *)

  • 在输出设备上显示水平线。此方法的参数完全是特定于应用程序和作者的，应谨慎解释。该方法实现可以假定已经passsend_line_break()发出了换行符。

• writer. send_flowing_data(* data *)

  • 输出字符数据，可以根据需要将其包装和重新排字。在对该方法的任何调用序列中，作者可以假定多个空白字符的范围已折叠为单个空格字符。

• writer. send_literal_data(* data *)

  • 输出已经格式化以显示的字符数据。通常，应将其解释为意味着应保留换行符指示的换行符，并且不应引入新的换行符。与提供给send_formatted_data()界面的数据不同，该数据可能包含嵌入的换行符和制表符。

• writer. send_label_data(* data *)

  • 如有可能，将* data *设置在当前左边距的左侧。 * data *的值不受限制；非字符串值的处理完全取决于应用程序和作者。仅在行的开头调用此方法。

34.1.4. Writer 实现

此模块提供了 writer 对象接口的三种实现方式作为示例。大多数应用程序将需要从NullWriter类派生新的 writer 类。

• 类别 formatter. NullWriter

  • 只提供接口定义的编写器；不会对任何方法采取任何措施。这应该是所有不需要继承任何实现方法的编写器的 Base Class。

• 类别 formatter. AbstractWriter

  • 可以用于调试格式化程序的编写器，但没有太多其他用途。每种方法都简单地pass在标准输出上打印其名称和参数来语句自己。
• • class * formatter. DumbWriter(* file = None ， maxcol = 72 *)
  • 简单编写器类，用于将输出写入以* file 传递的文件对象，或者如果 file 为None，则将其写入标准输出。输出仅被字包装为 maxcol *指定的列数。此类适合于重排段落序列。