mirror of https://github.com/python/cpython.git
324 lines
13 KiB
TeX
324 lines
13 KiB
TeX
\section{Standard Module \sectcode{formatter}}
|
|
\label{module-formatter}
|
|
\stmodindex{formatter}
|
|
|
|
|
|
This module supports two interface definitions, each with mulitple
|
|
implementations. The \emph{formatter} interface is used by the
|
|
\class{HTMLParser} class of the \module{htmllib} module, and the
|
|
\emph{writer} interface is required by the formatter interface.
|
|
\withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
|
|
|
|
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:
|
|
|
|
|
|
\begin{memberdesc}[formatter]{writer}
|
|
The writer instance with which the formatter interacts.
|
|
\end{memberdesc}
|
|
|
|
|
|
\begin{methoddesc}[formatter]{end_paragraph}{blanklines}
|
|
Close any open paragraphs and insert at least \var{blanklines}
|
|
before the next paragraph.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{add_line_break}{}
|
|
Add a hard line break if one does not already exist. This does not
|
|
break the logical paragraph.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{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
|
|
\method{send_line_break()} method.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{add_flowing_data}{data}
|
|
Provide data which should be formatted with collapsed whitespaces.
|
|
Whitespace from preceeding and successive calls to
|
|
\method{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{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{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 \var{data}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{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 \var{format} value is a string, it is interpreted as a
|
|
format specification for \var{counter}, which should be an integer.
|
|
The result of this formatting becomes the value of the label; if
|
|
\var{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
|
|
\method{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 \character{1} represents the counter value formatter as an
|
|
arabic number, the characters \character{A} and \character{a}
|
|
represent alphabetic representations of the counter value in upper and
|
|
lower case, respectively, and \character{I} and \character{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{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{flush_softspace}{}
|
|
Send any pending whitespace buffered from a previous call to
|
|
\method{add_flowing_data()} to the associated writer object. This
|
|
should be called before any direct manipulation of the writer object.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{push_alignment}{align}
|
|
Push a new alignment setting onto the alignment stack. This may be
|
|
\constant{AS_IS} if no change is desired. If the alignment value is
|
|
changed from the previous setting, the writer's \method{new_alignment()}
|
|
method is called with the \var{align} value.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{pop_alignment}{}
|
|
Restore the previous alignment.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
|
|
Change some or all font properties of the writer object. Properties
|
|
which are not set to \constant{AS_IS} are set to the values passed in
|
|
while others are maintained at their current settings. The writer's
|
|
\method{new_font()} method is called with the fully resolved font
|
|
specification.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{pop_font}{}
|
|
Restore the previous font.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{push_margin}{margin}
|
|
Increase the number of left margin indentations by one, associating
|
|
the logical tag \var{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 \constant{AS_IS} are not
|
|
sufficient to change the margin.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{pop_margin}{}
|
|
Restore the previous margin.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{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 \constant{AS_IS} values, is passed to the
|
|
writer's \method{new_styles()} method.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
|
|
Pop the last \var{n} style specifications passed to
|
|
\method{push_style()}. A tuple representing the revised stack,
|
|
including \constant{AS_IS} values, is passed to the writer's
|
|
\method{new_styles()} method.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{set_spacing}{spacing}
|
|
Set the spacing style for the writer.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[formatter]{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 \var{flag} argument can be set to false if
|
|
the writer manipulations produced a hard line break at the end of the
|
|
output.
|
|
\end{methoddesc}
|
|
|
|
|
|
\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.
|
|
|
|
\begin{classdesc}{NullFormatter}{\optional{writer}}
|
|
A formatter which does nothing. If \var{writer} is omitted, a
|
|
\class{NullWriter} instance is created. No methods of the writer are
|
|
called by \class{NullFormatter} instances. Implementations should
|
|
inherit from this class if implementing a writer interface but don't
|
|
need to inherit any implementation.
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{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{classdesc}
|
|
|
|
|
|
|
|
\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
|
|
\class{AbstractFormatter} class as a formatter, the writer must
|
|
typically be provided by the application.
|
|
|
|
|
|
\begin{methoddesc}[writer]{flush}{}
|
|
Flush any buffered output or device control events.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{new_alignment}{align}
|
|
Set the alignment style. The \var{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 \var{align} values are \code{'left'}, \code{'center'},
|
|
\code{'right'}, and \code{'justify'}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{new_font}{font}
|
|
Set the font style. The value of \var{font} will be \code{None},
|
|
indicating that the device's default font should be used, or a tuple
|
|
of the form \code{(}\var{size}, \var{italic}, \var{bold},
|
|
\var{teletype}\code{)}. 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{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{new_margin}{margin, level}
|
|
Set the margin level to the integer \var{level} and the logical tag
|
|
to \var{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
|
|
\var{level}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{new_spacing}{spacing}
|
|
Set the spacing style to \var{spacing}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{new_styles}{styles}
|
|
Set additional styles. The \var{styles} value is a tuple of
|
|
arbitrary values; the value \constant{AS_IS} should be ignored. The
|
|
\var{styles} tuple may be interpreted either as a set or as a stack
|
|
depending on the requirements of the application and writer
|
|
implementation.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{send_line_break}{}
|
|
Break the current line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{send_paragraph}{blankline}
|
|
Produce a paragraph separation of at least \var{blankline} blank
|
|
lines, or the equivelent. The \var{blankline} value will be an
|
|
integer.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{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 \method{send_line_break()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{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{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{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
|
|
\method{send_formatted_data()} interface.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[writer]{send_label_data}{data}
|
|
Set \var{data} to the left of the current left margin, if possible.
|
|
The value of \var{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{methoddesc}
|
|
|
|
|
|
\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 \class{NullWriter} class.
|
|
|
|
\begin{classdesc}{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{classdesc}
|
|
|
|
\begin{classdesc}{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{classdesc}
|
|
|
|
\begin{classdesc}{DumbWriter}{\optional{file\optional{, maxcol\code{ = 72}}}}
|
|
Simple writer class which writes output on the file object passed in
|
|
as \var{file} or, if \var{file} is omitted, on standard output. The
|
|
output is simply word-wrapped to the number of columns specified by
|
|
\var{maxcol}. This class is suitable for reflowing a sequence of
|
|
paragraphs.
|
|
\end{classdesc}
|