1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/parser/xml/public/nsISAXLexicalHandler.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,118 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +/**
1.12 + * SAX2 extension handler for lexical events.
1.13 + *
1.14 + * This is an extension handler for SAX2 to provide lexical
1.15 + * information about an XML document, such as comments and CDATA
1.16 + * section boundaries.
1.17 + *
1.18 + * The events in the lexical handler apply to the entire document,
1.19 + * not just to the document element, and all lexical handler events
1.20 + * must appear between the content handler's startDocument and
1.21 + * endDocument events.
1.22 + */
1.23 +[scriptable, uuid(23c26a56-adff-440c-8caf-95c2dc2e399b)]
1.24 +interface nsISAXLexicalHandler : nsISupports {
1.25 +
1.26 + /**
1.27 + * Report an XML comment anywhere in the document.
1.28 + *
1.29 + * This callback will be used for comments inside or outside the
1.30 + * document element, including comments in the external DTD subset
1.31 + * (if read). Comments in the DTD must be properly nested inside
1.32 + * start/endDTD and start/endEntity events (if used).
1.33 + *
1.34 + * @param chars The characters in the comment.
1.35 + */
1.36 + void comment(in AString chars);
1.37 +
1.38 + /**
1.39 + * Report the start of DTD declarations, if any.
1.40 + *
1.41 + * This method is intended to report the beginning of the
1.42 + * DOCTYPE declaration; if the document has no DOCTYPE declaration,
1.43 + * this method will not be invoked.
1.44 + *
1.45 + * All declarations reported through DTDHandler or DeclHandler
1.46 + * events must appear between the startDTD and endDTD events.
1.47 + * Declarations are assumed to belong to the internal DTD subset
1.48 + * unless they appear between startEntity and endEntity events.
1.49 + * Comments and processing instructions from the DTD should also be
1.50 + * reported between the startDTD and endDTD events, in their
1.51 + * original order of (logical) occurrence; they are not required to
1.52 + * appear in their correct locations relative to DTDHandler or
1.53 + * DeclHandler events, however.
1.54 + *
1.55 + * Note that the start/endDTD events will appear within the
1.56 + * start/endDocument events from ContentHandler and before the first
1.57 + * startElement event.
1.58 + *
1.59 + * @param name The document type name.
1.60 + * @param publicId The declared public identifier for the
1.61 + * external DTD subset, or null if none was declared.
1.62 + * @param systemId The declared system identifier for the
1.63 + * external DTD subset, or null if none was declared.
1.64 + * (Note that this is not resolved against the document
1.65 + * base URI.)
1.66 + */
1.67 + void startDTD(in AString name, in AString publicId, in AString systemId);
1.68 +
1.69 + /**
1.70 + * Report the end of DTD declarations.
1.71 + *
1.72 + * This method is intended to report the end of the
1.73 + * DOCTYPE declaration; if the document has no DOCTYPE declaration,
1.74 + * this method will not be invoked.
1.75 + */
1.76 + void endDTD();
1.77 +
1.78 + /**
1.79 + * Report the start of a CDATA section.
1.80 + *
1.81 + * The contents of the CDATA section will be reported through the
1.82 + * regular characters event; this event is intended only to report
1.83 + * the boundary.
1.84 + */
1.85 + void startCDATA();
1.86 +
1.87 + /**
1.88 + * Report the end of a CDATA section.
1.89 + */
1.90 + void endCDATA();
1.91 +
1.92 + /**
1.93 + * Report the beginning of some internal and external XML entities.
1.94 + *
1.95 + * Because of the streaming event model that SAX uses, some
1.96 + * entity boundaries cannot be reported under any circumstances:
1.97 + *
1.98 + * 1.) general entities within attribute values
1.99 + * 2.) parameter entities within declarations
1.100 + *
1.101 + * These will be silently expanded, with no indication of where
1.102 + * the original entity boundaries were.
1.103 + *
1.104 + * Note also that the boundaries of character references (which
1.105 + * are not really entities anyway) are not reported.
1.106 + *
1.107 + * All start/endEntity events must be properly nested.
1.108 + *
1.109 + * @param name The name of the entity. If it is a parameter
1.110 + * entity, the name will begin with '%', and if it is the
1.111 + * external DTD subset, it will be "[dtd]".
1.112 + */
1.113 + void startEntity(in AString name);
1.114 +
1.115 + /**
1.116 + * Report the end of an entity.
1.117 + *
1.118 + * @param name The name of the entity that is ending.
1.119 + */
1.120 + void endEntity(in AString name);
1.121 +};
