Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit a10768a

Browse files
gvanrossumgvanrossum
committed
Docu for xmllib.py, by Sjoerd Mullender.
1 parent b62b6d1 commit a10768a

2 files changed

Lines changed: 370 additions & 0 deletions

File tree

‎Doc/lib/libxmllib.tex‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
\section{Standard Module \sectcode{xmllib}}
2+
% Author: Sjoerd Mullender
3+
\label{module-xmllib}
4+
\stmodindex{xmllib}
5+
\index{XML}
6+
7+
This module defines a class \code{XMLParser} which serves as the basis
8+
for parsing text files formatted in XML (eXtended Markup Language).
9+
10+
The \code{XMLParser} class must be instantiated without arguments. It
11+
has the following interface methods:
12+
13+
\renewcommand{\indexsubitem}{({\tt XMLParser} method)}
14+
15+
\begin{funcdesc}{reset}{}
16+
Reset the instance. Loses all unprocessed data. This is called
17+
implicitly at the instantiation time.
18+
\end{funcdesc}
19+
20+
\begin{funcdesc}{setnomoretags}{}
21+
Stop processing tags. Treat all following input as literal input
22+
(CDATA).
23+
\end{funcdesc}
24+
25+
\begin{funcdesc}{setliteral}{}
26+
Enter literal mode (CDATA mode).
27+
\end{funcdesc}
28+
29+
\begin{funcdesc}{feed}{data}
30+
Feed some text to the parser. It is processed insofar as it consists
31+
of complete elements; incomplete data is buffered until more data is
32+
fed or \code{close()} is called.
33+
\end{funcdesc}
34+
35+
\begin{funcdesc}{close}{}
36+
Force processing of all buffered data as if it were followed by an
37+
end-of-file mark. This method may be redefined by a derived class to
38+
define additional processing at the end of the input, but the
39+
redefined version should always call \code{XMLParser.close()}.
40+
\end{funcdesc}
41+
42+
\begin{funcdesc}{handle_starttag}{tag\, method\, attributes}
43+
This method is called to handle start tags for which a
44+
\code{start_\var{tag}()} method has been defined. The \code{tag}
45+
argument is the name of the tag, and the \code{method} argument is the
46+
bound method which should be used to support semantic interpretation
47+
of the start tag. The \var{attributes} argument is a dictionary of
48+
attributes, the key being the \var{name} and the value being the
49+
\var{value} of the attribute found inside the tag's \code{<>} brackets.
50+
Lower case and double quotes and backslashes in the \var{value} have
51+
been interpreted. For instance, for the tag
52+
\code{<A HREF="http://www.cwi.nl/">}, this method would be called as
53+
\code{handle_starttag('A', self.start_A, {'HREF': 'http://www.cwi.nl/'})}.
54+
The base implementation simply calls \code{method} with \code{attributes}
55+
as the only argument.
56+
\end{funcdesc}
57+
58+
\begin{funcdesc}{handle_endtag}{tag\, method}
59+
This method is called to handle endtags for which an
60+
\code{end_\var{tag}()} method has been defined. The \code{tag}
61+
argument is the name of the tag, and the
62+
\code{method} argument is the bound method which should be used to
63+
support semantic interpretation of the end tag. If no
64+
\code{end_\var{tag}()} method is defined for the closing element, this
65+
handler is not called. The base implementation simply calls
66+
\code{method}.
67+
\end{funcdesc}
68+
69+
\begin{funcdesc}{handle_data}{data}
70+
This method is called to process arbitrary data. It is intended to be
71+
overridden by a derived class; the base class implementation does
72+
nothing.
73+
\end{funcdesc}
74+
75+
\begin{funcdesc}{handle_charref}{ref}
76+
This method is called to process a character reference of the form
77+
``\code{\&\#\var{ref};}''. \var{ref} can either be a decimal number,
78+
or a hexadecimal number when preceded by \code{x}.
79+
In the base implementation, \var{ref} must be a number in the
80+
range 0-255. It translates the character to \ASCII{} and calls the
81+
method \code{handle_data()} with the character as argument. If
82+
\var{ref} is invalid or out of range, the method
83+
\code{unknown_charref(\var{ref})} is called to handle the error. A
84+
subclass must override this method to provide support for character
85+
references outside of the \ASCII{} range.
86+
\end{funcdesc}
87+
88+
\begin{funcdesc}{handle_entityref}{ref}
89+
This method is called to process a general entity reference of the form
90+
``\code{\&\var{ref};}'' where \var{ref} is an general entity
91+
reference. It looks for \var{ref} in the instance (or class)
92+
variable \code{entitydefs} which should be a mapping from entity names
93+
to corresponding translations.
94+
If a translation is found, it calls the method \code{handle_data()}
95+
with the translation; otherwise, it calls the method
96+
\code{unknown_entityref(\var{ref})}. The default \code{entitydefs}
97+
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
98+
\code{\&lt;}, and \code{\&quot;}.
99+
\end{funcdesc}
100+
101+
\begin{funcdesc}{handle_comment}{comment}
102+
This method is called when a comment is encountered. The
103+
\code{comment} argument is a string containing the text between the
104+
``\code{<!--}'' and ``\code{-->}'' delimiters, but not the delimiters
105+
themselves. For example, the comment ``\code{<!--text-->}'' will
106+
cause this method to be called with the argument \code{'text'}. The
107+
default method does nothing.
108+
\end{funcdesc}
109+
110+
\begin{funcdesc}{handle_cdata}{data}
111+
This method is called when a CDATA element is encountered. The
112+
\code{data} argument is a string containing the text between the
113+
``\code{<![CDATA[}'' and ``\code{]]>}'' delimiters, but not the delimiters
114+
themselves. For example, the entity ``\code{<![CDATA[text]]>}'' will
115+
cause this method to be called with the argument \code{'text'}. The
116+
default method does nothing.
117+
\end{funcdesc}
118+
119+
\begin{funcdesc}{handle_proc}{name\, data}
120+
This method is called when a processing instruction (PI) is encountered. The
121+
\code{name} is the PI target, and the \code{data} argument is a
122+
string containing the text between the PI target and the closing delimiter,
123+
but not the delimiter itself. For example, the instruction
124+
``\code{<?XML text?>}'' will cause this method to be called with the
125+
arguments \code{'XML'} and \code{'text'}. The default method does
126+
nothing.
127+
\end{funcdesc}
128+
129+
\begin{funcdesc}{handle_special}{data}
130+
This method is called when a declaration is encountered. The
131+
\code{data} argument is a string containing the text between the
132+
``\code{<!}'' and ``\code{>}'' delimiters, but not the delimiters
133+
themselves. For example, the entity ``\code{<!DOCTYPE text>}'' will
134+
cause this method to be called with the argument \code{'DOCTYPE text'}. The
135+
default method does nothing.
136+
\end{funcdesc}
137+
138+
\begin{funcdesc}{syntax_error}{lineno\, message}
139+
This method is called when a syntax error is encountered. The
140+
\code{lineno} argument is the line number of the error, and the
141+
\code{message} is a description of what was wrong. The default method
142+
raises a \code{RuntimeError} exception. If this method is overridden,
143+
it is permissable for it to return. This method is only called when
144+
the error can be recovered from.
145+
\end{funcdesc}
146+
147+
\begin{funcdesc}{unknown_starttag}{tag\, attributes}
148+
This method is called to process an unknown start tag. It is intended
149+
to be overridden by a derived class; the base class implementation
150+
does nothing.
151+
\end{funcdesc}
152+
153+
\begin{funcdesc}{unknown_endtag}{tag}
154+
This method is called to process an unknown end tag. It is intended
155+
to be overridden by a derived class; the base class implementation
156+
does nothing.
157+
\end{funcdesc}
158+
159+
\begin{funcdesc}{unknown_charref}{ref}
160+
This method is called to process unresolvable numeric character
161+
references. It is intended to be overridden by a derived class; the
162+
base class implementation does nothing.
163+
\end{funcdesc}
164+
165+
\begin{funcdesc}{unknown_entityref}{ref}
166+
This method is called to process an unknown entity reference. It is
167+
intended to be overridden by a derived class; the base class
168+
implementation does nothing.
169+
\end{funcdesc}
170+
171+
Apart from overriding or extending the methods listed above, derived
172+
classes may also define methods of the following form to define
173+
processing of specific tags. Tag names in the input stream are case
174+
dependent; the \var{tag} occurring in method names must be in the
175+
correct case:
176+
177+
\begin{funcdesc}{start_\var{tag}}{attributes}
178+
This method is called to process an opening tag \var{tag}. The
179+
\var{attributes} argument has the same meaning as described for
180+
\code{handle_starttag()} above.
181+
\end{funcdesc}
182+
183+
\begin{funcdesc}{end_\var{tag}}{}
184+
This method is called to process a closing tag \var{tag}.
185+
\end{funcdesc}

‎Doc/libxmllib.tex‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
\section{Standard Module \sectcode{xmllib}}
2+
% Author: Sjoerd Mullender
3+
\label{module-xmllib}
4+
\stmodindex{xmllib}
5+
\index{XML}
6+
7+
This module defines a class \code{XMLParser} which serves as the basis
8+
for parsing text files formatted in XML (eXtended Markup Language).
9+
10+
The \code{XMLParser} class must be instantiated without arguments. It
11+
has the following interface methods:
12+
13+
\renewcommand{\indexsubitem}{({\tt XMLParser} method)}
14+
15+
\begin{funcdesc}{reset}{}
16+
Reset the instance. Loses all unprocessed data. This is called
17+
implicitly at the instantiation time.
18+
\end{funcdesc}
19+
20+
\begin{funcdesc}{setnomoretags}{}
21+
Stop processing tags. Treat all following input as literal input
22+
(CDATA).
23+
\end{funcdesc}
24+
25+
\begin{funcdesc}{setliteral}{}
26+
Enter literal mode (CDATA mode).
27+
\end{funcdesc}
28+
29+
\begin{funcdesc}{feed}{data}
30+
Feed some text to the parser. It is processed insofar as it consists
31+
of complete elements; incomplete data is buffered until more data is
32+
fed or \code{close()} is called.
33+
\end{funcdesc}
34+
35+
\begin{funcdesc}{close}{}
36+
Force processing of all buffered data as if it were followed by an
37+
end-of-file mark. This method may be redefined by a derived class to
38+
define additional processing at the end of the input, but the
39+
redefined version should always call \code{XMLParser.close()}.
40+
\end{funcdesc}
41+
42+
\begin{funcdesc}{handle_starttag}{tag\, method\, attributes}
43+
This method is called to handle start tags for which a
44+
\code{start_\var{tag}()} method has been defined. The \code{tag}
45+
argument is the name of the tag, and the \code{method} argument is the
46+
bound method which should be used to support semantic interpretation
47+
of the start tag. The \var{attributes} argument is a dictionary of
48+
attributes, the key being the \var{name} and the value being the
49+
\var{value} of the attribute found inside the tag's \code{<>} brackets.
50+
Lower case and double quotes and backslashes in the \var{value} have
51+
been interpreted. For instance, for the tag
52+
\code{<A HREF="http://www.cwi.nl/">}, this method would be called as
53+
\code{handle_starttag('A', self.start_A, {'HREF': 'http://www.cwi.nl/'})}.
54+
The base implementation simply calls \code{method} with \code{attributes}
55+
as the only argument.
56+
\end{funcdesc}
57+
58+
\begin{funcdesc}{handle_endtag}{tag\, method}
59+
This method is called to handle endtags for which an
60+
\code{end_\var{tag}()} method has been defined. The \code{tag}
61+
argument is the name of the tag, and the
62+
\code{method} argument is the bound method which should be used to
63+
support semantic interpretation of the end tag. If no
64+
\code{end_\var{tag}()} method is defined for the closing element, this
65+
handler is not called. The base implementation simply calls
66+
\code{method}.
67+
\end{funcdesc}
68+
69+
\begin{funcdesc}{handle_data}{data}
70+
This method is called to process arbitrary data. It is intended to be
71+
overridden by a derived class; the base class implementation does
72+
nothing.
73+
\end{funcdesc}
74+
75+
\begin{funcdesc}{handle_charref}{ref}
76+
This method is called to process a character reference of the form
77+
``\code{\&\#\var{ref};}''. \var{ref} can either be a decimal number,
78+
or a hexadecimal number when preceded by \code{x}.
79+
In the base implementation, \var{ref} must be a number in the
80+
range 0-255. It translates the character to \ASCII{} and calls the
81+
method \code{handle_data()} with the character as argument. If
82+
\var{ref} is invalid or out of range, the method
83+
\code{unknown_charref(\var{ref})} is called to handle the error. A
84+
subclass must override this method to provide support for character
85+
references outside of the \ASCII{} range.
86+
\end{funcdesc}
87+
88+
\begin{funcdesc}{handle_entityref}{ref}
89+
This method is called to process a general entity reference of the form
90+
``\code{\&\var{ref};}'' where \var{ref} is an general entity
91+
reference. It looks for \var{ref} in the instance (or class)
92+
variable \code{entitydefs} which should be a mapping from entity names
93+
to corresponding translations.
94+
If a translation is found, it calls the method \code{handle_data()}
95+
with the translation; otherwise, it calls the method
96+
\code{unknown_entityref(\var{ref})}. The default \code{entitydefs}
97+
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
98+
\code{\&lt;}, and \code{\&quot;}.
99+
\end{funcdesc}
100+
101+
\begin{funcdesc}{handle_comment}{comment}
102+
This method is called when a comment is encountered. The
103+
\code{comment} argument is a string containing the text between the
104+
``\code{<!--}'' and ``\code{-->}'' delimiters, but not the delimiters
105+
themselves. For example, the comment ``\code{<!--text-->}'' will
106+
cause this method to be called with the argument \code{'text'}. The
107+
default method does nothing.
108+
\end{funcdesc}
109+
110+
\begin{funcdesc}{handle_cdata}{data}
111+
This method is called when a CDATA element is encountered. The
112+
\code{data} argument is a string containing the text between the
113+
``\code{<![CDATA[}'' and ``\code{]]>}'' delimiters, but not the delimiters
114+
themselves. For example, the entity ``\code{<![CDATA[text]]>}'' will
115+
cause this method to be called with the argument \code{'text'}. The
116+
default method does nothing.
117+
\end{funcdesc}
118+
119+
\begin{funcdesc}{handle_proc}{name\, data}
120+
This method is called when a processing instruction (PI) is encountered. The
121+
\code{name} is the PI target, and the \code{data} argument is a
122+
string containing the text between the PI target and the closing delimiter,
123+
but not the delimiter itself. For example, the instruction
124+
``\code{<?XML text?>}'' will cause this method to be called with the
125+
arguments \code{'XML'} and \code{'text'}. The default method does
126+
nothing.
127+
\end{funcdesc}
128+
129+
\begin{funcdesc}{handle_special}{data}
130+
This method is called when a declaration is encountered. The
131+
\code{data} argument is a string containing the text between the
132+
``\code{<!}'' and ``\code{>}'' delimiters, but not the delimiters
133+
themselves. For example, the entity ``\code{<!DOCTYPE text>}'' will
134+
cause this method to be called with the argument \code{'DOCTYPE text'}. The
135+
default method does nothing.
136+
\end{funcdesc}
137+
138+
\begin{funcdesc}{syntax_error}{lineno\, message}
139+
This method is called when a syntax error is encountered. The
140+
\code{lineno} argument is the line number of the error, and the
141+
\code{message} is a description of what was wrong. The default method
142+
raises a \code{RuntimeError} exception. If this method is overridden,
143+
it is permissable for it to return. This method is only called when
144+
the error can be recovered from.
145+
\end{funcdesc}
146+
147+
\begin{funcdesc}{unknown_starttag}{tag\, attributes}
148+
This method is called to process an unknown start tag. It is intended
149+
to be overridden by a derived class; the base class implementation
150+
does nothing.
151+
\end{funcdesc}
152+
153+
\begin{funcdesc}{unknown_endtag}{tag}
154+
This method is called to process an unknown end tag. It is intended
155+
to be overridden by a derived class; the base class implementation
156+
does nothing.
157+
\end{funcdesc}
158+
159+
\begin{funcdesc}{unknown_charref}{ref}
160+
This method is called to process unresolvable numeric character
161+
references. It is intended to be overridden by a derived class; the
162+
base class implementation does nothing.
163+
\end{funcdesc}
164+
165+
\begin{funcdesc}{unknown_entityref}{ref}
166+
This method is called to process an unknown entity reference. It is
167+
intended to be overridden by a derived class; the base class
168+
implementation does nothing.
169+
\end{funcdesc}
170+
171+
Apart from overriding or extending the methods listed above, derived
172+
classes may also define methods of the following form to define
173+
processing of specific tags. Tag names in the input stream are case
174+
dependent; the \var{tag} occurring in method names must be in the
175+
correct case:
176+
177+
\begin{funcdesc}{start_\var{tag}}{attributes}
178+
This method is called to process an opening tag \var{tag}. The
179+
\var{attributes} argument has the same meaning as described for
180+
\code{handle_starttag()} above.
181+
\end{funcdesc}
182+
183+
\begin{funcdesc}{end_\var{tag}}{}
184+
This method is called to process a closing tag \var{tag}.
185+
\end{funcdesc}

0 commit comments

Comments
 (0)