home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / s / sgmllib < prev    next >
Encoding:
Text File  |  1996-11-14  |  9.0 KB  |  168 lines
  1. <TITLE>sgmllib -- Python library reference</TITLE>
  2. Next: <A HREF="../h/htmllib" TYPE="Next">htmllib</A>  
  3. Prev: <A HREF="../u/urlparse" TYPE="Prev">urlparse</A>  
  4. Up: <A HREF="../i/internet_and_www" TYPE="Up">Internet and WWW</A>  
  5. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  6. <H1>10.8. Standard Module <CODE>sgmllib</CODE></H1>
  7. This module defines a class <CODE>SGMLParser</CODE> which serves as the
  8. basis for parsing text files formatted in SGML (Standard Generalized
  9. Mark-up Language).  In fact, it does not provide a full SGML parser
  10. --- it only parses SGML insofar as it is used by HTML, and the module
  11. only exists as a base for the <CODE>htmllib</CODE> module.
  12. In particular, the parser is hardcoded to recognize the following
  13. constructs:
  14. <P>
  15. <UL>
  16. <LI>•  Opening and closing tags of the form
  17. ``<CODE><<VAR>tag</VAR> <VAR>attr</VAR>="<VAR>value</VAR>" ...></CODE>'' and
  18. ``<CODE></<VAR>tag</VAR>></CODE>'', respectively.
  19. <P>
  20. <LI>•  Numeric character references of the form ``<CODE>&#<VAR>name</VAR>;</CODE>''.
  21. <P>
  22. <LI>•  Entity references of the form ``<CODE>&<VAR>name</VAR>;</CODE>''.
  23. <P>
  24. <LI>•  SGML comments of the form ``<CODE><!--<VAR>text</VAR>--></CODE>''.  Note that
  25. spaces, tabs, and newlines are allowed between the trailing
  26. ``<CODE>></CODE>'' and the immediately preceeding ``<CODE>--</CODE>''.
  27. <P>
  28. </UL>
  29. The <CODE>SGMLParser</CODE> class must be instantiated without arguments.
  30. It has the following interface methods:
  31. <P>
  32. <DL><DT><B>reset</B> () -- Method on SGMLParser<DD>
  33. Reset the instance.  Loses all unprocessed data.  This is called
  34. implicitly at instantiation time.
  35. </DL>
  36. <DL><DT><B>setnomoretags</B> () -- Method on SGMLParser<DD>
  37. Stop processing tags.  Treat all following input as literal input
  38. (CDATA).  (This is only provided so the HTML tag <CODE><PLAINTEXT></CODE>
  39. can be implemented.)
  40. </DL>
  41. <DL><DT><B>setliteral</B> () -- Method on SGMLParser<DD>
  42. Enter literal mode (CDATA mode).
  43. </DL>
  44. <DL><DT><B>feed</B> (<VAR>data</VAR>) -- Method on SGMLParser<DD>
  45. Feed some text to the parser.  It is processed insofar as it consists
  46. of complete elements; incomplete data is buffered until more data is
  47. fed or <CODE>close()</CODE> is called.
  48. </DL>
  49. <DL><DT><B>close</B> () -- Method on SGMLParser<DD>
  50. Force processing of all buffered data as if it were followed by an
  51. end-of-file mark.  This method may be redefined by a derived class to
  52. define additional processing at the end of the input, but the
  53. redefined version should always call <CODE>SGMLParser.close()</CODE>.
  54. </DL>
  55. <DL><DT><B>handle_starttag</B> (<VAR>tag</VAR>, <VAR>method</VAR>, <VAR>attributes</VAR>) -- Method on SGMLParser<DD>
  56. This method is called to handle start tags for which either a
  57. <CODE>start_<VAR>tag</VAR>()</CODE> or <CODE>do_<VAR>tag</VAR>()</CODE> method has been
  58. defined.  The <CODE>tag</CODE> argument is the name of the tag converted to
  59. lower case, and the <CODE>method</CODE> argument is the bound method which
  60. should be used to support semantic interpretation of the start tag.
  61. The <VAR>attributes</VAR> argument is a list of (<VAR>name</VAR>, <VAR>value</VAR>)
  62. pairs containing the attributes found inside the tag's <CODE><></CODE>
  63. brackets.  The <VAR>name</VAR> has been translated to lower case and double
  64. quotes and backslashes in the <VAR>value</VAR> have been interpreted.  For
  65. instance, for the tag <CODE><A HREF="http://www.cwi.nl/"></CODE>, this
  66. method would be called as <CODE>unknown_starttag('a', [('href',
  67. 'http://www.cwi.nl/')])</CODE>.  The base implementation simply calls
  68. <CODE>method</CODE> with <CODE>attributes</CODE> as the only argument.
  69. </DL>
  70. <DL><DT><B>handle_endtag</B> (<VAR>tag</VAR>, <VAR>method</VAR>) -- Method on SGMLParser<DD>
  71. This method is called to handle endtags for which an
  72. <CODE>end_<VAR>tag</VAR>()</CODE> method has been defined.  The <CODE>tag</CODE>
  73. argument is the name of the tag converted to lower case, and the
  74. <CODE>method</CODE> argument is the bound method which should be used to
  75. support semantic interpretation of the end tag.  If no
  76. <CODE>end_<VAR>tag</VAR>()</CODE> method is defined for the closing element, this
  77. handler is not called.  The base implementation simply calls
  78. <CODE>method</CODE>.
  79. </DL>
  80. <DL><DT><B>handle_data</B> (<VAR>data</VAR>) -- Method on SGMLParser<DD>
  81. This method is called to process arbitrary data.  It is intended to be
  82. overridden by a derived class; the base class implementation does
  83. nothing.
  84. </DL>
  85. <DL><DT><B>handle_charref</B> (<VAR>ref</VAR>) -- Method on SGMLParser<DD>
  86. This method is called to process a character reference of the form
  87. ``<CODE>&#<VAR>ref</VAR>;</CODE>''.  In the base implementation, <VAR>ref</VAR> must
  88. be a decimal number in the
  89. range 0-255.  It translates the character to ASCII and calls the
  90. method <CODE>handle_data()</CODE> with the character as argument.  If
  91. <VAR>ref</VAR> is invalid or out of range, the method
  92. <CODE>unknown_charref(<VAR>ref</VAR>)</CODE> is called to handle the error.  A
  93. subclass must override this method to provide support for named
  94. character entities.
  95. </DL>
  96. <DL><DT><B>handle_entityref</B> (<VAR>ref</VAR>) -- Method on SGMLParser<DD>
  97. This method is called to process a general entity reference of the form
  98. ``<CODE>&<VAR>ref</VAR>;</CODE>'' where <VAR>ref</VAR> is an general entity
  99. reference.  It looks for <VAR>ref</VAR> in the instance (or class)
  100. variable <CODE>entitydefs</CODE> which should be a mapping from entity names
  101. to corresponding translations.
  102. If a translation is found, it calls the method <CODE>handle_data()</CODE>
  103. with the translation; otherwise, it calls the method
  104. <CODE>unknown_entityref(<VAR>ref</VAR>)</CODE>.  The default <CODE>entitydefs</CODE>
  105. defines translations for <CODE>&amp;</CODE>, <CODE>&apos</CODE>, <CODE>&gt;</CODE>,
  106. <CODE>&lt;</CODE>, and <CODE>&quot;</CODE>.
  107. </DL>
  108. <DL><DT><B>handle_comment</B> (<VAR>comment</VAR>) -- Method on SGMLParser<DD>
  109. This method is called when a comment is encountered.  The
  110. <CODE>comment</CODE> argument is a string containing the text between the
  111. ``<CODE><!--</CODE>'' and ``<CODE>--></CODE>'' delimiters, but not the delimiters
  112. themselves.  For example, the comment ``<CODE><!--text--></CODE>'' will
  113. cause this method to be called with the argument <CODE>'text'</CODE>.  The
  114. default method does nothing.
  115. </DL>
  116. <DL><DT><B>report_unbalanced</B> (<VAR>tag</VAR>) -- Method on SGMLParser<DD>
  117. This method is called when an end tag is found which does not
  118. correspond to any open element.
  119. </DL>
  120. <DL><DT><B>unknown_starttag</B> (<VAR>tag</VAR>, <VAR>attributes</VAR>) -- Method on SGMLParser<DD>
  121. This method is called to process an unknown start tag.  It is intended
  122. to be overridden by a derived class; the base class implementation
  123. does nothing.
  124. </DL>
  125. <DL><DT><B>unknown_endtag</B> (<VAR>tag</VAR>) -- Method on SGMLParser<DD>
  126. This method is called to process an unknown end tag.  It is intended
  127. to be overridden by a derived class; the base class implementation
  128. does nothing.
  129. </DL>
  130. <DL><DT><B>unknown_charref</B> (<VAR>ref</VAR>) -- Method on SGMLParser<DD>
  131. This method is called to process unresolvable numeric character
  132. references.  It is intended to be overridden by a derived class; the
  133. base class implementation does nothing.
  134. </DL>
  135. <DL><DT><B>unknown_entityref</B> (<VAR>ref</VAR>) -- Method on SGMLParser<DD>
  136. This method is called to process an unknown entity reference.  It is
  137. intended to be overridden by a derived class; the base class
  138. implementation does nothing.
  139. </DL>
  140. Apart from overriding or extending the methods listed above, derived
  141. classes may also define methods of the following form to define
  142. processing of specific tags.  Tag names in the input stream are case
  143. independent; the <VAR>tag</VAR> occurring in method names must be in lower
  144. case:
  145. <P>
  146. <DL><DT><B>start_<VAR>tag</VAR></B> (<VAR>attributes</VAR>) -- Method on SGMLParser<DD>
  147. This method is called to process an opening tag <VAR>tag</VAR>.  It has
  148. preference over <CODE>do_<VAR>tag</VAR>()</CODE>.  The <VAR>attributes</VAR> argument
  149. has the same meaning as described for <CODE>handle_starttag()</CODE> above.
  150. </DL>
  151. <DL><DT><B>do_<VAR>tag</VAR></B> (<VAR>attributes</VAR>) -- Method on SGMLParser<DD>
  152. This method is called to process an opening tag <VAR>tag</VAR> that does
  153. not come with a matching closing tag.  The <VAR>attributes</VAR> argument
  154. has the same meaning as described for <CODE>handle_starttag()</CODE> above.
  155. </DL>
  156. <DL><DT><B>end_<VAR>tag</VAR></B> () -- Method on SGMLParser<DD>
  157. This method is called to process a closing tag <VAR>tag</VAR>.
  158. </DL>
  159. Note that the parser maintains a stack of open elements for which no
  160. end tag has been found yet.  Only tags processed by
  161. <CODE>start_<VAR>tag</VAR>()</CODE> are pushed on this stack.  Definition of an
  162. <CODE>end_<VAR>tag</VAR>()</CODE> method is optional for these tags.  For tags
  163. processed by <CODE>do_<VAR>tag</VAR>()</CODE> or by <CODE>unknown_tag()</CODE>, no
  164. <CODE>end_<VAR>tag</VAR>()</CODE> method must be defined; if defined, it will not
  165. be used.  If both <CODE>start_<VAR>tag</VAR>()</CODE> and <CODE>do_<VAR>tag</VAR>()</CODE>
  166. methods exist for a tag, the <CODE>start_<VAR>tag</VAR>()</CODE> method takes
  167. precedence.
  168.