diff options
Diffstat (limited to 'sys/src/cmd/python/Doc/lib/libformatter.tex')
| -rw-r--r-- | sys/src/cmd/python/Doc/lib/libformatter.tex | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/sys/src/cmd/python/Doc/lib/libformatter.tex b/sys/src/cmd/python/Doc/lib/libformatter.tex new file mode 100644 index 000000000..d7c5a6b83 --- /dev/null +++ b/sys/src/cmd/python/Doc/lib/libformatter.tex @@ -0,0 +1,329 @@ +\section{\module{formatter} --- + Generic output formatting} + +\declaremodule{standard}{formatter} +\modulesynopsis{Generic output formatter and device interface.} + + + +This module supports two interface definitions, each with multiple +implementations. The \emph{formatter} interface is used by the +\class{HTMLParser} class of the \refmodule{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 \label{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 whitespace. +Whitespace from preceding 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 \label{formatter-impls}} + +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 \label{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 values 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 equivalent. The \var{blankline} value will be an +integer. Note that the implementation will receive a call to +\method{send_line_break()} before this call if a line break is needed; +this method should not include ending the last line of the paragraph. +It is only responsible for vertical spacing between paragraphs. +\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 \label{writer-impls}} + +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} |