[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / module-sgmllib.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-htmllib.html" />
<link rel="prev" href="module-HTMLParser.html" />
<link rel="parent" href="markup.html" />
<link rel="next" href="module-htmllib.html" />
<meta name='aesop' content='information' />
<title>13.2 sgmllib -- Simple SGML parser</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.1.1 Example HTML Parser"
  href="htmlparser-example.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="13. Structured Markup Processing"
  href="markup.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="13.3 htmllib  "
  href="module-htmllib.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="htmlparser-example.html">13.1.1 Example HTML Parser</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="markup.html">13. Structured Markup Processing</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-htmllib.html">13.3 htmllib  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0015200000000000000000">
13.2 <tt class="module">sgmllib</tt> --
         Simple SGML parser</A>
</H1>

<P>
<A NAME="module-sgmllib"></A>

<P>
<a id='l2h-4280' xml:id='l2h-4280'></a>

<P>
This module defines a class <tt class="class">SGMLParser</tt> which serves as the
basis for parsing text files formatted in SGML (Standard Generalized
Mark-up Language).  In fact, it does not provide a full SGML parser
-- it only parses SGML insofar as it is used by HTML, and the module
only exists as a base for the <tt class="module"><a href="module-htmllib.html">htmllib</a></tt> module.  Another
HTML parser which supports XHTML and offers a somewhat different
interface is available in the <tt class="module"><a href="module-HTMLParser.html">HTMLParser</a></tt> module.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4260' xml:id='l2h-4260' class="class">SGMLParser</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
The <tt class="class">SGMLParser</tt> class is instantiated without arguments.
The parser is hardcoded to recognize the following
constructs:

<P>

<UL>
<LI>Opening and closing tags of the form
"<tt class="samp">&lt;<var>tag</var> <var>attr</var>="<var>value</var>" ...&gt;</tt>" and
"<tt class="samp">&lt;/<var>tag</var>&gt;</tt>", respectively.

<P>
</LI>
<LI>Numeric character references of the form "<tt class="samp">&amp;#<var>name</var>;</tt>".

<P>
</LI>
<LI>Entity references of the form "<tt class="samp">&amp;<var>name</var>;</tt>".

<P>
</LI>
<LI>SGML comments of the form "<tt class="samp">&lt;!-&#45;<var>text</var>-&#45;&gt;</tt>".  Note that
spaces, tabs, and newlines are allowed between the trailing
"<tt class="samp">&gt;</tt>" and the immediately preceding "<tt class="samp">-&#45;</tt>".

<P>
</LI>
</UL>
</dl>

<P>
A single exception is defined as well:

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4261' xml:id='l2h-4261' class="exception">SGMLParseError</tt></b></dt>
<dd>
Exception raised by the <tt class="class">SGMLParser</tt> class when it encounters an
error while parsing.

<span class="versionnote">New in version 2.1.</span>

</dd></dl>

<P>
<tt class="class">SGMLParser</tt> instances have the following methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4262' xml:id='l2h-4262' class="method">reset</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Reset the instance.  Loses all unprocessed data.  This is called
implicitly at instantiation time.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4263' xml:id='l2h-4263' class="method">setnomoretags</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Stop processing tags.  Treat all following input as literal input
(CDATA).  (This is only provided so the HTML tag
<code>&lt;PLAINTEXT&gt;</code> can be implemented.)
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4264' xml:id='l2h-4264' class="method">setliteral</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Enter literal mode (CDATA mode).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4265' xml:id='l2h-4265' class="method">feed</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Feed some text to the parser.  It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is
fed or <tt class="method">close()</tt> is called.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4266' xml:id='l2h-4266' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Force processing of all buffered data as if it were followed by an
end-of-file mark.  This method may be redefined by a derived class to
define additional processing at the end of the input, but the
redefined version should always call <tt class="method">close()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4267' xml:id='l2h-4267' class="method">get_starttag_text</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the text of the most recently opened start tag.  This should
not normally be needed for structured processing, but may be useful in
dealing with HTML ``as deployed'' or for re-generating input with
minimal changes (whitespace between attributes can be preserved,
etc.).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4268' xml:id='l2h-4268' class="method">handle_starttag</tt></b>(</nobr></td>
  <td><var>tag, method, attributes</var>)</td></tr></table></dt>
