parser/htmlparser/nsIParser.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=2 sw=2 et tw=78: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6 #ifndef NS_IPARSER___
   7 #define NS_IPARSER___
   8
   9 /**
  10  * This GECKO-INTERNAL interface is on track to being REMOVED (or refactored
  11  * to the point of being near-unrecognizable).
  12  *
  13  * Please DO NOT #include this file in comm-central code, in your XULRunner
  14  * app or binary extensions.
  15  *
  16  * Please DO NOT #include this into new files even inside Gecko. It is more
  17  * likely than not that #including this header is the wrong thing to do.
  18  */
  19
  20 #include "nsISupports.h"
  21 #include "nsIStreamListener.h"
  22 #include "nsIDTD.h"
  23 #include "nsString.h"
  24 #include "nsTArray.h"
  25 #include "nsAtom.h"
  26 #include "nsParserBase.h"
  27 #include "mozilla/NotNull.h"
  28
  29 #define NS_IPARSER_IID                               \
  30   {                                                  \
  31     0x2c4ad90a, 0x740e, 0x4212, {                    \
  32       0xba, 0x3f, 0xfe, 0xac, 0xda, 0x4b, 0x92, 0x9e \
  33     }                                                \
  34   }
  35
  36 class nsIContentSink;
  37 class nsIRequestObserver;
  38 class nsIURI;
  39 class nsIChannel;
  40 namespace mozilla {
  41 class Encoding;
  42 }
  43
  44 enum eParserCommands { eViewNormal, eViewSource, eViewFragment, eViewErrors };
  45
  46 enum eParserDocType { ePlainText = 0, eXML, eHTML_Quirks, eHTML_Strict };
  47
  48 enum eStreamState { eNone, eOnStart, eOnDataAvail, eOnStop };
  49
  50 /**
  51  * This GECKO-INTERNAL interface is on track to being REMOVED (or refactored
  52  * to the point of being near-unrecognizable).
  53  *
  54  * Please DO NOT #include this file in comm-central code, in your XULRunner
  55  * app or binary extensions.
  56  *
  57  * Please DO NOT #include this into new files even inside Gecko. It is more
  58  * likely than not that #including this header is the wrong thing to do.
  59  */
  60 class nsIParser : public nsParserBase {
  61  protected:
  62   using Encoding = mozilla::Encoding;
  63   template <typename T>
  64   using NotNull = mozilla::NotNull<T>;
  65
  66  public:
  67   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IPARSER_IID)
  68
  69   /**
  70    * Select given content sink into parser for parser output
  71    * @update    gess5/11/98
  72    * @param   aSink is the new sink to be used by parser
  73    * @return
  74    */
  75   NS_IMETHOD_(void) SetContentSink(nsIContentSink* aSink) = 0;
  76
  77   /**
  78    * retrieve the sink set into the parser
  79    * @update    gess5/11/98
  80    * @return  current sink
  81    */
  82   NS_IMETHOD_(nsIContentSink*) GetContentSink(void) = 0;
  83
  84   /**
  85    *  Call this method once you've created a parser, and want to instruct it
  86    *  about the command which caused the parser to be constructed. For example,
  87    *  this allows us to select a DTD which can do, say, view-source.
  88    *
  89    *  @update  gess 3/25/98
  90    *  @param   aCommand -- ptrs to string that contains command
  91    *  @return    nada
  92    */
  93   NS_IMETHOD_(void) GetCommand(nsCString& aCommand) = 0;
  94   NS_IMETHOD_(void) SetCommand(const char* aCommand) = 0;
  95   NS_IMETHOD_(void) SetCommand(eParserCommands aParserCommand) = 0;
  96
  97   /**
  98    *  Call this method once you've created a parser, and want to instruct it
  99    *  about what charset to load
 100    *
 101    *  @update  ftang 4/23/99
 102    *  @param   aCharset- the charest of a document
 103    *  @param   aCharsetSource- the soure of the chares
 104    *  @param   aChannelHadCharset- whether the channel had charset
 105    *  @return    nada
 106    */
 107   virtual void SetDocumentCharset(NotNull<const Encoding*> aCharset,
 108                                   int32_t aSource,
 109                                   bool aChannelHadCharset = false) = 0;
 110
 111   /**
 112    * Get the channel associated with this parser
 113    * @update harishd,gagan 07/17/01
 114    * @param aChannel out param that will contain the result
 115    * @return NS_OK if successful
 116    */
 117   NS_IMETHOD GetChannel(nsIChannel** aChannel) override = 0;
 118
 119   /**
 120    * Get the DTD associated with this parser
 121    * @update vidur 9/29/99
 122    * @param aDTD out param that will contain the result
 123    * @return NS_OK if successful, NS_ERROR_FAILURE for runtime error
 124    */
 125   NS_IMETHOD GetDTD(nsIDTD** aDTD) = 0;
 126
 127   /**
 128    * Get the nsIStreamListener for this parser
 129    */
 130   virtual nsIStreamListener* GetStreamListener() = 0;
 131
 132   /**************************************************************************
 133    *  Parse methods always begin with an input source, and perform
 134    *  conversions until you wind up being emitted to the given contentsink
 135    *  (which may or may not be a proxy for the NGLayout content model).
 136    ************************************************************************/
 137
 138   // Call this method to resume the parser from an unblocked state.
 139   // This can happen, for example, if parsing was interrupted and then the
 140   // consumer needed to restart the parser without waiting for more data.
 141   // This also happens after loading scripts, which unblock the parser in
 142   // order to process the output of document.write() and then need to
 143   // continue on with the page load on an enabled parser.
 144   NS_IMETHOD ContinueInterruptedParsing() = 0;
 145
 146   // Stops parsing temporarily.
 147   NS_IMETHOD_(void) BlockParser() = 0;
 148
 149   // Open up the parser for tokenization, building up content
 150   // model..etc. However, this method does not resume parsing
 151   // automatically. It's the callers' responsibility to restart
 152   // the parsing engine.
 153   NS_IMETHOD_(void) UnblockParser() = 0;
 154
 155   /**
 156    * Asynchronously continues parsing.
 157    */
 158   NS_IMETHOD_(void) ContinueInterruptedParsingAsync() = 0;
 159
 160   NS_IMETHOD_(bool) IsParserEnabled() override = 0;
 161   NS_IMETHOD_(bool) IsComplete() = 0;
 162
 163   NS_IMETHOD Parse(nsIURI* aURL, nsIRequestObserver* aListener = nullptr,
 164                    void* aKey = 0, nsDTDMode aMode = eDTDMode_autodetect) = 0;
 165
 166   NS_IMETHOD Terminate(void) = 0;
 167
 168   /**
 169    * This method gets called when you want to parse a fragment of HTML or XML
 170    * surrounded by the context |aTagStack|. It requires that the parser have
 171    * been given a fragment content sink.
 172    *
 173    * @param aSourceBuffer The XML or HTML that hasn't been parsed yet.
 174    * @param aTagStack The context of the source buffer.
 175    * @return Success or failure.
 176    */
 177   NS_IMETHOD ParseFragment(const nsAString& aSourceBuffer,
 178                            nsTArray<nsString>& aTagStack) = 0;
 179
 180   /**
 181    * This method gets called when the tokens have been consumed, and it's time
 182    * to build the model via the content sink.
 183    * @update    gess5/11/98
 184    * @return  error code -- 0 if model building went well .
 185    */
 186   NS_IMETHOD BuildModel(void) = 0;
 187
 188   /**
 189    *  Call this method to cancel any pending parsing events.
 190    *  Parsing events may be pending if all of the document's content
 191    *  has been passed to the parser but the parser has been interrupted
 192    *  because processing the tokens took too long.
 193    *
 194    *  @update  kmcclusk 05/18/01
 195    *  @return  NS_OK if succeeded else ERROR.
 196    */
 197
 198   NS_IMETHOD CancelParsingEvents() = 0;
 199
 200   virtual void Reset() = 0;
 201
 202   /**
 203    * True if the insertion point (per HTML5) is defined.
 204    */
 205   virtual bool IsInsertionPointDefined() = 0;
 206
 207   /**
 208    * Call immediately before starting to evaluate a parser-inserted script or
 209    * in general when the spec says to increment the script nesting level.
 210    */
 211   virtual void IncrementScriptNestingLevel() = 0;
 212
 213   /**
 214    * Call immediately after having evaluated a parser-inserted script or
 215    * generally want to restore to the state before the last
 216    * IncrementScriptNestingLevel call.
 217    */
 218   virtual void DecrementScriptNestingLevel() = 0;
 219
 220   /**
 221    * True if this is an HTML5 parser whose script nesting level (in
 222    * the sense of
 223    * <https://html.spec.whatwg.org/multipage/parsing.html#script-nesting-level>)
 224    * is nonzero.
 225    */
 226   virtual bool HasNonzeroScriptNestingLevel() const = 0;
 227
 228   /**
 229    * Marks the HTML5 parser as not a script-created parser.
 230    */
 231   virtual void MarkAsNotScriptCreated(const char* aCommand) = 0;
 232
 233   /**
 234    * True if this is a script-created HTML5 parser.
 235    */
 236   virtual bool IsScriptCreated() = 0;
 237 };
 238
 239 NS_DEFINE_STATIC_IID_ACCESSOR(nsIParser, NS_IPARSER_IID)
 240
 241 /* ===========================================================*
 242   Some useful constants...
 243  * ===========================================================*/
 244
 245 #define NS_IPARSER_FLAG_XML 0x00000200
 246 #define NS_IPARSER_FLAG_HTML 0x00000400
 247
 248 #endif