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 

    11 This module supports two interface definitions, each with multiple

    12 implementations.  The *formatter* interface is used by the :class:`HTMLParser`

    13 class of the :mod:`htmllib` module, and the *writer* interface is required by

    14 the formatter interface.

    15 

    16 Formatter objects transform an abstract flow of formatting events into specific

    17 output events on writer objects.  Formatters manage several stack structures to

    18 allow various properties of a writer object to be changed and restored; writers

    19 need not be able to handle relative changes nor any sort of "change back"

    20 operation.  Specific writer properties which may be controlled via formatter

    21 objects are horizontal alignment, font, and left margin indentations.  A

    22 mechanism is provided which supports providing arbitrary, non-exclusive style

    23 settings to a writer as well.  Additional interfaces facilitate formatting

    24 events which are not reversible, such as paragraph separation.

    25 

    26 Writer objects encapsulate device interfaces.  Abstract devices, such as file

    27 formats, are supported as well as physical devices.  The provided

    28 implementations all work with abstract devices.  The interface makes available

    29 mechanisms for setting the properties which formatter objects manage and

    30 inserting data into the output.

    31 

    32 

    33 .. _formatter-interface:

    34 

    35 The Formatter Interface

    36 -----------------------

    37 

    38 Interfaces to create formatters are dependent on the specific formatter class

    39 being instantiated.  The interfaces described below are the required interfaces

    40 which all formatters must support once initialized.

    41 

    42 One 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 

    52 The 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 

   194 Formatter Implementations

   195 -------------------------

   196 

   197 Two implementations of formatter objects are provided by this module. Most

   198 applications 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 

   219 The Writer Interface

   220 --------------------

   221 

   222 Interfaces to create writers are dependent on the specific writer class being

   223 instantiated.  The interfaces described below are the required interfaces which

   224 all writers must support once initialized. Note that while most applications can

   225 use the :class:`AbstractFormatter` class as a formatter, the writer must

   226 typically 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 

   322 Writer Implementations

   323 ----------------------

   324 

   325 Three implementations of the writer object interface are provided as examples by

   326 this 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