<dd>
This method is called to handle start tags for which either a
<tt class="method">start_<var>tag</var>()</tt> or <tt class="method">do_<var>tag</var>()</tt> method has been
defined.  The <var>tag</var> argument is the name of the tag converted to
lower case, and the <var>method</var> argument is the bound method which
should be used to support semantic interpretation of the start tag.
The <var>attributes</var> argument is a list of <code>(<var>name</var>,
<var>value</var>)</code> pairs containing the attributes found inside the tag's
<code>&lt;&gt;</code> brackets.  The <var>name</var> has been translated to lower case
and double quotes and backslashes in the <var>value</var> have been interpreted.
For instance, for the tag <code>&lt;A HREF="http://www.cwi.nl/"&gt;</code>, this
method would be called as "<tt class="samp">unknown_starttag('a', [('href',
'http://www.cwi.nl/')])</tt>".  The base implementation simply calls
<var>method</var> with <var>attributes</var> as the only argument.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4269' xml:id='l2h-4269' class="method">handle_endtag</tt></b>(</nobr></td>
  <td><var>tag, method</var>)</td></tr></table></dt>
<dd>
This method is called to handle endtags for which an
<tt class="method">end_<var>tag</var>()</tt> method has been defined.  The
<var>tag</var> argument is the name of the tag converted to lower case, and
the <var>method</var> argument is the bound method which should be used to
support semantic interpretation of the end tag.  If no
<tt class="method">end_<var>tag</var>()</tt> method is defined for the closing element,
this handler is not called.  The base implementation simply calls
<var>method</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4270' xml:id='l2h-4270' class="method">handle_data</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
This method is called to process arbitrary data.  It is intended to be
overridden by a derived class; the base class implementation does
nothing.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4271' xml:id='l2h-4271' class="method">handle_charref</tt></b>(</nobr></td>
  <td><var>ref</var>)</td></tr></table></dt>
<dd>
This method is called to process a character reference of the form
"<tt class="samp">&amp;#<var>ref</var>;</tt>".  In the base implementation, <var>ref</var> must
be a decimal number in the
range 0-255.  It translates the character to ASCII and calls the
method <tt class="method">handle_data()</tt> with the character as argument.  If
<var>ref</var> is invalid or out of range, the method
<code>unknown_charref(<var>ref</var>)</code> is called to handle the error.  A
subclass must override this method to provide support for named
character entities.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4272' xml:id='l2h-4272' class="method">handle_entityref</tt></b>(</nobr></td>
  <td><var>ref</var>)</td></tr></table></dt>
<dd>
This method is called to process a general entity reference of the
form "<tt class="samp">&amp;<var>ref</var>;</tt>" where <var>ref</var> is an general entity
reference.  It looks for <var>ref</var> in the instance (or class)
variable <tt class="member">entitydefs</tt> which should be a mapping from entity
names to corresponding translations.  If a translation is found, it
calls the method <tt class="method">handle_data()</tt> with the translation;
otherwise, it calls the method <code>unknown_entityref(<var>ref</var>)</code>.
The default <tt class="member">entitydefs</tt> defines translations for
<code>&amp;amp;</code>, <code>&amp;apos</code>, <code>&amp;gt;</code>, <code>&amp;lt;</code>, and
<code>&amp;quot;</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4273' xml:id='l2h-4273' class="method">handle_comment</tt></b>(</nobr></td>
  <td><var>comment</var>)</td></tr></table></dt>
<dd>
This method is called when a comment is encountered.  The
<var>comment</var> argument is a string containing the text between the
"<tt class="samp">&lt;!-&#45;</tt>" and "<tt class="samp">-&#45;&gt;</tt>" delimiters, but not the delimiters
themselves.  For example, the comment "<tt class="samp">&lt;!-&#45;text-&#45;&gt;</tt>" will
cause this method to be called with the argument <code>'text'</code>.  The
default method does nothing.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4274' xml:id='l2h-4274' class="method">handle_decl</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Method called when an SGML declaration is read by the parser.  In
practice, the <code>DOCTYPE</code> declaration is the only thing observed in
HTML, but the parser does not discriminate among different (or broken)
declarations.  Internal subsets in a <code>DOCTYPE</code> declaration are
not supported.  The <var>data</var> parameter will be the entire contents
of the declaration inside the <code>&lt;!</code>...<code>&gt;</code> markup.  The
default implementation does nothing.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4275' xml:id='l2h-4275' class="method">report_unbalanced</tt></b>(</nobr></td>
  <td><var>tag</var>)</td></tr></table></dt>
