331 lines
13 KiB
TeX
331 lines
13 KiB
TeX
\section{Standard Module \sectcode{formatter}}
|
|
\label{module-formatter}
|
|
\stmodindex{formatter}
|
|
|
|
\renewcommand{\indexsubitem}{(in module formatter)}
|
|
|
|
This module supports two interface definitions, each with mulitple
|
|
implementations. The \emph{formatter} interface is used by the
|
|
\code{HTMLParser} class of the \code{htmllib} module, and the
|
|
\emph{writer} interface is required by the formatter interface.
|
|
|
|
Formatter objects transform an abstract flow of formatting events into
|
|
specific output events on writer objects. Formatters manage several
|
|
stack structures to allow various properties of a writer object to be
|
|
changed and restored; writers need not be able to handle relative
|
|
changes nor any sort of ``change back'' operation. Specific writer
|
|
properties which may be controlled via formatter objects are
|
|
horizontal alignment, font, and left margin indentations. A mechanism
|
|
is provided which supports providing arbitrary, non-exclusive style
|
|
settings to a writer as well. Additional interfaces facilitate
|
|
formatting events which are not reversible, such as paragraph
|
|
separation.
|
|
|
|
Writer objects encapsulate device interfaces. Abstract devices, such
|
|
as file formats, are supported as well as physical devices. The
|
|
provided implementations all work with abstract devices. The
|
|
interface makes available mechanisms for setting the properties which
|
|
formatter objects manage and inserting data into the output.
|
|
|
|
|
|
\subsection{The Formatter Interface}
|
|
|
|
Interfaces to create formatters are dependent on the specific
|
|
formatter class being instantiated. The interfaces described below
|
|
are the required interfaces which all formatters must support once
|
|
initialized.
|
|
|
|
One data element is defined at the module level:
|
|
|
|
\begin{datadesc}{AS_IS}
|
|
Value which can be used in the font specification passed to the
|
|
\code{push_font()} method described below, or as the new value to any
|
|
other \code{push_\var{property}()} method. Pushing the \code{AS_IS}
|
|
value allows the corresponding \code{pop_\var{property}()} method to
|
|
be called without having to track whether the property was changed.
|
|
\end{datadesc}
|
|
|
|
The following attributes are defined for formatter instance objects:
|
|
|
|
\renewcommand{\indexsubitem}{(formatter object data)}
|
|
|
|
\begin{datadesc}{writer}
|
|
The writer instance with which the formatter interacts.
|
|
\end{datadesc}
|
|
|
|
|
|
\renewcommand{\indexsubitem}{(formatter object method)}
|
|
|
|
\begin{funcdesc}{end_paragraph}{blanklines}
|
|
Close any open paragraphs and insert at least \code{blanklines}
|
|
before the next paragraph.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_line_break}{}
|
|
Add a hard line break if one does not already exist. This does not
|
|
break the logical paragraph.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_hor_rule}{*args\, **kw}
|
|
Insert a horizontal rule in the output. A hard break is inserted if
|
|
there is data in the current paragraph, but the logical paragraph is
|
|
not broken. The arguments and keywords are passed on to the writer's
|
|
\code{send_line_break()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_flowing_data}{data}
|
|
Provide data which should be formatted with collapsed whitespaces.
|
|
Whitespace from preceeding and successive calls to
|
|
\code{add_flowing_data()} is considered as well when the whitespace
|
|
collapse is performed. The data which is passed to this method is
|
|
expected to be word-wrapped by the output device. Note that any
|
|
word-wrapping still must be performed by the writer object due to the
|
|
need to rely on device and font information.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_literal_data}{data}
|
|
Provide data which should be passed to the writer unchanged.
|
|
Whitespace, including newline and tab characters, are considered legal
|
|
in the value of \code{data}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_label_data}{format, counter}
|
|
Insert a label which should be placed to the left of the current left
|
|
margin. This should be used for constructing bulleted or numbered
|
|
lists. If the \code{format} value is a string, it is interpreted as a
|
|
format specification for \code{counter}, which should be an integer.
|
|
The result of this formatting becomes the value of the label; if
|
|
\code{format} is not a string it is used as the label value directly.
|
|
The label value is passed as the only argument to the writer's
|
|
\code{send_label_data()} method. Interpretation of non-string label
|
|
values is dependent on the associated writer.
|
|
|
|
Format specifications are strings which, in combination with a counter
|
|
value, are used to compute label values. Each character in the format
|
|
string is copied to the label value, with some characters recognized
|
|
to indicate a transform on the counter value. Specifically, the
|
|
character ``\code{1}'' represents the counter value formatter as an
|
|
arabic number, the characters ``\code{A}'' and ``\code{a}'' represent
|
|
alphabetic representations of the counter value in upper and lower
|
|
case, respectively, and ``\code{I}'' and ``\code{i}'' represent the
|
|
counter value in Roman numerals, in upper and lower case. Note that
|
|
the alphabetic and roman transforms require that the counter value be
|
|
greater than zero.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{flush_softspace}{}
|
|
Send any pending whitespace buffered from a previous call to
|
|
\code{add_flowing_data()} to the associated writer object. This
|
|
should be called before any direct manipulation of the writer object.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{push_alignment}{align}
|
|
Push a new alignment setting onto the alignment stack. This may be
|
|
\code{AS_IS} if no change is desired. If the alignment value is
|
|
changed from the previous setting, the writer's \code{new_alignment()}
|
|
method is called with the \code{align} value.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pop_alignment}{}
|
|
Restore the previous alignment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{push_font}{(size, italic, bold, teletype)}
|
|
Change some or all font properties of the writer object. Properties
|
|
which are not set to \code{AS_IS} are set to the values passed in
|
|
while others are maintained at their current settings. The writer's
|
|
\code{new_font()} method is called with the fully resolved font
|
|
specification.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pop_font}{}
|
|
Restore the previous font.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{push_margin}{margin}
|
|
Increase the number of left margin indentations by one, associating
|
|
the logical tag \code{margin} with the new indentation. The initial
|
|
margin level is \code{0}. Changed values of the logical tag must be
|
|
true values; false values other than \code{AS_IS} are not sufficient
|
|
to change the margin.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pop_margin}{}
|
|
Restore the previous margin.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{push_style}{*styles}
|
|
Push any number of arbitrary style specifications. All styles are
|
|
pushed onto the styles stack in order. A tuple representing the
|
|
entire stack, including \code{AS_IS} values, is passed to the writer's
|
|
\code{new_styles()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pop_style}{\optional{n\code{ = 1}}}
|
|
Pop the last \code{n} style specifications passed to
|
|
\code{push_style()}. A tuple representing the revised stack,
|
|
including \code{AS_IS} values, is passed to the writer's
|
|
\code{new_styles()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{set_spacing}{spacing}
|
|
Set the spacing style for the writer.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{assert_line_data}{\optional{flag\code{ = 1}}}
|
|
Inform the formatter that data has been added to the current paragraph
|
|
out-of-band. This should be used when the writer has been manipulated
|
|
directly. The optional \code{flag} argument can be set to false if
|
|
the writer manipulations produced a hard line break at the end of the
|
|
output.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Formatter Implementations}
|
|
|
|
Two implementations of formatter objects are provided by this module.
|
|
Most applications may use one of these classes without modification or
|
|
subclassing.
|
|
|
|
\renewcommand{\indexsubitem}{(in module formatter)}
|
|
|
|
\begin{funcdesc}{NullFormatter}{\optional{writer\code{ = None}}}
|
|
A formatter which does nothing. If \code{writer} is omitted, a
|
|
\code{NullWriter} instance is created. No methods of the writer are
|
|
called by \code{NullWriter} instances. Implementations should inherit
|
|
from this class if implementing a writer interface but don't need to
|
|
inherit any implementation.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{AbstractFormatter}{writer}
|
|
The standard formatter. This implementation has demonstrated wide
|
|
applicability to many writers, and may be used directly in most
|
|
circumstances. It has been used to implement a full-featured
|
|
world-wide web browser.
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
\subsection{The Writer Interface}
|
|
|
|
Interfaces to create writers are dependent on the specific writer
|
|
class being instantiated. The interfaces described below are the
|
|
required interfaces which all writers must support once initialized.
|
|
Note that while most applications can use the \code{AbstractFormatter}
|
|
class as a formatter, the writer must typically be provided by the
|
|
application.
|
|
|
|
\renewcommand{\indexsubitem}{(writer object method)}
|
|
|
|
\begin{funcdesc}{flush}{}
|
|
Flush any buffered output or device control events.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{new_alignment}{align}
|
|
Set the alignment style. The \code{align} value can be any object,
|
|
but by convention is a string or \code{None}, where \code{None}
|
|
indicates that the writer's ``preferred'' alignment should be used.
|
|
Conventional \code{align} values are \code{'left'}, \code{'center'},
|
|
\code{'right'}, and \code{'justify'}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{new_font}{font}
|
|
Set the font style. The value of \code{font} will be \code{None},
|
|
indicating that the device's default font should be used, or a tuple
|
|
of the form (\var{size}, \var{italic}, \var{bold}, \var{teletype}).
|
|
Size will be a string indicating the size of font that should be used;
|
|
specific strings and their interpretation must be defined by the
|
|
application. The \var{italic}, \var{bold}, and \var{teletype} values
|
|
are boolean indicators specifying which of those font attributes
|
|
should be used.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{new_margin}{margin, level}
|
|
Set the margin level to the integer \code{level} and the logical tag
|
|
to \code{margin}. Interpretation of the logical tag is at the
|
|
writer's discretion; the only restriction on the value of the logical
|
|
tag is that it not be a false value for non-zero values of
|
|
\code{level}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{new_spacing}{spacing}
|
|
Set the spacing style to \code{spacing}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{new_styles}{styles}
|
|
Set additional styles. The \code{styles} value is a tuple of
|
|
arbitrary values; the value \code{AS_IS} should be ignored. The
|
|
\code{styles} tuple may be interpreted either as a set or as a stack
|
|
depending on the requirements of the application and writer
|
|
implementation.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{send_line_break}{}
|
|
Break the current line.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{send_paragraph}{blankline}
|
|
Produce a paragraph separation of at least \code{blankline} blank
|
|
lines, or the equivelent. The \code{blankline} value will be an
|
|
integer.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{send_hor_rule}{*args\, **kw}
|
|
Display a horizontal rule on the output device. The arguments to this
|
|
method are entirely application- and writer-specific, and should be
|
|
interpreted with care. The method implementation may assume that a
|
|
line break has already been issued via \code{send_line_break()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{send_flowing_data}{data}
|
|
Output character data which may be word-wrapped and re-flowed as
|
|
needed. Within any sequence of calls to this method, the writer may
|
|
assume that spans of multiple whitespace characters have been
|
|
collapsed to single space characters.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{send_literal_data}{data}
|
|
Output character data which has already been formatted
|
|
for display. Generally, this should be interpreted to mean that line
|
|
breaks indicated by newline characters should be preserved and no new
|
|
line breaks should be introduced. The data may contain embedded
|
|
newline and tab characters, unlike data provided to the
|
|
\code{send_formatted_data()} interface.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{send_label_data}{data}
|
|
Set \code{data} to the left of the current left margin, if possible.
|
|
The value of \code{data} is not restricted; treatment of non-string
|
|
values is entirely application- and writer-dependent. This method
|
|
will only be called at the beginning of a line.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Writer Implementations}
|
|
|
|
Three implementations of the writer object interface are provided as
|
|
examples by this module. Most applications will need to derive new
|
|
writer classes from the \code{NullWriter} class.
|
|
|
|
\renewcommand{\indexsubitem}{(in module formatter)}
|
|
|
|
\begin{funcdesc}{NullWriter}{}
|
|
A writer which only provides the interface definition; no actions are
|
|
taken on any methods. This should be the base class for all writers
|
|
which do not need to inherit any implementation methods.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{AbstractWriter}{}
|
|
A writer which can be used in debugging formatters, but not much
|
|
else. Each method simply announces itself by printing its name and
|
|
arguments on standard output.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{DumbWriter}{\optional{file\code{ = None}\optional{\, maxcol\code{ = 72}}}}
|
|
Simple writer class which writes output on the file object passed in
|
|
as \code{file} or, if \code{file} is omitted, on standard output. The
|
|
output is simply word-wrapped to the number of columns specified by
|
|
\code{maxcol}. This class is suitable for reflowing a sequence of
|
|
paragraphs.
|
|
\end{funcdesc}
|