227 lines
9.6 KiB
TeX
227 lines
9.6 KiB
TeX
\section{\module{xmllib} ---
|
|
A parser for XML documents.}
|
|
% Author: Sjoerd Mullender
|
|
\declaremodule{standard}{xmllib}
|
|
|
|
\modulesynopsis{A parser for XML documents.}
|
|
|
|
\index{XML}
|
|
|
|
This module defines a class \class{XMLParser} which serves as the basis
|
|
for parsing text files formatted in XML (eXtended Markup Language).
|
|
|
|
\begin{classdesc}{XMLParser}{}
|
|
The \class{XMLParser} class must be instantiated without arguments.
|
|
\end{classdesc}
|
|
|
|
This class provides the following interface methods:
|
|
|
|
\begin{methoddesc}{reset}{}
|
|
Reset the instance. Loses all unprocessed data. This is called
|
|
implicitly at the instantiation time.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setnomoretags}{}
|
|
Stop processing tags. Treat all following input as literal input
|
|
(CDATA).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setliteral}{}
|
|
Enter literal mode (CDATA mode).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{feed}{data}
|
|
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 \method{close()} is called.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
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 \method{close()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{translate_references}{data}
|
|
Translate all entity and character references in \var{data} and
|
|
returns the translated string.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_xml}{encoding, standalone}
|
|
This method is called when the \samp{<?xml ...?>} tag is processed.
|
|
The arguments are the values of the encoding and standalone attributes
|
|
in the tag. Both encoding and standalone are optional. The values
|
|
passed to \method{handle_xml()} default to \code{None} and the string
|
|
\code{'no'} respectively.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_doctype}{tag, data}
|
|
This method is called when the \samp{<!DOCTYPE...>} tag is processed.
|
|
The arguments are the name of the root element and the uninterpreted
|
|
contents of the tag, starting after the white space after the name of
|
|
the root element.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_starttag}{tag, method, attributes}
|
|
This method is called to handle start tags for which a
|
|
\method{start_\var{tag}()} method has been defined. The \var{tag}
|
|
argument is the name of the tag, and the \var{method} argument is the
|
|
bound method which should be used to support semantic interpretation
|
|
of the start tag. The \var{attributes} argument is a dictionary of
|
|
attributes, the key being the \var{name} and the value being the
|
|
\var{value} of the attribute found inside the tag's \code{<>} brackets.
|
|
Character and entity references in the \var{value} have
|
|
been interpreted. For instance, for the tag
|
|
\code{<A HREF="http://www.cwi.nl/">}, this method would be called as
|
|
\code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}.
|
|
The base implementation simply calls \var{method} with \var{attributes}
|
|
as the only argument.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_endtag}{tag, method}
|
|
This method is called to handle endtags for which an
|
|
\method{end_\var{tag}()} method has been defined. The \var{tag}
|
|
argument is the name of the tag, and the
|
|
\var{method} argument is the bound method which should be used to
|
|
support semantic interpretation of the end tag. If no
|
|
\method{end_\var{tag}()} method is defined for the closing element, this
|
|
handler is not called. The base implementation simply calls
|
|
\var{method}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_data}{data}
|
|
This method is called to process arbitrary data. It is intended to be
|
|
overridden by a derived class; the base class implementation does
|
|
nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_charref}{ref}
|
|
This method is called to process a character reference of the form
|
|
\samp{\&\#\var{ref};}. \var{ref} can either be a decimal number,
|
|
or a hexadecimal number when preceded by an \character{x}.
|
|
In the base implementation, \var{ref} must be a number in the
|
|
range 0-255. It translates the character to \ASCII{} and calls the
|
|
method \method{handle_data()} with the character as argument. If
|
|
\var{ref} is invalid or out of range, the method
|
|
\code{unknown_charref(\var{ref})} is called to handle the error. A
|
|
subclass must override this method to provide support for character
|
|
references outside of the \ASCII{} range.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_entityref}{ref}
|
|
This method is called to process a general entity reference of the
|
|
form \samp{\&\var{ref};} where \var{ref} is an general entity
|
|
reference. It looks for \var{ref} in the instance (or class)
|
|
variable \member{entitydefs} which should be a mapping from entity
|
|
names to corresponding translations.
|
|
If a translation is found, it calls the method \method{handle_data()}
|
|
with the translation; otherwise, it calls the method
|
|
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
|
|
defines translations for \code{\&}, \code{\&apos}, \code{\>},
|
|
\code{\<}, and \code{\"}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_comment}{comment}
|
|
This method is called when a comment is encountered. The
|
|
\var{comment} argument is a string containing the text between the
|
|
\samp{<!--} and \samp{-->} delimiters, but not the delimiters
|
|
themselves. For example, the comment \samp{<!--text-->} will
|
|
cause this method to be called with the argument \code{'text'}. The
|
|
default method does nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_cdata}{data}
|
|
This method is called when a CDATA element is encountered. The
|
|
\var{data} argument is a string containing the text between the
|
|
\samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters
|
|
themselves. For example, the entity \samp{<![CDATA[text]]>} will
|
|
cause this method to be called with the argument \code{'text'}. The
|
|
default method does nothing, and is intended to be overridden.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_proc}{name, data}
|
|
This method is called when a processing instruction (PI) is
|
|
encountered. The \var{name} is the PI target, and the \var{data}
|
|
argument is a string containing the text between the PI target and the
|
|
closing delimiter, but not the delimiter itself. For example, the
|
|
instruction \samp{<?XML text?>} will cause this method to be called
|
|
with the arguments \code{'XML'} and \code{'text'}. The default method
|
|
does nothing. Note that if a document starts with \samp{<?xml
|
|
...?>}, \method{handle_xml()} is called to handle it.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_special}{data}
|
|
This method is called when a declaration is encountered. The
|
|
\var{data} argument is a string containing the text between the
|
|
\samp{<!} and \samp{>} delimiters, but not the delimiters
|
|
themselves. For example, the entity \samp{<!ENTITY text>} will
|
|
cause this method to be called with the argument \code{'ENTITY text'}. The
|
|
default method does nothing. Note that \samp{<!DOCTYPE ...>} is
|
|
handled separately if it is located at the start of the document.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{syntax_error}{message}
|
|
This method is called when a syntax error is encountered. The
|
|
\var{message} is a description of what was wrong. The default method
|
|
raises a \exception{RuntimeError} exception. If this method is
|
|
overridden, it is permissable for it to return. This method is only
|
|
called when the error can be recovered from. Unrecoverable errors
|
|
raise a \exception{RuntimeError} without first calling
|
|
\method{syntax_error()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_starttag}{tag, attributes}
|
|
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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_endtag}{tag}
|
|
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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_charref}{ref}
|
|
This method is called to process unresolvable numeric character
|
|
references. It is intended to be overridden by a derived class; the
|
|
base class implementation does nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_entityref}{ref}
|
|
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.
|
|
\end{methoddesc}
|
|
|
|
Apart from overriding or extending the methods listed above, derived
|
|
classes may also define methods and variables of the following form to
|
|
define processing of specific tags. Tag names in the input stream are
|
|
case dependent; the \var{tag} occurring in method names must be in the
|
|
correct case:
|
|
|
|
\begin{methoddescni}{start_\var{tag}}{attributes}
|
|
This method is called to process an opening tag \var{tag}. The
|
|
\var{attributes} argument has the same meaning as described for
|
|
\method{handle_starttag()} above. In fact, the base implementation of
|
|
\method{handle_starttag()} calls this method.
|
|
\end{methoddescni}
|
|
|
|
\begin{methoddescni}{end_\var{tag}}{}
|
|
This method is called to process a closing tag \var{tag}.
|
|
\end{methoddescni}
|
|
|
|
\begin{memberdescni}{\var{tag}_attributes}
|
|
If a class or instance variable \member{\var{tag}_attributes} exists, it
|
|
should be a list or a dictionary. If a list, the elements of the list
|
|
are the valid attributes for the element \var{tag}; if a dictionary,
|
|
the keys are the valid attributes for the element \var{tag}, and the
|
|
values the default values of the attributes, or \code{None} if there
|
|
is no default.
|
|
In addition to the attributes that were present in the tag, the
|
|
attribute dictionary that is passed to \method{handle_starttag()} and
|
|
\method{unknown_starttag()} contains values for all attributes that
|
|
have a default value.
|
|
\end{memberdescni}
|