| \section{Standard Module \sectcode{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: |
| |
| \begin{datadesc}{writer} |
| The writer instance with which the formatter interacts. |
| \end{datadesc} |
| |
| |
| \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} |
| |
| \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. |
| \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. |
| \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. |
| |
| \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} |
| |
| \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 accounces 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} |