home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / !ibrowse / files / pylibi-7 (.txt) < prev    next >
GNU Info File  |  1996-11-14  |  52KB  |  903 lines
  1. This is Info file pylibi, produced by Makeinfo-1.55 from the input file
  2. lib.texi.
  3. This file describes the built-in types, exceptions and functions and the
  4. standard modules that come with the Python system.  It assumes basic
  5. knowledge about the Python language.  For an informal introduction to
  6. the language, see the Python Tutorial.  The Python Reference Manual
  7. gives a more formal definition of the language.  (These manuals are not
  8. yet available in INFO or Texinfo format.)
  9. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The
  10. Netherlands.
  11. All Rights Reserved
  12. Permission to use, copy, modify, and distribute this software and its
  13. documentation for any purpose and without fee is hereby granted,
  14. provided that the above copyright notice appear in all copies and that
  15. both that copyright notice and this permission notice appear in
  16. supporting documentation, and that the names of Stichting Mathematisch
  17. Centrum or CWI or Corporation for National Research Initiatives or CNRI
  18. not be used in advertising or publicity pertaining to distribution of
  19. the software without specific, written prior permission.
  20. While CWI is the initial source for this software, a modified version
  21. is made available by the Corporation for National Research Initiatives
  22. (CNRI) at the Internet address ftp://ftp.python.org.
  23. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  24. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  25. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  26. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  27. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  28. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  29. ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  30. THIS SOFTWARE.
  31. File: pylibi,  Node: formatter,  Next: rfc822,  Prev: htmllib,  Up: Internet and WWW
  32. Standard Module `formatter'
  33. ===========================
  34. This module supports two interface definitions, each with mulitple
  35. implementations.  The *formatter* interface is used by the `HTMLParser'
  36. class of the `htmllib' module, and the *writer* interface is required
  37. by the formatter interface.
  38. Formatter objects transform an abstract flow of formatting events into
  39. specific output events on writer objects.  Formatters manage several
  40. stack structures to allow various properties of a writer object to be
  41. changed and restored; writers need not be able to handle relative
  42. changes nor any sort of "change back" operation.  Specific writer
  43. properties which may be controlled via formatter objects are horizontal
  44. alignment, font, and left margin indentations.  A mechanism is provided
  45. which supports providing arbitrary, non-exclusive style settings to a
  46. writer as well.  Additional interfaces facilitate formatting events
  47. which are not reversible, such as paragraph separation.
  48. Writer objects encapsulate device interfaces.  Abstract devices, such
  49. as file formats, are supported as well as physical devices.  The
  50. provided implementations all work with abstract devices.  The interface
  51. makes available mechanisms for setting the properties which formatter
  52. objects manage and inserting data into the output.
  53. * Menu:
  54. * The Formatter Interface::
  55. * Formatter Implementations::
  56. * The Writer Interface::
  57. * Writer Implementations::
  58. File: pylibi,  Node: The Formatter Interface,  Next: Formatter Implementations,  Prev: formatter,  Up: formatter
  59. The Formatter Interface
  60. -----------------------
  61. Interfaces to create formatters are dependent on the specific formatter
  62. class being instantiated.  The interfaces described below are the
  63. required interfaces which all formatters must support once initialized.
  64. One data element is defined at the module level:
  65.  - data of module formatter: AS_IS
  66.      Value which can be used in the font specification passed to the
  67.      `push_font()' method described below, or as the new value to any
  68.      other `push_PROPERTY()' method.  Pushing the `AS_IS' value allows
  69.      the corresponding `pop_PROPERTY()' method to be called without
  70.      having to track whether the property was changed.
  71. The following attributes are defined for formatter instance objects:
  72.  - data of formatter object data: writer
  73.      The writer instance with which the formatter interacts.
  74.  - Method on formatter object: end_paragraph (BLANKLINES)
  75.      Close any open paragraphs and insert at least `blanklines' before
  76.      the next paragraph.
  77.  - Method on formatter object: add_line_break ()
  78.      Add a hard line break if one does not already exist.  This does not
  79.      break the logical paragraph.
  80.  - Method on formatter object: add_hor_rule (*ARGS, **KW)
  81.      Insert a horizontal rule in the output.  A hard break is inserted
  82.      if there is data in the current paragraph, but the logical
  83.      paragraph is not broken.  The arguments and keywords are passed on
  84.      to the writer's `send_line_break()' method.
  85.  - Method on formatter object: add_flowing_data (DATA)
  86.      Provide data which should be formatted with collapsed whitespaces.
  87.      Whitespace from preceeding and successive calls to
  88.      `add_flowing_data()' is considered as well when the whitespace
  89.      collapse is performed.  The data which is passed to this method is
  90.      expected to be word-wrapped by the output device.  Note that any
  91.      word-wrapping still must be performed by the writer object due to
  92.      the need to rely on device and font information.
  93.  - Method on formatter object: add_literal_data (DATA)
  94.      Provide data which should be passed to the writer unchanged.
  95.      Whitespace, including newline and tab characters, are considered
  96.      legal in the value of `data'.
  97.  - Method on formatter object: add_label_data (FORMAT, COUNTER)
  98.      Insert a label which should be placed to the left of the current
  99.      left margin.  This should be used for constructing bulleted or
  100.      numbered lists.  If the `format' value is a string, it is
  101.      interpreted as a format specification for `counter', which should
  102.      be an integer.  The result of this formatting becomes the value of
  103.      the label; if `format' is not a string it is used as the label
  104.      value directly.  The label value is passed as the only argument to
  105.      the writer's `send_label_data()' method.  Interpretation of
  106.      non-string label values is dependent on the associated writer.
  107.      Format specifications are strings which, in combination with a
  108.      counter value, are used to compute label values.  Each character
  109.      in the format string is copied to the label value, with some
  110.      characters recognized to indicate a transform on the counter
  111.      value.  Specifically, the character "`1'" represents the counter
  112.      value formatter as an arabic number, the characters "`A'" and
  113.      "`a'" represent alphabetic representations of the counter value in
  114.      upper and lower case, respectively, and "`I'" and "`i'" represent
  115.      the counter value in Roman numerals, in upper and lower case.
  116.      Note that the alphabetic and roman transforms require that the
  117.      counter value be greater than zero.
  118.  - Method on formatter object: flush_softspace ()
  119.      Send any pending whitespace buffered from a previous call to
  120.      `add_flowing_data()' to the associated writer object.  This should
  121.      be called before any direct manipulation of the writer object.
  122.  - Method on formatter object: push_alignment (ALIGN)
  123.      Push a new alignment setting onto the alignment stack.  This may be
  124.      `AS_IS' if no change is desired.  If the alignment value is
  125.      changed from the previous setting, the writer's `new_alignment()'
  126.      method is called with the `align' value.
  127.  - Method on formatter object: pop_alignment ()
  128.      Restore the previous alignment.
  129.  - Method on formatter object: push_font ((SIZE, ITALIC, BOLD,
  130.           TELETYPE))
  131.      Change some or all font properties of the writer object.
  132.      Properties which are not set to `AS_IS' are set to the values
  133.      passed in while others are maintained at their current settings.
  134.      The writer's `new_font()' method is called with the fully resolved
  135.      font specification.
  136.  - Method on formatter object: pop_font ()
  137.      Restore the previous font.
  138.  - Method on formatter object: push_mar