Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{htmllib}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-htmllib} |
Guido van Rossum | a12ef94 | 1995-02-27 17:53:25 +0000 | [diff] [blame] | 3 | \stmodindex{htmllib} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 4 | \index{HTML} |
| 5 | \index{hypertext} |
| 6 | |
| 7 | \renewcommand{\indexsubitem}{(in module htmllib)} |
| 8 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 9 | This module defines a class which can serve as a base for parsing text |
| 10 | files formatted in the HyperText Mark-up Language (HTML). The class |
| 11 | is not directly concerned with I/O --- it must be provided with input |
| 12 | in string form via a method, and makes calls to methods of a |
| 13 | ``formatter'' object in order to produce output. The |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 14 | \class{HTMLParser} class is designed to be used as a base class for |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 15 | other classes in order to add functionality, and allows most of its |
| 16 | methods to be extended or overridden. In turn, this class is derived |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 17 | from and extends the \class{SGMLParser} class defined in module |
| 18 | \module{sgmllib}\refstmodindex{sgmllib}. The \class{HTMLParser} |
| 19 | implementation supports the HTML 2.0 language as described in |
| 20 | \rfc{1866}. Two implementations of formatter objects are provided in |
| 21 | the \module{formatter}\refstmodindex{formatter} module; refer to the |
| 22 | documentation for that module for information on the formatter |
| 23 | interface. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 24 | \index{SGML} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 25 | \ttindex{SGMLParser} |
| 26 | \index{formatter} |
| 27 | |
| 28 | The following is a summary of the interface defined by |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 29 | \class{sgmllib.SGMLParser}: |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 30 | |
| 31 | \begin{itemize} |
| 32 | |
| 33 | \item |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 34 | The interface to feed data to an instance is through the \method{feed()} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 35 | method, which takes a string argument. This can be called with as |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 36 | little or as much text at a time as desired; \samp{p.feed(a); |
| 37 | p.feed(b)} has the same effect as \samp{p.feed(a+b)}. When the data |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 38 | contains complete HTML tags, these are processed immediately; |
| 39 | incomplete elements are saved in a buffer. To force processing of all |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 40 | unprocessed data, call the \method{close()} method. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 41 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 42 | For example, to parse the entire contents of a file, use: |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 43 | \bcode\begin{verbatim} |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 44 | parser.feed(open('myfile.html').read()) |
| 45 | parser.close() |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 46 | \end{verbatim}\ecode |
| 47 | % |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 48 | \item |
| 49 | The interface to define semantics for HTML tags is very simple: derive |
| 50 | a class and define methods called \code{start_\var{tag}()}, |
| 51 | \code{end_\var{tag}()}, or \code{do_\var{tag}()}. The parser will |
| 52 | call these at appropriate moments: \code{start_\var{tag}} or |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 53 | \code{do_\var{tag}()} is called when an opening tag of the form |
| 54 | \code{<\var{tag} ...>} is encountered; \code{end_\var{tag}()} is called |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 55 | when a closing tag of the form \code{<\var{tag}>} is encountered. If |
| 56 | an opening tag requires a corresponding closing tag, like \code{<H1>} |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 57 | ... \code{</H1>}, the class should define the \code{start_\var{tag}()} |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 58 | method; if a tag requires no closing tag, like \code{<P>}, the class |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 59 | should define the \code{do_\var{tag}()} method. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 60 | |
| 61 | \end{itemize} |
| 62 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 63 | The module defines a single class: |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 64 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 65 | \begin{funcdesc}{HTMLParser}{formatter} |
| 66 | This is the basic HTML parser class. It supports all entity names |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 67 | required by the HTML 2.0 specification (\rfc{1866}). It also defines |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 68 | handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 69 | \end{funcdesc} |
| 70 | |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 71 | In addition to tag methods, the \class{HTMLParser} class provides some |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 72 | additional methods and instance variables for use within tag methods. |
| 73 | |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 74 | \renewcommand{\indexsubitem}{(HTMLParser attribute)} |
Fred Drake | 8f92595 | 1996-10-09 16:13:22 +0000 | [diff] [blame] | 75 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 76 | \begin{datadesc}{formatter} |
| 77 | This is the formatter instance associated with the parser. |
| 78 | \end{datadesc} |
| 79 | |
| 80 | \begin{datadesc}{nofill} |
| 81 | Boolean flag which should be true when whitespace should not be |
| 82 | collapsed, or false when it should be. In general, this should only |
| 83 | be true when character data is to be treated as ``preformatted'' text, |
| 84 | as within a \code{<PRE>} element. The default value is false. This |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 85 | affects the operation of \method{handle_data()} and \method{save_end()}. |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 86 | \end{datadesc} |
| 87 | |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 88 | \renewcommand{\indexsubitem}{(HTMLParser method)} |
| 89 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 90 | \begin{funcdesc}{anchor_bgn}{href\, name\, type} |
| 91 | This method is called at the start of an anchor region. The arguments |
| 92 | correspond to the attributes of the \code{<A>} tag with the same |
| 93 | names. The default implementation maintains a list of hyperlinks |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 94 | (defined by the \code{href} attribute) within the document. The list |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 95 | of hyperlinks is available as the data attribute \code{anchorlist}. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 96 | \end{funcdesc} |
| 97 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 98 | \begin{funcdesc}{anchor_end}{} |
| 99 | This method is called at the end of an anchor region. The default |
| 100 | implementation adds a textual footnote marker using an index into the |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 101 | list of hyperlinks created by \method{anchor_bgn()}. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 102 | \end{funcdesc} |
| 103 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 104 | \begin{funcdesc}{handle_image}{source\, alt\optional{\, ismap\optional{\, align\optional{\, width\optional{\, height}}}}} |
| 105 | This method is called to handle images. The default implementation |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 106 | simply passes the \var{alt} value to the \method{handle_data()} |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 107 | method. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 108 | \end{funcdesc} |
| 109 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 110 | \begin{funcdesc}{save_bgn}{} |
| 111 | Begins saving character data in a buffer instead of sending it to the |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 112 | formatter object. Retrieve the stored data via \method{save_end()}. |
| 113 | Use of the \method{save_bgn()} / \method{save_end()} pair may not be |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 114 | nested. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 115 | \end{funcdesc} |
| 116 | |
Fred Drake | 58d7f69 | 1996-10-08 21:52:23 +0000 | [diff] [blame] | 117 | \begin{funcdesc}{save_end}{} |
| 118 | Ends buffering character data and returns all data saved since the |
Fred Drake | 526467c | 1998-02-10 21:42:27 +0000 | [diff] [blame^] | 119 | preceeding call to \method{save_bgn()}. If the \code{nofill} flag is |
| 120 | false, whitespace is collapsed to single spaces. A call to this |
| 121 | method without a preceeding call to \method{save_bgn()} will raise a |
| 122 | \exception{TypeError} exception. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 123 | \end{funcdesc} |