<dd>
This method is called when an end tag is found which does not
correspond to any open element.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4276' xml:id='l2h-4276' class="method">unknown_starttag</tt></b>(</nobr></td>
  <td><var>tag, attributes</var>)</td></tr></table></dt>
<dd>
This method is called to process an unknown start tag.  It is intended
to be overridden by a derived class; the base class implementation
does nothing.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4277' xml:id='l2h-4277' class="method">unknown_endtag</tt></b>(</nobr></td>
  <td><var>tag</var>)</td></tr></table></dt>
<dd>
This method is called to process an unknown end tag.  It is intended
to be overridden by a derived class; the base class implementation
does nothing.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4278' xml:id='l2h-4278' class="method">unknown_charref</tt></b>(</nobr></td>
  <td><var>ref</var>)</td></tr></table></dt>
<dd>
This method is called to process unresolvable numeric character
references.  Refer to <tt class="method">handle_charref()</tt> to determine what is
handled by default.  It is intended to be overridden by a derived
class; the base class implementation does nothing.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4279' xml:id='l2h-4279' class="method">unknown_entityref</tt></b>(</nobr></td>
  <td><var>ref</var>)</td></tr></table></dt>
<dd>
This method is called to process an unknown entity reference.  It is
intended to be overridden by a derived class; the base class
implementation does nothing.
</dl>

<P>
Apart from overriding or extending the methods listed above, derived
classes may also define methods of the following form to define
processing of specific tags.  Tag names in the input stream are case
independent; the <var>tag</var> occurring in method names must be in lower
case:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b>start_<var>tag</var></b>(</nobr></td>
  <td><var>attributes</var>)</td></tr></table></dt>
<dd>
This method is called to process an opening tag <var>tag</var>.  It has
preference over <tt class="method">do_<var>tag</var>()</tt>.  The
<var>attributes</var> argument has the same meaning as described for
<tt class="method">handle_starttag()</tt> above.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b>do_<var>tag</var></b>(</nobr></td>
  <td><var>attributes</var>)</td></tr></table></dt>
<dd>
This method is called to process an opening tag <var>tag</var> that does
not come with a matching closing tag.  The <var>attributes</var> argument
has the same meaning as described for <tt class="method">handle_starttag()</tt> above.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b>end_<var>tag</var></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
This method is called to process a closing tag <var>tag</var>.
</dl>

<P>
Note that the parser maintains a stack of open elements for which no
end tag has been found yet.  Only tags processed by
<tt class="method">start_<var>tag</var>()</tt> are pushed on this stack.  Definition of an
<tt class="method">end_<var>tag</var>()</tt> method is optional for these tags.  For tags
processed by <tt class="method">do_<var>tag</var>()</tt> or by <tt class="method">unknown_tag()</tt>, no
<tt class="method">end_<var>tag</var>()</tt> method must be defined; if defined, it will
not be used.  If both <tt class="method">start_<var>tag</var>()</tt> and
<tt class="method">do_<var>tag</var>()</tt> methods exist for a tag, the
<tt class="method">start_<var>tag</var>()</tt> method takes precedence.

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.1.1 Example HTML Parser"
  href="htmlparser-example.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="13. Structured Markup Processing"
  href="markup.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="13.3 htmllib  "
  href="module-htmllib.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="htmlparser-example.html">13.1.1 Example HTML Parser</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="markup.html">13. Structured Markup Processing</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-htmllib.html">13.3 htmllib  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="module-htmllib.html" />
	13	<link rel="prev" href="module-HTMLParser.html" />
	14	<link rel="parent" href="markup.html" />
	15	<link rel="next" href="module-htmllib.html" />
	16	<meta name='aesop' content='information' />
	17	<title>13.2 sgmllib -- Simple SGML parser</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="13.1.1 Example HTML Parser"
	25	href="htmlparser-example.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="13. Structured Markup Processing"
	28	href="markup.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="13.3 htmllib "
	31	href="module-htmllib.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="htmlparser-example.html">13.1.1 Example HTML Parser</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="markup.html">13. Structured Markup Processing</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-htmllib.html">13.3 htmllib </A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION0015200000000000000000">
	56	13.2 <tt class="module">sgmllib</tt> --
	57	Simple SGML parser</A>
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-sgmllib"></A>
	62
	63	<P>
	64	<a id='l2h-4280' xml:id='l2h-4280'></a>
