/Doc/library/formatter.rst

  1
  2:mod:`formatter` --- Generic output formatting
  3==============================================
  4
  5.. module:: formatter
  6   :synopsis: Generic output formatter and device interface.
  7
  8
  9.. index:: single: HTMLParser (class in htmllib)
 10
 11This module supports two interface definitions, each with multiple
 12implementations.  The *formatter* interface is used by the :class:`HTMLParser`
 13class of the :mod:`htmllib` module, and the *writer* interface is required by
 14the formatter interface.
 15
 16Formatter objects transform an abstract flow of formatting events into specific
 17output events on writer objects.  Formatters manage several stack structures to
 18allow various properties of a writer object to be changed and restored; writers
 19need not be able to handle relative changes nor any sort of "change back"
 20operation.  Specific writer properties which may be controlled via formatter
 21objects are horizontal alignment, font, and left margin indentations.  A
 22mechanism is provided which supports providing arbitrary, non-exclusive style
 23settings to a writer as well.  Additional interfaces facilitate formatting
 24events which are not reversible, such as paragraph separation.
 25
 26Writer objects encapsulate device interfaces.  Abstract devices, such as file
 27formats, are supported as well as physical devices.  The provided
 28implementations all work with abstract devices.  The interface makes available
 29mechanisms for setting the properties which formatter objects manage and
 30inserting data into the output.
 31
 32
 33.. _formatter-interface:
 34
 35The Formatter Interface
 36-----------------------
 37
 38Interfaces to create formatters are dependent on the specific formatter class
 39being instantiated.  The interfaces described below are the required interfaces
 40which all formatters must support once initialized.
 41
 42One data element is defined at the module level:
 43
 44
 45.. data:: AS_IS
 46
 47   Value which can be used in the font specification passed to the ``push_font()``
 48   method described below, or as the new value to any other ``push_property()``
 49   method.  Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
 50   method to be called without having to track whether the property was changed.
 51
 52The following attributes are defined for formatter instance objects:
 53
 54
 55.. attribute:: formatter.writer
 56
 57   The writer instance with which the formatter interacts.
 58
 59
 60.. method:: formatter.end_paragraph(blanklines)
 61
 62   Close any open paragraphs and insert at least *blanklines* before the next
 63   paragraph.
 64
 65
 66.. method:: formatter.add_line_break()
 67
 68   Add a hard line break if one does not already exist.  This does not break the
 69   logical paragraph.
 70
 71
 72.. method:: formatter.add_hor_rule(*args, **kw)
 73
 74   Insert a horizontal rule in the output.  A hard break is inserted if there is
 75   data in the current paragraph, but the logical paragraph is not broken.  The
 76   arguments and keywords are passed on to the writer's :meth:`send_line_break`
 77   method.
 78
 79
 80.. method:: formatter.add_flowing_data(data)
 81
 82   Provide data which should be formatted with collapsed whitespace. Whitespace
 83   from preceding and successive calls to :meth:`add_flowing_data` is considered as
 84   well when the whitespace collapse is performed.  The data which is passed to
 85   this method is expected to be word-wrapped by the output device.  Note that any
 86   word-wrapping still must be performed by the writer object due to the need to
 87   rely on device and font information.
 88
 89
 90.. method:: formatter.add_literal_data(data)
 91
 92   Provide data which should be passed to the writer unchanged. Whitespace,
 93   including newline and tab characters, are considered legal in the value of
 94   *data*.
 95
 96
 97.. method:: formatter.add_label_data(format, counter)
 98
 99   Insert a label which should be placed to the left of the current left margin.
