parser/xml/public/nsISAXLexicalHandler.idl@925c144e1f1f
parser/xml/public/nsISAXLexicalHandler.idl
Fri, 16 Jan 2015 18:13:44 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 18:13:44 +0100
- branch
- TOR_BUG_9701
- changeset 14
- 925c144e1f1f
- permissions
- -rw-r--r--
Integrate suggestion from review to improve consistency with existing code.
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 /**
9 * SAX2 extension handler for lexical events.
10 *
11 * This is an extension handler for SAX2 to provide lexical
12 * information about an XML document, such as comments and CDATA
13 * section boundaries.
14 *
15 * The events in the lexical handler apply to the entire document,
16 * not just to the document element, and all lexical handler events
17 * must appear between the content handler's startDocument and
18 * endDocument events.
19 */
20 [scriptable, uuid(23c26a56-adff-440c-8caf-95c2dc2e399b)]
21 interface nsISAXLexicalHandler : nsISupports {
23 /**
24 * Report an XML comment anywhere in the document.
25 *
26 * This callback will be used for comments inside or outside the
27 * document element, including comments in the external DTD subset
28 * (if read). Comments in the DTD must be properly nested inside
29 * start/endDTD and start/endEntity events (if used).
30 *
31 * @param chars The characters in the comment.
32 */
33 void comment(in AString chars);
35 /**
36 * Report the start of DTD declarations, if any.
37 *
38 * This method is intended to report the beginning of the
39 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
40 * this method will not be invoked.
41 *
42 * All declarations reported through DTDHandler or DeclHandler
43 * events must appear between the startDTD and endDTD events.
44 * Declarations are assumed to belong to the internal DTD subset
45 * unless they appear between startEntity and endEntity events.
46 * Comments and processing instructions from the DTD should also be
47 * reported between the startDTD and endDTD events, in their
48 * original order of (logical) occurrence; they are not required to
49 * appear in their correct locations relative to DTDHandler or
50 * DeclHandler events, however.
51 *
52 * Note that the start/endDTD events will appear within the
53 * start/endDocument events from ContentHandler and before the first
54 * startElement event.
55 *
56 * @param name The document type name.
57 * @param publicId The declared public identifier for the
58 * external DTD subset, or null if none was declared.
59 * @param systemId The declared system identifier for the
60 * external DTD subset, or null if none was declared.
61 * (Note that this is not resolved against the document
62 * base URI.)
63 */
64 void startDTD(in AString name, in AString publicId, in AString systemId);
66 /**
67 * Report the end of DTD declarations.
68 *
69 * This method is intended to report the end of the
70 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
71 * this method will not be invoked.
72 */
73 void endDTD();
75 /**
76 * Report the start of a CDATA section.
77 *
78 * The contents of the CDATA section will be reported through the
79 * regular characters event; this event is intended only to report
80 * the boundary.
81 */
82 void startCDATA();
84 /**
85 * Report the end of a CDATA section.
86 */
87 void endCDATA();
89 /**
90 * Report the beginning of some internal and external XML entities.
91 *
92 * Because of the streaming event model that SAX uses, some
93 * entity boundaries cannot be reported under any circumstances:
94 *
95 * 1.) general entities within attribute values
96 * 2.) parameter entities within declarations
97 *
98 * These will be silently expanded, with no indication of where
99 * the original entity boundaries were.
100 *
101 * Note also that the boundaries of character references (which
102 * are not really entities anyway) are not reported.
103 *
104 * All start/endEntity events must be properly nested.
105 *
106 * @param name The name of the entity. If it is a parameter
107 * entity, the name will begin with '%', and if it is the
108 * external DTD subset, it will be "[dtd]".
109 */
110 void startEntity(in AString name);
112 /**
113 * Report the end of an entity.
114 *
115 * @param name The name of the entity that is ending.
116 */
117 void endEntity(in AString name);
118 };