65
66	<P>
67	This module defines a class <tt class="class">SGMLParser</tt> which serves as the
68	basis for parsing text files formatted in SGML (Standard Generalized
69	Mark-up Language). In fact, it does not provide a full SGML parser
70	-- it only parses SGML insofar as it is used by HTML, and the module
71	only exists as a base for the <tt class="module"><a href="module-htmllib.html">htmllib</a></tt> module. Another
72	HTML parser which supports XHTML and offers a somewhat different
73	interface is available in the <tt class="module"><a href="module-HTMLParser.html">HTMLParser</a></tt> module.
74
75	<P>
76	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
77	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-4260' xml:id='l2h-4260' class="class">SGMLParser</tt></b>(</nobr></td>
78	<td><var></var>)</td></tr></table></dt>
79	<dd>
80	The <tt class="class">SGMLParser</tt> class is instantiated without arguments.
81	The parser is hardcoded to recognize the following
82	constructs:
83
84	<P>
85
86	<UL>
87	<LI>Opening and closing tags of the form
88	"<tt class="samp"><<var>tag</var> <var>attr</var>="<var>value</var>" ...></tt>" and
89	"<tt class="samp"></<var>tag</var>></tt>", respectively.
90
91	<P>
92	</LI>
93	<LI>Numeric character references of the form "<tt class="samp">&#<var>name</var>;</tt>".
94
95	<P>
96	</LI>
97	<LI>Entity references of the form "<tt class="samp">&<var>name</var>;</tt>".
98
99	<P>
100	</LI>
101	<LI>SGML comments of the form "<tt class="samp"><!--<var>text</var>--></tt>". Note that
102	spaces, tabs, and newlines are allowed between the trailing
103	"<tt class="samp">></tt>" and the immediately preceding "<tt class="samp">--</tt>".
104
105	<P>
106	</LI>
107	</UL>
108	</dl>
109
110	<P>
111	A single exception is defined as well:
112
113	<P>
114	<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-4261' xml:id='l2h-4261' class="exception">SGMLParseError</tt></b></dt>
115	<dd>
116	Exception raised by the <tt class="class">SGMLParser</tt> class when it encounters an
117	error while parsing.
118
119	<span class="versionnote">New in version 2.1.</span>
120
121	</dd></dl>
122
123	<P>
124	<tt class="class">SGMLParser</tt> instances have the following methods:
125
126	<P>
127	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
128	<td><nobr><b><tt id='l2h-4262' xml:id='l2h-4262' class="method">reset</tt></b>(</nobr></td>
129	<td><var></var>)</td></tr></table></dt>
130	<dd>
131	Reset the instance. Loses all unprocessed data. This is called
132	implicitly at instantiation time.
133	</dl>
134
135	<P>
136	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
137	<td><nobr><b><tt id='l2h-4263' xml:id='l2h-4263' class="method">setnomoretags</tt></b>(</nobr></td>
138	<td><var></var>)</td></tr></table></dt>
139	<dd>
140	Stop processing tags. Treat all following input as literal input
141	(CDATA). (This is only provided so the HTML tag
142	<code><PLAINTEXT></code> can be implemented.)
143	</dl>
144
145	<P>
146	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
147	<td><nobr><b><tt id='l2h-4264' xml:id='l2h-4264' class="method">setliteral</tt></b>(</nobr></td>
148	<td><var></var>)</td></tr></table></dt>
149	<dd>
150	Enter literal mode (CDATA mode).
151	</dl>
152
153	<P>
154	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
155	<td><nobr><b><tt id='l2h-4265' xml:id='l2h-4265' class="method">feed</tt></b>(</nobr></td>
156	<td><var>data</var>)</td></tr></table></dt>
157	<dd>
158	Feed some text to the parser. It is processed insofar as it consists
159	of complete elements; incomplete data is buffered until more data is
160	fed or <tt class="method">close()</tt> is called.
161	</dl>
162
163	<P>
164	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
165	<td><nobr><b><tt id='l2h-4266' xml:id='l2h-4266' class="method">close</tt></b>(</nobr></td>
166	<td><var></var>)</td></tr></table></dt>
167	<dd>
168	Force processing of all buffered data as if it were followed by an
169	end-of-file mark. This method may be redefined by a derived class to
170	define additional processing at the end of the input, but the
171	redefined version should always call <tt class="method">close()</tt>.
172	</dl>
173
174	<P>
175	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
176	<td><nobr><b><tt id='l2h-4267' xml:id='l2h-4267' class="method">get_starttag_text</tt></b>(</nobr></td>
177	<td><var></var>)</td></tr></table></dt>
178	<dd>
179	Return the text of the most recently opened start tag. This should
180	not normally be needed for structured processing, but may be useful in
181	dealing with HTML ``as deployed'' or for re-generating input with
182	minimal changes (whitespace between attributes can be preserved,
183	etc.).
184	</dl>
185
186	<P>
187	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
188	<td><nobr><b><tt id='l2h-4268' xml:id='l2h-4268' class="method">handle_starttag</tt></b>(</nobr></td>
189	<td><var>tag, method, attributes</var>)</td></tr></table></dt>
190	<dd>
191	This method is called to handle start tags for which either a
192	<tt class="method">start_<var>tag</var>()</tt> or <tt class="method">do_<var>tag</var>()</tt> method has been
193	defined. The <var>tag</var> argument is the name of the tag converted to
194	lower case, and the <var>method</var> argument is the bound method which
195	should be used to support semantic interpretation of the start tag.
196	The <var>attributes</var> argument is a list of <code>(<var>name</var>,
197	<var>value</var>)</code> pairs containing the attributes found inside the tag's
198	<code><></code> brackets. The <var>name</var> has been translated to lower case
199	and double quotes and backslashes in the <var>value</var> have been interpreted.
200	For instance, for the tag <code><A HREF="http://www.cwi.nl/"></code>, this
201	method would be called as "<tt class="samp">unknown_starttag('a', [('href',
202	'http://www.cwi.nl/')])</tt>". The base implementation simply calls
203	<var>method</var> with <var>attributes</var> as the only argument.
204	</dl>
205
206	<P>
207	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
208	<td><nobr><b><tt id='l2h-4269' xml:id='l2h-4269' class="method">handle_endtag</tt></b>(</nobr></td>
209	<td><var>tag, method</var>)</td></tr></table></dt>
210	<dd>
211	This method is called to handle endtags for which an
212	<tt class="method">end_<var>tag</var>()</tt> method has been defined. The
213	<var>tag</var> argument is the name of the tag converted to lower case, and
214	the <var>method</var> argument is the bound method which should be used to
215	support semantic interpretation of the end tag. If no
216	<tt class="method">end_<var>tag</var>()</tt> method is defined for the closing element,
217	this handler is not called. The base implementation simply calls
218	<var>method</var>.
219	</dl>
220
221	<P>
222	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
223	<td><nobr><b><tt id='l2h-4270' xml:id='l2h-4270' class="method">handle_data</tt></b>(</nobr></td>
224	<td><var>data</var>)</td></tr></table></dt>
225	<dd>
226	This method is called to process arbitrary data. It is intended to be
227	overridden by a derived class; the base class implementation does
228	nothing.
229	</dl>
230
231	<P>
232	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
233	<td><nobr><b><tt id='l2h-4271' xml:id='l2h-4271' class="method">handle_charref</tt></b>(</nobr></td>
234	<td><var>ref</var>)</td></tr></table></dt>
235	<dd>
236	This method is called to process a character reference of the form
237	"<tt class="samp">&#<var>ref</var>;</tt>". In the base implementation, <var>ref</var> must
238	be a decimal number in the
239	range 0-255. It translates the character to ASCII and calls the
240	method <tt class="method">handle_data()</tt> with the character as argument. If
241	<var>ref</var> is invalid or out of range, the method
242	<code>unknown_charref(<var>ref</var>)</code> is called to handle the error. A
243	subclass must override this method to provide support for named
244	character entities.
245	</dl>
246
247	<P>
248	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
249	<td><nobr><b><tt id='l2h-4272' xml:id='l2h-4272' class="method">handle_entityref</tt></b>(</nobr></td>
250	<td><var>ref</var>)</td></tr></table></dt>
251	<dd>
252	This method is called to process a general entity reference of the
253	form "<tt class="samp">&<var>ref</var>;</tt>" where <var>ref</var> is an general entity
254	reference. It looks for <var>ref</var> in the instance (or class)
255	variable <tt class="member">entitydefs</tt> which should be a mapping from entity
256	names to corresponding translations. If a translation is found, it
257	calls the method <tt class="method">handle_data()</tt> with the translation;
258	otherwise, it calls the method <code>unknown_entityref(<var>ref</var>)</code>.
259	The default <tt class="member">entitydefs</tt> defines translations for
260	<code>&amp;</code>, <code>&apos</code>, <code>&gt;</code>, <code>&lt;</code>, and
261	<code>&quot;</code>.
262	</dl>
263
264	<P>
265	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
266	<td><nobr><b><tt id='l2h-4273' xml:id='l2h-4273' class="method">handle_comment</tt></b>(</nobr></td>
267	<td><var>comment</var>)</td></tr></table></dt>
268	<dd>
269	This method is called when a comment is encountered. The
270	<var>comment</var> argument is a string containing the text between the
271	"<tt class="samp"><!--</tt>" and "<tt class="samp">--></tt>" delimiters, but not the delimiters
272	themselves. For example, the comment "<tt class="samp"><!--text--></tt>" will
273	cause this method to be called with the argument <code>'text'</code>. The
274	default method does nothing.
275	</dl>
276
277	<P>
278	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
279	<td><nobr><b><tt id='l2h-4274' xml:id='l2h-4274' class="method">handle_decl</tt></b>(</nobr></td>
280	<td><var>data</var>)</td></tr></table></dt>
281	<dd>
282	Method called when an SGML declaration is read by the parser. In
283	practice, the <code>DOCTYPE</code> declaration is the only thing observed in
284	HTML, but the parser does not discriminate among different (or broken)
285	declarations. Internal subsets in a <code>DOCTYPE</code> declaration are
286	not supported. The <var>data</var> parameter will be the entire contents
287	of the declaration inside the <code><!</code>...<code>></code> markup. The
288	default implementation does nothing.
289	</dl>
290
291	<P>
292	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
293	<td><nobr><b><tt id='l2h-4275' xml:id='l2h-4275' class="method">report_unbalanced</tt></b>(</nobr></td>
294	<td><var>tag</var>)</td></tr></table></dt>
295	<dd>
296	This method is called when an end tag is found which does not
297	correspond to any open element.
298	</dl>
299
300	<P>
301	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
302	<td><nobr><b><tt id='l2h-4276' xml:id='l2h-4276' class="method">unknown_starttag</tt></b>(</nobr></td>
303	<td><var>tag, attributes</var>)</td></tr></table></dt>
304	<dd>
305	This method is called to process an unknown start tag. It is intended
306	to be overridden by a derived class; the base class implementation
307	does nothing.
308	</dl>
309
310	<P>
311	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
312	<td><nobr><b><tt id='l2h-4277' xml:id='l2h-4277' class="method">unknown_endtag</tt></b>(</nobr></td>
313	<td><var>tag</var>)</td></tr></table></dt>
314	<dd>
315	This method is called to process an unknown end tag. It is intended
316	to be overridden by a derived class; the base class implementation
317	does nothing.
318	</dl>
319
320	<P>
321	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
322	<td><nobr><b><tt id='l2h-4278' xml:id='l2h-4278' class="method">unknown_charref</tt></b>(</nobr></td>
323	<td><var>ref</var>)</td></tr></table></dt>
324	<dd>
325	This method is called to process unresolvable numeric character
326	references. Refer to <tt class="method">handle_charref()</tt> to determine what is
327	handled by default. It is intended to be overridden by a derived
328	class; the base class implementation does nothing.
329	</dl>
330
331	<P>
332	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
333	<td><nobr><b><tt id='l2h-4279' xml:id='l2h-4279' class="method">unknown_entityref</tt></b>(</nobr></td>
334	<td><var>ref</var>)</td></tr></table></dt>
335	<dd>
336	This method is called to process an unknown entity reference. It is
337	intended to be overridden by a derived class; the base class
338	implementation does nothing.
339	</dl>
340
341	<P>
342	Apart from overriding or extending the methods listed above, derived
343	classes may also define methods of the following form to define
344	processing of specific tags. Tag names in the input stream are case
345	independent; the <var>tag</var> occurring in method names must be in lower
346	case:
347
348	<P>
349	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
350	<td><nobr><b>start_<var>tag</var></b>(</nobr></td>
351	<td><var>attributes</var>)</td></tr></table></dt>
352	<dd>
353	This method is called to process an opening tag <var>tag</var>. It has
354	preference over <tt class="method">do_<var>tag</var>()</tt>. The
355	<var>attributes</var> argument has the same meaning as described for
356	<tt class="method">handle_starttag()</tt> above.
357	</dl>
358
359	<P>
360	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
361	<td><nobr><b>do_<var>tag</var></b>(</nobr></td>
362	<td><var>attributes</var>)</td></tr></table></dt>
363	<dd>
364	This method is called to process an opening tag <var>tag</var> that does
365	not come with a matching closing tag. The <var>attributes</var> argument
366	has the same meaning as described for <tt class="method">handle_starttag()</tt> above.
367	</dl>
368
369	<P>
370	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
371	<td><nobr><b>end_<var>tag</var></b>(</nobr></td>
372	<td><var></var>)</td></tr></table></dt>
373	<dd>
374	This method is called to process a closing tag <var>tag</var>.
375	</dl>
376
377	<P>
378	Note that the parser maintains a stack of open elements for which no
379	end tag has been found yet. Only tags processed by
380	<tt class="method">start_<var>tag</var>()</tt> are pushed on this stack. Definition of an
381	<tt class="method">end_<var>tag</var>()</tt> method is optional for these tags. For tags
382	processed by <tt class="method">do_<var>tag</var>()</tt> or by <tt class="method">unknown_tag()</tt>, no
383	<tt class="method">end_<var>tag</var>()</tt> method must be defined; if defined, it will
384	not be used. If both <tt class="method">start_<var>tag</var>()</tt> and
385	<tt class="method">do_<var>tag</var>()</tt> methods exist for a tag, the
386	<tt class="method">start_<var>tag</var>()</tt> method takes precedence.
387
388	<DIV CLASS="navigation">
389	<div class='online-navigation'>
390	<p></p><hr />
391	<table align="center" width="100%" cellpadding="0" cellspacing="2">
392	<tr>
393	<td class='online-navigation'><a rel="prev" title="13.1.1 Example HTML Parser"
394	href="htmlparser-example.html"><img src='../icons/previous.png'
395	border='0' height='32' alt='Previous Page' width='32' /></A></td>
396	<td class='online-navigation'><a rel="parent" title="13. Structured Markup Processing"
397	href="markup.html"><img src='../icons/up.png'
398	border='0' height='32' alt='Up One Level' width='32' /></A></td>
399	<td class='online-navigation'><a rel="next" title="13.3 htmllib "
400	href="module-htmllib.html"><img src='../icons/next.png'
401	border='0' height='32' alt='Next Page' width='32' /></A></td>
402	<td align="center" width="100%">Python Library Reference</td>
403	<td class='online-navigation'><a rel="contents" title="Table of Contents"
404	href="contents.html"><img src='../icons/contents.png'
405	border='0' height='32' alt='Contents' width='32' /></A></td>
406	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
407	border='0' height='32' alt='Module Index' width='32' /></a></td>
408	<td class='online-navigation'><a rel="index" title="Index"
409	href="genindex.html"><img src='../icons/index.png'
410	border='0' height='32' alt='Index' width='32' /></A></td>
411	</tr></table>
412	<div class='online-navigation'>
413	<b class="navlabel">Previous:</b>
414	<a class="sectref" rel="prev" href="htmlparser-example.html">13.1.1 Example HTML Parser</A>
415	<b class="navlabel">Up:</b>
416	<a class="sectref" rel="parent" href="markup.html">13. Structured Markup Processing</A>
417	<b class="navlabel">Next:</b>
418	<a class="sectref" rel="next" href="module-htmllib.html">13.3 htmllib </A>
419	</div>
420	</div>
421	<hr />
422	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
423	</DIV>
424	<!--End of Navigation Panel-->
425	<ADDRESS>
426	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
427	</ADDRESS>
428	</BODY>
429	</HTML>