100   This should be used for constructing bulleted or numbered lists.  If the
101   *format* value is a string, it is interpreted as a format specification for
102   *counter*, which should be an integer. The result of this formatting becomes the
103   value of the label; if *format* is not a string it is used as the label value
104   directly. The label value is passed as the only argument to the writer's
105   :meth:`send_label_data` method.  Interpretation of non-string label values is
106   dependent on the associated writer.
107
108   Format specifications are strings which, in combination with a counter value,
109   are used to compute label values.  Each character in the format string is copied
110   to the label value, with some characters recognized to indicate a transform on
111   the counter value.  Specifically, the character ``'1'`` represents the counter
112   value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
113   represent alphabetic representations of the counter value in upper and lower
114   case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
115   numerals, in upper and lower case.  Note that the alphabetic and roman
116   transforms require that the counter value be greater than zero.
117
118
119.. method:: formatter.flush_softspace()
120
121   Send any pending whitespace buffered from a previous call to
122   :meth:`add_flowing_data` to the associated writer object.  This should be called
123   before any direct manipulation of the writer object.
124
125
126.. method:: formatter.push_alignment(align)
127
128   Push a new alignment setting onto the alignment stack.  This may be
129   :const:`AS_IS` if no change is desired.  If the alignment value is changed from
130   the previous setting, the writer's :meth:`new_alignment` method is called with
131   the *align* value.
132
133
134.. method:: formatter.pop_alignment()
135
136   Restore the previous alignment.
137
138
139.. method:: formatter.push_font((size, italic, bold, teletype))
140
141   Change some or all font properties of the writer object.  Properties which are
142   not set to :const:`AS_IS` are set to the values passed in while others are
143   maintained at their current settings.  The writer's :meth:`new_font` method is
144   called with the fully resolved font specification.
145
146
147.. method:: formatter.pop_font()
148
149   Restore the previous font.
150
151
152.. method:: formatter.push_margin(margin)
153
154   Increase the number of left margin indentations by one, associating the logical
155   tag *margin* with the new indentation.  The initial margin level is ``0``.
156   Changed values of the logical tag must be true values; false values other than
157   :const:`AS_IS` are not sufficient to change the margin.
158
159
160.. method:: formatter.pop_margin()
161
162   Restore the previous margin.
163
164
165.. method:: formatter.push_style(*styles)
166
167   Push any number of arbitrary style specifications.  All styles are pushed onto
168   the styles stack in order.  A tuple representing the entire stack, including
169   :const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
170
171
172.. method:: formatter.pop_style([n=1])
173
174   Pop the last *n* style specifications passed to :meth:`push_style`.  A tuple
175   representing the revised stack, including :const:`AS_IS` values, is passed to
176   the writer's :meth:`new_styles` method.
177
178
179.. method:: formatter.set_spacing(spacing)
180
181   Set the spacing style for the writer.
182
183
184.. method:: formatter.assert_line_data([flag=1])
185
186   Inform the formatter that data has been added to the current paragraph
187   out-of-band.  This should be used when the writer has been manipulated
188   directly.  The optional *flag* argument can be set to false if the writer
189   manipulations produced a hard line break at the end of the output.
190
191
192.. _formatter-impls:
193
194Formatter Implementations
195-------------------------
196
197Two implementations of formatter objects are provided by this module. Most
198applications may use one of these classes without modification or subclassing.
199
200
201.. class:: NullFormatter([writer])
202
203   A formatter which does nothing.  If *writer* is omitted, a :class:`NullWriter`
204   instance is created.  No methods of the writer are called by
205   :class:`NullFormatter` instances.  Implementations should inherit from this
206   class if implementing a writer interface but don't need to inherit any
207   implementation.
208
209
210.. class:: AbstractFormatter(writer)
211
212   The standard formatter.  This implementation has demonstrated wide applicability
213   to many writers, and may be used directly in most circumstances.  It has been
214   used to implement a full-featured World Wide Web browser.
215
216
217.. _writer-interface:
218
219The Writer Interface
220--------------------
221
222Interfaces to create writers are dependent on the specific writer class being
223instantiated.  The interfaces described below are the required interfaces which
224all writers must support once initialized. Note that while most applications can
225use the :class:`AbstractFormatter` class as a formatter, the writer must
226typically be provided by the application.
227
228
229.. method:: writer.flush()
230
231   Flush any buffered output or device control events.
232
233
234.. method:: writer.new_alignment(align)
235
236   Set the alignment style.  The *align* value can be any object, but by convention
237   is a string or ``None``, where ``None`` indicates that the writer's "preferred"
238   alignment should be used. Conventional *align* values are ``'left'``,
239   ``'center'``, ``'right'``, and ``'justify'``.
240
241
242.. method:: writer.new_font(font)
243
244   Set the font style.  The value of *font* will be ``None``, indicating that the
245   device's default font should be used, or a tuple of the form ``(size,
246   italic, bold, teletype)``.  Size will be a string indicating the size of
247   font that should be used; specific strings and their interpretation must be
248   defined by the application.  The *italic*, *bold*, and *teletype* values are
249   Boolean values specifying which of those font attributes should be used.
250
251
252.. method:: writer.new_margin(margin, level)
253
254   Set the margin level to the integer *level* and the logical tag to *margin*.
255   Interpretation of the logical tag is at the writer's discretion; the only
256   restriction on the value of the logical tag is that it not be a false value for
257   non-zero values of *level*.
258
259
260.. method:: writer.new_spacing(spacing)
261
262   Set the spacing style to *spacing*.
263
264
265.. method:: writer.new_styles(styles)
266
267   Set additional styles.  The *styles* value is a tuple of arbitrary values; the
268   value :const:`AS_IS` should be ignored.  The *styles* tuple may be interpreted
269   either as a set or as a stack depending on the requirements of the application
270   and writer implementation.
271
272
273.. method:: writer.send_line_break()
274
275   Break the current line.
276
277
278.. method:: writer.send_paragraph(blankline)
279
280   Produce a paragraph separation of at least *blankline* blank lines, or the
281   equivalent.  The *blankline* value will be an integer.  Note that the
282   implementation will receive a call to :meth:`send_line_break` before this call
283   if a line break is needed;  this method should not include ending the last line
284   of the paragraph. It is only responsible for vertical spacing between
285   paragraphs.
286
287
288.. method:: writer.send_hor_rule(*args, **kw)
289
290   Display a horizontal rule on the output device.  The arguments to this method
291   are entirely application- and writer-specific, and should be interpreted with
292   care.  The method implementation may assume that a line break has already been
293   issued via :meth:`send_line_break`.
294
295
296.. method:: writer.send_flowing_data(data)
297
298   Output character data which may be word-wrapped and re-flowed as needed.  Within
299   any sequence of calls to this method, the writer may assume that spans of
300   multiple whitespace characters have been collapsed to single space characters.
301
302
303.. method:: writer.send_literal_data(data)
304
305   Output character data which has already been formatted for display.  Generally,
306   this should be interpreted to mean that line breaks indicated by newline
307   characters should be preserved and no new line breaks should be introduced.  The
308   data may contain embedded newline and tab characters, unlike data provided to
309   the :meth:`send_formatted_data` interface.
310
311
312.. method:: writer.send_label_data(data)
313
314   Set *data* to the left of the current left margin, if possible. The value of
315   *data* is not restricted; treatment of non-string values is entirely
316   application- and writer-dependent.  This method will only be called at the
317   beginning of a line.
318
319
320.. _writer-impls:
321
322Writer Implementations
323----------------------
324
325Three implementations of the writer object interface are provided as examples by
326this module.  Most applications will need to derive new writer classes from the
327:class:`NullWriter` class.
328
329
330.. class:: NullWriter()
331
332   A writer which only provides the interface definition; no actions are taken on
333   any methods.  This should be the base class for all writers which do not need to
334   inherit any implementation methods.
335
336
337.. class:: AbstractWriter()
338
339   A writer which can be used in debugging formatters, but not much else.  Each
340   method simply announces itself by printing its name and arguments on standard
341   output.
342
343
344.. class:: DumbWriter([file[, maxcol=72]])
345
346   Simple writer class which writes output on the file object passed in as *file*
347   or, if *file* is omitted, on standard output.  The output is simply word-wrapped
348   to the number of columns specified by *maxcol*.  This class is suitable for
349   reflowing a sequence of paragraphs.
350