sgmllib
This module defines a class SGMLParser
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 htmllib
module.
In particular, the parser is hardcoded to recognize the following constructs:
<tag attr="value" ...>
'' and
``</tag>
'', respectively.&#name;
''.&name;
''.<!-text->
''. Note that
spaces, tabs, and newlines are allowed between the trailing
``>
'' and the immediately preceeding ``-
''.
The SGMLParser
class must be instantiated without arguments.
It has the following interface methods:
<PLAINTEXT>
can be implemented.)
close()
is called.
SGMLParser.close()
.
start_tag()
or do_tag()
method has been
defined. The tag
argument is the name of the tag converted to
lower case, and the method
argument is the bound method which
should be used to support semantic interpretation of the start tag.
The attributes argument is a list of (name, value)
pairs containing the attributes found inside the tag's <>
brackets. The name has been translated to lower case and double
quotes and backslashes in the value have been interpreted. For
instance, for the tag <A HREF="http://www.cwi.nl/">
, this
method would be called as unknown_starttag('a', [('href',
'http://www.cwi.nl/')])
. The base implementation simply calls
method
with attributes
as the only argument.
This method is called to handle endtags for which an
end_tag()
method has been defined. The tag
argument is the name of the tag converted to lower case, and the
method
argument is the bound method which should be used to
support semantic interpretation of the end tag. If no
end_tag()
method is defined for the closing element, this
handler is not called. The base implementation simply calls
method
.
&#ref;
''. In the base implementation, ref must
be a decimal number in the
range 0-255. It translates the character to ASCII and calls the
method handle_data()
with the character as argument. If
ref is invalid or out of range, the method
unknown_charref(ref)
is called to handle the error. A
subclass must override this method to provide support for named
character entities.
&ref;
'' where ref is an general entity
reference. It looks for ref in the instance (or class)
variable entitydefs
which should be a mapping from entity names
to corresponding translations.
If a translation is found, it calls the method handle_data()
with the translation; otherwise, it calls the method
unknown_entityref(ref)
. The default entitydefs
defines translations for &
, &apos
, >
,
<
, and "
.
comment
argument is a string containing the text between the
``<!-
'' and ``->
'' delimiters, but not the delimiters
themselves. For example, the comment ``<!-text->
'' will
cause this method to be called with the argument 'text'
. The
default method does nothing.
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 tag occurring in method names must be in lower case:
do_tag()
. The attributes argument
has the same meaning as described for handle_starttag()
above.
handle_starttag()
above.
Note that the parser maintains a stack of open elements for which no
end tag has been found yet. Only tags processed by
start_tag()
are pushed on this stack. Definition of an
end_tag()
method is optional for these tags. For tags
processed by do_tag()
or by unknown_tag()
, no
end_tag()
method must be defined; if defined, it will not
be used. If both start_tag()
and do_tag()
methods exist for a tag, the start_tag()
method takes
precedence.