mirror of https://github.com/python/cpython
Logical markup.
This commit is contained in:
parent
2dde74c778
commit
3b5da76182
|
@ -6,8 +6,9 @@
|
|||
|
||||
This module supports two interface definitions, each with mulitple
|
||||
implementations. The \emph{formatter} interface is used by the
|
||||
\code{HTMLParser} class of the \code{htmllib} module, and the
|
||||
\class{HTMLParser} class of the \module{htmllib} module, and the
|
||||
\emph{writer} interface is required by the formatter interface.
|
||||
\withsubitem{(im module htmllib)}{\ttindex{HTMLParser}}
|
||||
|
||||
Formatter objects transform an abstract flow of formatting events into
|
||||
specific output events on writer objects. Formatters manage several
|
||||
|
@ -47,17 +48,17 @@ be called without having to track whether the property was changed.
|
|||
|
||||
The following attributes are defined for formatter instance objects:
|
||||
|
||||
\setindexsubitem{(formatter object data)}
|
||||
\setindexsubitem{(formatter attribute)}
|
||||
|
||||
\begin{datadesc}{writer}
|
||||
The writer instance with which the formatter interacts.
|
||||
\end{datadesc}
|
||||
|
||||
|
||||
\setindexsubitem{(formatter object method)}
|
||||
\setindexsubitem{(formatter method)}
|
||||
|
||||
\begin{funcdesc}{end_paragraph}{blanklines}
|
||||
Close any open paragraphs and insert at least \code{blanklines}
|
||||
Close any open paragraphs and insert at least \var{blanklines}
|
||||
before the next paragraph.
|
||||
\end{funcdesc}
|
||||
|
||||
|
@ -70,13 +71,13 @@ break the logical paragraph.
|
|||
Insert a horizontal rule in the output. A hard break is inserted if
|
||||
there is data in the current paragraph, but the logical paragraph is
|
||||
not broken. The arguments and keywords are passed on to the writer's
|
||||
\code{send_line_break()} method.
|
||||
\method{send_line_break()} method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{add_flowing_data}{data}
|
||||
Provide data which should be formatted with collapsed whitespaces.
|
||||
Whitespace from preceeding and successive calls to
|
||||
\code{add_flowing_data()} is considered as well when the whitespace
|
||||
\method{add_flowing_data()} is considered as well when the whitespace
|
||||
collapse is performed. The data which is passed to this method is
|
||||
expected to be word-wrapped by the output device. Note that any
|
||||
word-wrapping still must be performed by the writer object due to the
|
||||
|
@ -86,55 +87,55 @@ need to rely on device and font information.
|
|||
\begin{funcdesc}{add_literal_data}{data}
|
||||
Provide data which should be passed to the writer unchanged.
|
||||
Whitespace, including newline and tab characters, are considered legal
|
||||
in the value of \code{data}.
|
||||
in the value of \var{data}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{add_label_data}{format, counter}
|
||||
Insert a label which should be placed to the left of the current left
|
||||
margin. This should be used for constructing bulleted or numbered
|
||||
lists. If the \code{format} value is a string, it is interpreted as a
|
||||
format specification for \code{counter}, which should be an integer.
|
||||
lists. If the \var{format} value is a string, it is interpreted as a
|
||||
format specification for \var{counter}, which should be an integer.
|
||||
The result of this formatting becomes the value of the label; if
|
||||
\code{format} is not a string it is used as the label value directly.
|
||||
\var{format} is not a string it is used as the label value directly.
|
||||
The label value is passed as the only argument to the writer's
|
||||
\code{send_label_data()} method. Interpretation of non-string label
|
||||
\method{send_label_data()} method. Interpretation of non-string label
|
||||
values is dependent on the associated writer.
|
||||
|
||||
Format specifications are strings which, in combination with a counter
|
||||
value, are used to compute label values. Each character in the format
|
||||
string is copied to the label value, with some characters recognized
|
||||
to indicate a transform on the counter value. Specifically, the
|
||||
character \samp{1} represents the counter value formatter as an
|
||||
arabic number, the characters \samp{A} and \samp{a} represent
|
||||
alphabetic representations of the counter value in upper and lower
|
||||
case, respectively, and \samp{I} and \samp{i} represent the
|
||||
counter value in Roman numerals, in upper and lower case. Note that
|
||||
the alphabetic and roman transforms require that the counter value be
|
||||
greater than zero.
|
||||
character \character{1} represents the counter value formatter as an
|
||||
arabic number, the characters \character{A} and \character{a}
|
||||
represent alphabetic representations of the counter value in upper and
|
||||
lower case, respectively, and \character{I} and \character{i}
|
||||
represent the counter value in Roman numerals, in upper and lower
|
||||
case. Note that the alphabetic and roman transforms require that the
|
||||
counter value be greater than zero.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{flush_softspace}{}
|
||||
Send any pending whitespace buffered from a previous call to
|
||||
\code{add_flowing_data()} to the associated writer object. This
|
||||
\method{add_flowing_data()} to the associated writer object. This
|
||||
should be called before any direct manipulation of the writer object.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{push_alignment}{align}
|
||||
Push a new alignment setting onto the alignment stack. This may be
|
||||
\code{AS_IS} if no change is desired. If the alignment value is
|
||||
changed from the previous setting, the writer's \code{new_alignment()}
|
||||
method is called with the \code{align} value.
|
||||
\constant{AS_IS} if no change is desired. If the alignment value is
|
||||
changed from the previous setting, the writer's \method{new_alignment()}
|
||||
method is called with the \var{align} value.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pop_alignment}{}
|
||||
Restore the previous alignment.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{push_font}{(size, italic, bold, teletype)}
|
||||
\begin{funcdesc}{push_font}{\code{(}size, italic, bold, teletype\code{)}}
|
||||
Change some or all font properties of the writer object. Properties
|
||||
which are not set to \code{AS_IS} are set to the values passed in
|
||||
which are not set to \constant{AS_IS} are set to the values passed in
|
||||
while others are maintained at their current settings. The writer's
|
||||
\code{new_font()} method is called with the fully resolved font
|
||||
\method{new_font()} method is called with the fully resolved font
|
||||
specification.
|
||||
\end{funcdesc}
|
||||
|
||||
|
@ -144,10 +145,10 @@ Restore the previous font.
|
|||
|
||||
\begin{funcdesc}{push_margin}{margin}
|
||||
Increase the number of left margin indentations by one, associating
|
||||
the logical tag \code{margin} with the new indentation. The initial
|
||||
the logical tag \var{margin} with the new indentation. The initial
|
||||
margin level is \code{0}. Changed values of the logical tag must be
|
||||
true values; false values other than \code{AS_IS} are not sufficient
|
||||
to change the margin.
|
||||
true values; false values other than \constant{AS_IS} are not
|
||||
sufficient to change the margin.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pop_margin}{}
|
||||
|
@ -157,15 +158,15 @@ Restore the previous margin.
|
|||
\begin{funcdesc}{push_style}{*styles}
|
||||
Push any number of arbitrary style specifications. All styles are
|
||||
pushed onto the styles stack in order. A tuple representing the
|
||||
entire stack, including \code{AS_IS} values, is passed to the writer's
|
||||
\code{new_styles()} method.
|
||||
entire stack, including \constant{AS_IS} values, is passed to the
|
||||
writer's \method{new_styles()} method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pop_style}{\optional{n\code{ = 1}}}
|
||||
Pop the last \code{n} style specifications passed to
|
||||
\code{push_style()}. A tuple representing the revised stack,
|
||||
including \code{AS_IS} values, is passed to the writer's
|
||||
\code{new_styles()} method.
|
||||
Pop the last \var{n} style specifications passed to
|
||||
\method{push_style()}. A tuple representing the revised stack,
|
||||
including \constant{AS_IS} values, is passed to the writer's
|
||||
\method{new_styles()} method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{set_spacing}{spacing}
|
||||
|
@ -175,7 +176,7 @@ Set the spacing style for the writer.
|
|||
\begin{funcdesc}{assert_line_data}{\optional{flag\code{ = 1}}}
|
||||
Inform the formatter that data has been added to the current paragraph
|
||||
out-of-band. This should be used when the writer has been manipulated
|
||||
directly. The optional \code{flag} argument can be set to false if
|
||||
directly. The optional \var{flag} argument can be set to false if
|
||||
the writer manipulations produced a hard line break at the end of the
|
||||
output.
|
||||
\end{funcdesc}
|
||||
|
@ -189,20 +190,20 @@ subclassing.
|
|||
|
||||
\setindexsubitem{(in module formatter)}
|
||||
|
||||
\begin{funcdesc}{NullFormatter}{\optional{writer\code{ = None}}}
|
||||
A formatter which does nothing. If \code{writer} is omitted, a
|
||||
\code{NullWriter} instance is created. No methods of the writer are
|
||||
called by \code{NullWriter} instances. Implementations should inherit
|
||||
from this class if implementing a writer interface but don't need to
|
||||
inherit any implementation.
|
||||
\end{funcdesc}
|
||||
\begin{classdesc}{NullFormatter}{\optional{writer}}
|
||||
A formatter which does nothing. If \var{writer} is omitted, a
|
||||
\class{NullWriter} instance is created. No methods of the writer are
|
||||
called by \class{NullFormatter} instances. Implementations should
|
||||
inherit from this class if implementing a writer interface but don't
|
||||
need to inherit any implementation.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{funcdesc}{AbstractFormatter}{writer}
|
||||
\begin{classdesc}{AbstractFormatter}{writer}
|
||||
The standard formatter. This implementation has demonstrated wide
|
||||
applicability to many writers, and may be used directly in most
|
||||
circumstances. It has been used to implement a full-featured
|
||||
world-wide web browser.
|
||||
\end{funcdesc}
|
||||
\end{classdesc}
|
||||
|
||||
|
||||
|
||||
|
@ -211,9 +212,9 @@ world-wide web browser.
|
|||
Interfaces to create writers are dependent on the specific writer
|
||||
class being instantiated. The interfaces described below are the
|
||||
required interfaces which all writers must support once initialized.
|
||||
Note that while most applications can use the \code{AbstractFormatter}
|
||||
class as a formatter, the writer must typically be provided by the
|
||||
application.
|
||||
Note that while most applications can use the
|
||||
\class{AbstractFormatter} class as a formatter, the writer must
|
||||
typically be provided by the application.
|
||||
|
||||
\setindexsubitem{(writer object method)}
|
||||
|
||||
|
@ -222,40 +223,40 @@ Flush any buffered output or device control events.
|
|||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_alignment}{align}
|
||||
Set the alignment style. The \code{align} value can be any object,
|
||||
Set the alignment style. The \var{align} value can be any object,
|
||||
but by convention is a string or \code{None}, where \code{None}
|
||||
indicates that the writer's ``preferred'' alignment should be used.
|
||||
Conventional \code{align} values are \code{'left'}, \code{'center'},
|
||||
Conventional \var{align} values are \code{'left'}, \code{'center'},
|
||||
\code{'right'}, and \code{'justify'}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_font}{font}
|
||||
Set the font style. The value of \code{font} will be \code{None},
|
||||
Set the font style. The value of \var{font} will be \code{None},
|
||||
indicating that the device's default font should be used, or a tuple
|
||||
of the form (\var{size}, \var{italic}, \var{bold}, \var{teletype}).
|
||||
Size will be a string indicating the size of font that should be used;
|
||||
specific strings and their interpretation must be defined by the
|
||||
application. The \var{italic}, \var{bold}, and \var{teletype} values
|
||||
are boolean indicators specifying which of those font attributes
|
||||
should be used.
|
||||
of the form \code{(}\var{size}, \var{italic}, \var{bold},
|
||||
\var{teletype}\code{)}. Size will be a string indicating the size of
|
||||
font that should be used; specific strings and their interpretation
|
||||
must be defined by the application. The \var{italic}, \var{bold}, and
|
||||
\var{teletype} values are boolean indicators specifying which of those
|
||||
font attributes should be used.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_margin}{margin, level}
|
||||
Set the margin level to the integer \code{level} and the logical tag
|
||||
to \code{margin}. Interpretation of the logical tag is at the
|
||||
Set the margin level to the integer \var{level} and the logical tag
|
||||
to \var{margin}. Interpretation of the logical tag is at the
|
||||
writer's discretion; the only restriction on the value of the logical
|
||||
tag is that it not be a false value for non-zero values of
|
||||
\code{level}.
|
||||
\var{level}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_spacing}{spacing}
|
||||
Set the spacing style to \code{spacing}.
|
||||
Set the spacing style to \var{spacing}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_styles}{styles}
|
||||
Set additional styles. The \code{styles} value is a tuple of
|
||||
arbitrary values; the value \code{AS_IS} should be ignored. The
|
||||
\code{styles} tuple may be interpreted either as a set or as a stack
|
||||
Set additional styles. The \var{styles} value is a tuple of
|
||||
arbitrary values; the value \constant{AS_IS} should be ignored. The
|
||||
\var{styles} tuple may be interpreted either as a set or as a stack
|
||||
depending on the requirements of the application and writer
|
||||
implementation.
|
||||
\end{funcdesc}
|
||||
|
@ -265,8 +266,8 @@ Break the current line.
|
|||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{send_paragraph}{blankline}
|
||||
Produce a paragraph separation of at least \code{blankline} blank
|
||||
lines, or the equivelent. The \code{blankline} value will be an
|
||||
Produce a paragraph separation of at least \var{blankline} blank
|
||||
lines, or the equivelent. The \var{blankline} value will be an
|
||||
integer.
|
||||
\end{funcdesc}
|
||||
|
||||
|
@ -274,7 +275,7 @@ integer.
|
|||
Display a horizontal rule on the output device. The arguments to this
|
||||
method are entirely application- and writer-specific, and should be
|
||||
interpreted with care. The method implementation may assume that a
|
||||
line break has already been issued via \code{send_line_break()}.
|
||||
line break has already been issued via \method{send_line_break()}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{send_flowing_data}{data}
|
||||
|
@ -290,12 +291,12 @@ for display. Generally, this should be interpreted to mean that line
|
|||
breaks indicated by newline characters should be preserved and no new
|
||||
line breaks should be introduced. The data may contain embedded
|
||||
newline and tab characters, unlike data provided to the
|
||||
\code{send_formatted_data()} interface.
|
||||
\method{send_formatted_data()} interface.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{send_label_data}{data}
|
||||
Set \code{data} to the left of the current left margin, if possible.
|
||||
The value of \code{data} is not restricted; treatment of non-string
|
||||
Set \var{data} to the left of the current left margin, if possible.
|
||||
The value of \var{data} is not restricted; treatment of non-string
|
||||
values is entirely application- and writer-dependent. This method
|
||||
will only be called at the beginning of a line.
|
||||
\end{funcdesc}
|
||||
|
@ -305,7 +306,7 @@ will only be called at the beginning of a line.
|
|||
|
||||
Three implementations of the writer object interface are provided as
|
||||
examples by this module. Most applications will need to derive new
|
||||
writer classes from the \code{NullWriter} class.
|
||||
writer classes from the \class{NullWriter} class.
|
||||
|
||||
\setindexsubitem{(in module formatter)}
|
||||
|
||||
|
@ -321,10 +322,10 @@ else. Each method simply announces itself by printing its name and
|
|||
arguments on standard output.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{DumbWriter}{\optional{file\code{ = None}\optional{\, maxcol\code{ = 72}}}}
|
||||
\begin{funcdesc}{DumbWriter}{\optional{file\optional{\, maxcol\code{ = 72}}}}
|
||||
Simple writer class which writes output on the file object passed in
|
||||
as \code{file} or, if \code{file} is omitted, on standard output. The
|
||||
as \var{file} or, if \var{file} is omitted, on standard output. The
|
||||
output is simply word-wrapped to the number of columns specified by
|
||||
\code{maxcol}. This class is suitable for reflowing a sequence of
|
||||
\var{maxcol}. This class is suitable for reflowing a sequence of
|
||||
paragraphs.
|
||||
\end{funcdesc}
|
||||
|
|
|
@ -4,11 +4,14 @@
|
|||
\stmodindex{xmllib}
|
||||
\index{XML}
|
||||
|
||||
This module defines a class \code{XMLParser} which serves as the basis
|
||||
This module defines a class \class{XMLParser} which serves as the basis
|
||||
for parsing text files formatted in XML (eXtended Markup Language).
|
||||
|
||||
The \code{XMLParser} class must be instantiated without arguments. It
|
||||
has the following interface methods:
|
||||
\begin{classdesc}{XMLParser}{}
|
||||
The \class{XMLParser} class must be instantiated without arguments.
|
||||
\end{classdesc}
|
||||
|
||||
This class provides the following interface methods:
|
||||
|
||||
\setindexsubitem{(XMLParser method)}
|
||||
|
||||
|
@ -29,40 +32,40 @@ Enter literal mode (CDATA mode).
|
|||
\begin{funcdesc}{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 \code{close()} is called.
|
||||
fed or \method{close()} is called.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{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 \code{XMLParser.close()}.
|
||||
redefined version should always call \method{close()}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{translate_references}{data}
|
||||
Translate all entity and character references in \code{data} and
|
||||
Translate all entity and character references in \var{data} and
|
||||
returns the translated string.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_xml}{encoding\, standalone}
|
||||
\begin{funcdesc}{handle_xml}{encoding, standalone}
|
||||
This method is called when the \code{<?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 \code{handle_xml} default to \code{None} and the string
|
||||
passed to \method{handle_xml()} default to \code{None} and the string
|
||||
\code{'no'} respectively.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_doctype}{tag\, data}
|
||||
\begin{funcdesc}{handle_doctype}{tag, data}
|
||||
This method is called when the \code{<!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{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_starttag}{tag\, method\, attributes}
|
||||
\begin{funcdesc}{handle_starttag}{tag, method, attributes}
|
||||
This method is called to handle start tags for which a
|
||||
\code{start_\var{tag}()} method has been defined. The \code{tag}
|
||||
argument is the name of the tag, and the \code{method} argument is the
|
||||
\code{start_\var{tag}()} method has been defined. The \var{tag}
|
||||
argument is the name of the tag, and the \method{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
|
||||
|
@ -71,19 +74,19 @@ 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 \code{method} with \code{attributes}
|
||||
The base implementation simply calls \var{method} with \var{attributes}
|
||||
as the only argument.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_endtag}{tag\, method}
|
||||
This method is called to handle endtags for which an
|
||||
\code{end_\var{tag}()} method has been defined. The \code{tag}
|
||||
\code{end_\var{tag}()} method has been defined. The \var{tag}
|
||||
argument is the name of the tag, and the
|
||||
\code{method} argument is the bound method which should be used to
|
||||
\var{method} argument is the bound method which should be used to
|
||||
support semantic interpretation of the end tag. If no
|
||||
\code{end_\var{tag}()} method is defined for the closing element, this
|
||||
handler is not called. The base implementation simply calls
|
||||
\code{method}.
|
||||
\var{method}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_data}{data}
|
||||
|
@ -98,7 +101,7 @@ This method is called to process a character reference of the form
|
|||
or a hexadecimal number when preceded by \code{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 \code{handle_data()} with the character as argument. If
|
||||
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
|
||||
|
@ -106,21 +109,21 @@ references outside of the \ASCII{} range.
|
|||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{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
|
||||
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 \code{entitydefs} which should be a mapping from entity names
|
||||
to corresponding translations.
|
||||
If a translation is found, it calls the method \code{handle_data()}
|
||||
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 \code{entitydefs}
|
||||
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
|
||||
defines translations for \code{\&}, \code{\&apos}, \code{\>},
|
||||
\code{\<}, and \code{\"}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_comment}{comment}
|
||||
This method is called when a comment is encountered. The
|
||||
\code{comment} argument is a string containing the text between 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
|
||||
|
@ -129,27 +132,27 @@ default method does nothing.
|
|||
|
||||
\begin{funcdesc}{handle_cdata}{data}
|
||||
This method is called when a CDATA element is encountered. The
|
||||
\code{data} argument is a string containing the text between 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.
|
||||
default method does nothing, and is intended to be overridden.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_proc}{name\, data}
|
||||
This method is called when a processing instruction (PI) is encountered. The
|
||||
\code{name} is the PI target, and the \code{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 a \code{<?xml ...?>}
|
||||
tag, \code{handle_xml} is called to handle it.
|
||||
\begin{funcdesc}{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 \code{<?xml
|
||||
...?>}, \method{handle_xml()} is called to handle it.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_special}{data}
|
||||
This method is called when a declaration is encountered. The
|
||||
\code{data} argument is a string containing the text between 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
|
||||
|
@ -159,11 +162,12 @@ handled separately if it is located at the start of the document.
|
|||
|
||||
\begin{funcdesc}{syntax_error}{message}
|
||||
This method is called when a syntax error is encountered. The
|
||||
\code{message} is a description of what was wrong. The default method
|
||||
raises a \code{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
|
||||
\code{RuntimeError} without first calling \code{syntax_error}.
|
||||
\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{funcdesc}
|
||||
|
||||
\begin{funcdesc}{unknown_starttag}{tag\, attributes}
|
||||
|
@ -199,8 +203,8 @@ correct case:
|
|||
\begin{funcdescni}{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
|
||||
\code{handle_starttag()} above. In fact, the base implementation of
|
||||
\code{handle_starttag()} calls this method.
|
||||
\method{handle_starttag()} above. In fact, the base implementation of
|
||||
\method{handle_starttag()} calls this method.
|
||||
\end{funcdescni}
|
||||
|
||||
\begin{funcdescni}{end_\var{tag}}{}
|
||||
|
@ -215,7 +219,7 @@ 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 \code{handle_starttag()} and
|
||||
\code{unknown_starttag()} contains values for all attributes that have a
|
||||
default value.
|
||||
attribute dictionary that is passed to \method{handle_starttag()} and
|
||||
\method{unknown_starttag()} contains values for all attributes that
|
||||
have a default value.
|
||||
\end{datadescni}
|
||||
|
|
|
@ -6,8 +6,9 @@
|
|||
|
||||
This module supports two interface definitions, each with mulitple
|
||||
implementations. The \emph{formatter} interface is used by the
|
||||
\code{HTMLParser} class of the \code{htmllib} module, and the
|
||||
\class{HTMLParser} class of the \module{htmllib} module, and the
|
||||
\emph{writer} interface is required by the formatter interface.
|
||||
\withsubitem{(im module htmllib)}{\ttindex{HTMLParser}}
|
||||
|
||||
Formatter objects transform an abstract flow of formatting events into
|
||||
specific output events on writer objects. Formatters manage several
|
||||
|
@ -47,17 +48,17 @@ be called without having to track whether the property was changed.
|
|||
|
||||
The following attributes are defined for formatter instance objects:
|
||||
|
||||
\setindexsubitem{(formatter object data)}
|
||||
\setindexsubitem{(formatter attribute)}
|
||||
|
||||
\begin{datadesc}{writer}
|
||||
The writer instance with which the formatter interacts.
|
||||
\end{datadesc}
|
||||
|
||||
|
||||
\setindexsubitem{(formatter object method)}
|
||||
\setindexsubitem{(formatter method)}
|
||||
|
||||
\begin{funcdesc}{end_paragraph}{blanklines}
|
||||
Close any open paragraphs and insert at least \code{blanklines}
|
||||
Close any open paragraphs and insert at least \var{blanklines}
|
||||
before the next paragraph.
|
||||
\end{funcdesc}
|
||||
|
||||
|
@ -70,13 +71,13 @@ break the logical paragraph.
|
|||
Insert a horizontal rule in the output. A hard break is inserted if
|
||||
there is data in the current paragraph, but the logical paragraph is
|
||||
not broken. The arguments and keywords are passed on to the writer's
|
||||
\code{send_line_break()} method.
|
||||
\method{send_line_break()} method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{add_flowing_data}{data}
|
||||
Provide data which should be formatted with collapsed whitespaces.
|
||||
Whitespace from preceeding and successive calls to
|
||||
\code{add_flowing_data()} is considered as well when the whitespace
|
||||
\method{add_flowing_data()} is considered as well when the whitespace
|
||||
collapse is performed. The data which is passed to this method is
|
||||
expected to be word-wrapped by the output device. Note that any
|
||||
word-wrapping still must be performed by the writer object due to the
|
||||
|
@ -86,55 +87,55 @@ need to rely on device and font information.
|
|||
\begin{funcdesc}{add_literal_data}{data}
|
||||
Provide data which should be passed to the writer unchanged.
|
||||
Whitespace, including newline and tab characters, are considered legal
|
||||
in the value of \code{data}.
|
||||
in the value of \var{data}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{add_label_data}{format, counter}
|
||||
Insert a label which should be placed to the left of the current left
|
||||
margin. This should be used for constructing bulleted or numbered
|
||||
lists. If the \code{format} value is a string, it is interpreted as a
|
||||
format specification for \code{counter}, which should be an integer.
|
||||
lists. If the \var{format} value is a string, it is interpreted as a
|
||||
format specification for \var{counter}, which should be an integer.
|
||||
The result of this formatting becomes the value of the label; if
|
||||
\code{format} is not a string it is used as the label value directly.
|
||||
\var{format} is not a string it is used as the label value directly.
|
||||
The label value is passed as the only argument to the writer's
|
||||
\code{send_label_data()} method. Interpretation of non-string label
|
||||
\method{send_label_data()} method. Interpretation of non-string label
|
||||
values is dependent on the associated writer.
|
||||
|
||||
Format specifications are strings which, in combination with a counter
|
||||
value, are used to compute label values. Each character in the format
|
||||
string is copied to the label value, with some characters recognized
|
||||
to indicate a transform on the counter value. Specifically, the
|
||||
character \samp{1} represents the counter value formatter as an
|
||||
arabic number, the characters \samp{A} and \samp{a} represent
|
||||
alphabetic representations of the counter value in upper and lower
|
||||
case, respectively, and \samp{I} and \samp{i} represent the
|
||||
counter value in Roman numerals, in upper and lower case. Note that
|
||||
the alphabetic and roman transforms require that the counter value be
|
||||
greater than zero.
|
||||
character \character{1} represents the counter value formatter as an
|
||||
arabic number, the characters \character{A} and \character{a}
|
||||
represent alphabetic representations of the counter value in upper and
|
||||
lower case, respectively, and \character{I} and \character{i}
|
||||
represent the counter value in Roman numerals, in upper and lower
|
||||
case. Note that the alphabetic and roman transforms require that the
|
||||
counter value be greater than zero.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{flush_softspace}{}
|
||||
Send any pending whitespace buffered from a previous call to
|
||||
\code{add_flowing_data()} to the associated writer object. This
|
||||
\method{add_flowing_data()} to the associated writer object. This
|
||||
should be called before any direct manipulation of the writer object.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{push_alignment}{align}
|
||||
Push a new alignment setting onto the alignment stack. This may be
|
||||
\code{AS_IS} if no change is desired. If the alignment value is
|
||||
changed from the previous setting, the writer's \code{new_alignment()}
|
||||
method is called with the \code{align} value.
|
||||
\constant{AS_IS} if no change is desired. If the alignment value is
|
||||
changed from the previous setting, the writer's \method{new_alignment()}
|
||||
method is called with the \var{align} value.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pop_alignment}{}
|
||||
Restore the previous alignment.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{push_font}{(size, italic, bold, teletype)}
|
||||
\begin{funcdesc}{push_font}{\code{(}size, italic, bold, teletype\code{)}}
|
||||
Change some or all font properties of the writer object. Properties
|
||||
which are not set to \code{AS_IS} are set to the values passed in
|
||||
which are not set to \constant{AS_IS} are set to the values passed in
|
||||
while others are maintained at their current settings. The writer's
|
||||
\code{new_font()} method is called with the fully resolved font
|
||||
\method{new_font()} method is called with the fully resolved font
|
||||
specification.
|
||||
\end{funcdesc}
|
||||
|
||||
|
@ -144,10 +145,10 @@ Restore the previous font.
|
|||
|
||||
\begin{funcdesc}{push_margin}{margin}
|
||||
Increase the number of left margin indentations by one, associating
|
||||
the logical tag \code{margin} with the new indentation. The initial
|
||||
the logical tag \var{margin} with the new indentation. The initial
|
||||
margin level is \code{0}. Changed values of the logical tag must be
|
||||
true values; false values other than \code{AS_IS} are not sufficient
|
||||
to change the margin.
|
||||
true values; false values other than \constant{AS_IS} are not
|
||||
sufficient to change the margin.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pop_margin}{}
|
||||
|
@ -157,15 +158,15 @@ Restore the previous margin.
|
|||
\begin{funcdesc}{push_style}{*styles}
|
||||
Push any number of arbitrary style specifications. All styles are
|
||||
pushed onto the styles stack in order. A tuple representing the
|
||||
entire stack, including \code{AS_IS} values, is passed to the writer's
|
||||
\code{new_styles()} method.
|
||||
entire stack, including \constant{AS_IS} values, is passed to the
|
||||
writer's \method{new_styles()} method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pop_style}{\optional{n\code{ = 1}}}
|
||||
Pop the last \code{n} style specifications passed to
|
||||
\code{push_style()}. A tuple representing the revised stack,
|
||||
including \code{AS_IS} values, is passed to the writer's
|
||||
\code{new_styles()} method.
|
||||
Pop the last \var{n} style specifications passed to
|
||||
\method{push_style()}. A tuple representing the revised stack,
|
||||
including \constant{AS_IS} values, is passed to the writer's
|
||||
\method{new_styles()} method.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{set_spacing}{spacing}
|
||||
|
@ -175,7 +176,7 @@ Set the spacing style for the writer.
|
|||
\begin{funcdesc}{assert_line_data}{\optional{flag\code{ = 1}}}
|
||||
Inform the formatter that data has been added to the current paragraph
|
||||
out-of-band. This should be used when the writer has been manipulated
|
||||
directly. The optional \code{flag} argument can be set to false if
|
||||
directly. The optional \var{flag} argument can be set to false if
|
||||
the writer manipulations produced a hard line break at the end of the
|
||||
output.
|
||||
\end{funcdesc}
|
||||
|
@ -189,20 +190,20 @@ subclassing.
|
|||
|
||||
\setindexsubitem{(in module formatter)}
|
||||
|
||||
\begin{funcdesc}{NullFormatter}{\optional{writer\code{ = None}}}
|
||||
A formatter which does nothing. If \code{writer} is omitted, a
|
||||
\code{NullWriter} instance is created. No methods of the writer are
|
||||
called by \code{NullWriter} instances. Implementations should inherit
|
||||
from this class if implementing a writer interface but don't need to
|
||||
inherit any implementation.
|
||||
\end{funcdesc}
|
||||
\begin{classdesc}{NullFormatter}{\optional{writer}}
|
||||
A formatter which does nothing. If \var{writer} is omitted, a
|
||||
\class{NullWriter} instance is created. No methods of the writer are
|
||||
called by \class{NullFormatter} instances. Implementations should
|
||||
inherit from this class if implementing a writer interface but don't
|
||||
need to inherit any implementation.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{funcdesc}{AbstractFormatter}{writer}
|
||||
\begin{classdesc}{AbstractFormatter}{writer}
|
||||
The standard formatter. This implementation has demonstrated wide
|
||||
applicability to many writers, and may be used directly in most
|
||||
circumstances. It has been used to implement a full-featured
|
||||
world-wide web browser.
|
||||
\end{funcdesc}
|
||||
\end{classdesc}
|
||||
|
||||
|
||||
|
||||
|
@ -211,9 +212,9 @@ world-wide web browser.
|
|||
Interfaces to create writers are dependent on the specific writer
|
||||
class being instantiated. The interfaces described below are the
|
||||
required interfaces which all writers must support once initialized.
|
||||
Note that while most applications can use the \code{AbstractFormatter}
|
||||
class as a formatter, the writer must typically be provided by the
|
||||
application.
|
||||
Note that while most applications can use the
|
||||
\class{AbstractFormatter} class as a formatter, the writer must
|
||||
typically be provided by the application.
|
||||
|
||||
\setindexsubitem{(writer object method)}
|
||||
|
||||
|
@ -222,40 +223,40 @@ Flush any buffered output or device control events.
|
|||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_alignment}{align}
|
||||
Set the alignment style. The \code{align} value can be any object,
|
||||
Set the alignment style. The \var{align} value can be any object,
|
||||
but by convention is a string or \code{None}, where \code{None}
|
||||
indicates that the writer's ``preferred'' alignment should be used.
|
||||
Conventional \code{align} values are \code{'left'}, \code{'center'},
|
||||
Conventional \var{align} values are \code{'left'}, \code{'center'},
|
||||
\code{'right'}, and \code{'justify'}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_font}{font}
|
||||
Set the font style. The value of \code{font} will be \code{None},
|
||||
Set the font style. The value of \var{font} will be \code{None},
|
||||
indicating that the device's default font should be used, or a tuple
|
||||
of the form (\var{size}, \var{italic}, \var{bold}, \var{teletype}).
|
||||
Size will be a string indicating the size of font that should be used;
|
||||
specific strings and their interpretation must be defined by the
|
||||
application. The \var{italic}, \var{bold}, and \var{teletype} values
|
||||
are boolean indicators specifying which of those font attributes
|
||||
should be used.
|
||||
of the form \code{(}\var{size}, \var{italic}, \var{bold},
|
||||
\var{teletype}\code{)}. Size will be a string indicating the size of
|
||||
font that should be used; specific strings and their interpretation
|
||||
must be defined by the application. The \var{italic}, \var{bold}, and
|
||||
\var{teletype} values are boolean indicators specifying which of those
|
||||
font attributes should be used.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_margin}{margin, level}
|
||||
Set the margin level to the integer \code{level} and the logical tag
|
||||
to \code{margin}. Interpretation of the logical tag is at the
|
||||
Set the margin level to the integer \var{level} and the logical tag
|
||||
to \var{margin}. Interpretation of the logical tag is at the
|
||||
writer's discretion; the only restriction on the value of the logical
|
||||
tag is that it not be a false value for non-zero values of
|
||||
\code{level}.
|
||||
\var{level}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_spacing}{spacing}
|
||||
Set the spacing style to \code{spacing}.
|
||||
Set the spacing style to \var{spacing}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{new_styles}{styles}
|
||||
Set additional styles. The \code{styles} value is a tuple of
|
||||
arbitrary values; the value \code{AS_IS} should be ignored. The
|
||||
\code{styles} tuple may be interpreted either as a set or as a stack
|
||||
Set additional styles. The \var{styles} value is a tuple of
|
||||
arbitrary values; the value \constant{AS_IS} should be ignored. The
|
||||
\var{styles} tuple may be interpreted either as a set or as a stack
|
||||
depending on the requirements of the application and writer
|
||||
implementation.
|
||||
\end{funcdesc}
|
||||
|
@ -265,8 +266,8 @@ Break the current line.
|
|||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{send_paragraph}{blankline}
|
||||
Produce a paragraph separation of at least \code{blankline} blank
|
||||
lines, or the equivelent. The \code{blankline} value will be an
|
||||
Produce a paragraph separation of at least \var{blankline} blank
|
||||
lines, or the equivelent. The \var{blankline} value will be an
|
||||
integer.
|
||||
\end{funcdesc}
|
||||
|
||||
|
@ -274,7 +275,7 @@ integer.
|
|||
Display a horizontal rule on the output device. The arguments to this
|
||||
method are entirely application- and writer-specific, and should be
|
||||
interpreted with care. The method implementation may assume that a
|
||||
line break has already been issued via \code{send_line_break()}.
|
||||
line break has already been issued via \method{send_line_break()}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{send_flowing_data}{data}
|
||||
|
@ -290,12 +291,12 @@ for display. Generally, this should be interpreted to mean that line
|
|||
breaks indicated by newline characters should be preserved and no new
|
||||
line breaks should be introduced. The data may contain embedded
|
||||
newline and tab characters, unlike data provided to the
|
||||
\code{send_formatted_data()} interface.
|
||||
\method{send_formatted_data()} interface.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{send_label_data}{data}
|
||||
Set \code{data} to the left of the current left margin, if possible.
|
||||
The value of \code{data} is not restricted; treatment of non-string
|
||||
Set \var{data} to the left of the current left margin, if possible.
|
||||
The value of \var{data} is not restricted; treatment of non-string
|
||||
values is entirely application- and writer-dependent. This method
|
||||
will only be called at the beginning of a line.
|
||||
\end{funcdesc}
|
||||
|
@ -305,7 +306,7 @@ will only be called at the beginning of a line.
|
|||
|
||||
Three implementations of the writer object interface are provided as
|
||||
examples by this module. Most applications will need to derive new
|
||||
writer classes from the \code{NullWriter} class.
|
||||
writer classes from the \class{NullWriter} class.
|
||||
|
||||
\setindexsubitem{(in module formatter)}
|
||||
|
||||
|
@ -321,10 +322,10 @@ else. Each method simply announces itself by printing its name and
|
|||
arguments on standard output.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{DumbWriter}{\optional{file\code{ = None}\optional{\, maxcol\code{ = 72}}}}
|
||||
\begin{funcdesc}{DumbWriter}{\optional{file\optional{\, maxcol\code{ = 72}}}}
|
||||
Simple writer class which writes output on the file object passed in
|
||||
as \code{file} or, if \code{file} is omitted, on standard output. The
|
||||
as \var{file} or, if \var{file} is omitted, on standard output. The
|
||||
output is simply word-wrapped to the number of columns specified by
|
||||
\code{maxcol}. This class is suitable for reflowing a sequence of
|
||||
\var{maxcol}. This class is suitable for reflowing a sequence of
|
||||
paragraphs.
|
||||
\end{funcdesc}
|
||||
|
|
|
@ -4,11 +4,14 @@
|
|||
\stmodindex{xmllib}
|
||||
\index{XML}
|
||||
|
||||
This module defines a class \code{XMLParser} which serves as the basis
|
||||
This module defines a class \class{XMLParser} which serves as the basis
|
||||
for parsing text files formatted in XML (eXtended Markup Language).
|
||||
|
||||
The \code{XMLParser} class must be instantiated without arguments. It
|
||||
has the following interface methods:
|
||||
\begin{classdesc}{XMLParser}{}
|
||||
The \class{XMLParser} class must be instantiated without arguments.
|
||||
\end{classdesc}
|
||||
|
||||
This class provides the following interface methods:
|
||||
|
||||
\setindexsubitem{(XMLParser method)}
|
||||
|
||||
|
@ -29,40 +32,40 @@ Enter literal mode (CDATA mode).
|
|||
\begin{funcdesc}{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 \code{close()} is called.
|
||||
fed or \method{close()} is called.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{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 \code{XMLParser.close()}.
|
||||
redefined version should always call \method{close()}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{translate_references}{data}
|
||||
Translate all entity and character references in \code{data} and
|
||||
Translate all entity and character references in \var{data} and
|
||||
returns the translated string.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_xml}{encoding\, standalone}
|
||||
\begin{funcdesc}{handle_xml}{encoding, standalone}
|
||||
This method is called when the \code{<?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 \code{handle_xml} default to \code{None} and the string
|
||||
passed to \method{handle_xml()} default to \code{None} and the string
|
||||
\code{'no'} respectively.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_doctype}{tag\, data}
|
||||
\begin{funcdesc}{handle_doctype}{tag, data}
|
||||
This method is called when the \code{<!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{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_starttag}{tag\, method\, attributes}
|
||||
\begin{funcdesc}{handle_starttag}{tag, method, attributes}
|
||||
This method is called to handle start tags for which a
|
||||
\code{start_\var{tag}()} method has been defined. The \code{tag}
|
||||
argument is the name of the tag, and the \code{method} argument is the
|
||||
\code{start_\var{tag}()} method has been defined. The \var{tag}
|
||||
argument is the name of the tag, and the \method{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
|
||||
|
@ -71,19 +74,19 @@ 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 \code{method} with \code{attributes}
|
||||
The base implementation simply calls \var{method} with \var{attributes}
|
||||
as the only argument.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_endtag}{tag\, method}
|
||||
This method is called to handle endtags for which an
|
||||
\code{end_\var{tag}()} method has been defined. The \code{tag}
|
||||
\code{end_\var{tag}()} method has been defined. The \var{tag}
|
||||
argument is the name of the tag, and the
|
||||
\code{method} argument is the bound method which should be used to
|
||||
\var{method} argument is the bound method which should be used to
|
||||
support semantic interpretation of the end tag. If no
|
||||
\code{end_\var{tag}()} method is defined for the closing element, this
|
||||
handler is not called. The base implementation simply calls
|
||||
\code{method}.
|
||||
\var{method}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_data}{data}
|
||||
|
@ -98,7 +101,7 @@ This method is called to process a character reference of the form
|
|||
or a hexadecimal number when preceded by \code{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 \code{handle_data()} with the character as argument. If
|
||||
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
|
||||
|
@ -106,21 +109,21 @@ references outside of the \ASCII{} range.
|
|||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{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
|
||||
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 \code{entitydefs} which should be a mapping from entity names
|
||||
to corresponding translations.
|
||||
If a translation is found, it calls the method \code{handle_data()}
|
||||
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 \code{entitydefs}
|
||||
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
|
||||
defines translations for \code{\&}, \code{\&apos}, \code{\>},
|
||||
\code{\<}, and \code{\"}.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_comment}{comment}
|
||||
This method is called when a comment is encountered. The
|
||||
\code{comment} argument is a string containing the text between 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
|
||||
|
@ -129,27 +132,27 @@ default method does nothing.
|
|||
|
||||
\begin{funcdesc}{handle_cdata}{data}
|
||||
This method is called when a CDATA element is encountered. The
|
||||
\code{data} argument is a string containing the text between 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.
|
||||
default method does nothing, and is intended to be overridden.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_proc}{name\, data}
|
||||
This method is called when a processing instruction (PI) is encountered. The
|
||||
\code{name} is the PI target, and the \code{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 a \code{<?xml ...?>}
|
||||
tag, \code{handle_xml} is called to handle it.
|
||||
\begin{funcdesc}{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 \code{<?xml
|
||||
...?>}, \method{handle_xml()} is called to handle it.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{handle_special}{data}
|
||||
This method is called when a declaration is encountered. The
|
||||
\code{data} argument is a string containing the text between 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
|
||||
|
@ -159,11 +162,12 @@ handled separately if it is located at the start of the document.
|
|||
|
||||
\begin{funcdesc}{syntax_error}{message}
|
||||
This method is called when a syntax error is encountered. The
|
||||
\code{message} is a description of what was wrong. The default method
|
||||
raises a \code{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
|
||||
\code{RuntimeError} without first calling \code{syntax_error}.
|
||||
\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{funcdesc}
|
||||
|
||||
\begin{funcdesc}{unknown_starttag}{tag\, attributes}
|
||||
|
@ -199,8 +203,8 @@ correct case:
|
|||
\begin{funcdescni}{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
|
||||
\code{handle_starttag()} above. In fact, the base implementation of
|
||||
\code{handle_starttag()} calls this method.
|
||||
\method{handle_starttag()} above. In fact, the base implementation of
|
||||
\method{handle_starttag()} calls this method.
|
||||
\end{funcdescni}
|
||||
|
||||
\begin{funcdescni}{end_\var{tag}}{}
|
||||
|
@ -215,7 +219,7 @@ 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 \code{handle_starttag()} and
|
||||
\code{unknown_starttag()} contains values for all attributes that have a
|
||||
default value.
|
||||
attribute dictionary that is passed to \method{handle_starttag()} and
|
||||
\method{unknown_starttag()} contains values for all attributes that
|
||||
have a default value.
|
||||
\end{datadescni}
|
||||
|
|
Loading…
Reference in New Issue