| \section{Standard Module \module{xmllib}} |
| % Author: Sjoerd Mullender |
| \label{module-xmllib} |
| \stmodindex{xmllib} |
| \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} |