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.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=None, maxcol=72) 345 346 Simple writer class which writes output on the file object passed in as *file* 347 or, if *file* is ``None``, 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 351
