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    *  @return    nada
 105    */
 106   virtual void SetDocumentCharset(NotNull<const Encoding*> aCharset,
 107                                   int32_t aSource) = 0;
 108
 109   /**
 110    * Get the channel associated with this parser
 111    * @update harishd,gagan 07/17/01
 112    * @param aChannel out param that will contain the result
 113    * @return NS_OK if successful
 114    */
 115   NS_IMETHOD GetChannel(nsIChannel** aChannel) override = 0;
 116
 117   /**
 118    * Get the DTD associated with this parser
 119    * @update vidur 9/29/99
 120    * @param aDTD out param that will contain the result
 121    * @return NS_OK if successful, NS_ERROR_FAILURE for runtime error
 122    */
 123   NS_IMETHOD GetDTD(nsIDTD** aDTD) = 0;
 124
 125   /**
 126    * Get the nsIStreamListener for this parser
 127    */
 128   virtual nsIStreamListener* GetStreamListener() = 0;
 129
 130   /**************************************************************************
 131    *  Parse methods always begin with an input source, and perform
 132    *  conversions until you wind up being emitted to the given contentsink
 133    *  (which may or may not be a proxy for the NGLayout content model).
 134    ************************************************************************/
 135
 136   // Call this method to resume the parser from an unblocked state.
 137   // This can happen, for example, if parsing was interrupted and then the
 138   // consumer needed to restart the parser without waiting for more data.
 139   // This also happens after loading scripts, which unblock the parser in
 140   // order to process the output of document.write() and then need to
 141   // continue on with the page load on an enabled parser.
 142   NS_IMETHOD ContinueInterruptedParsing() = 0;
 143
 144   // Stops parsing temporarily.
 145   NS_IMETHOD_(void) BlockParser() = 0;
 146
 147   // Open up the parser for tokenization, building up content
 148   // model..etc. However, this method does not resume parsing
 149   // automatically. It's the callers' responsibility to restart
 150   // the parsing engine.
 151   NS_IMETHOD_(void) UnblockParser() = 0;
 152
 153   /**
 154    * Asynchronously continues parsing.
 155    */
 156   NS_IMETHOD_(void) ContinueInterruptedParsingAsync() = 0;
 157
 158   NS_IMETHOD_(bool) IsParserEnabled() override = 0;
 159   NS_IMETHOD_(bool) IsComplete() = 0;
 160
 161   NS_IMETHOD Parse(nsIURI* aURL, nsIRequestObserver* aListener = nullptr,
 162                    void* aKey = 0, nsDTDMode aMode = eDTDMode_autodetect) = 0;
 163
 164   NS_IMETHOD Terminate(void) = 0;
 165
 166   /**
 167    * This method gets called when you want to parse a fragment of HTML or XML
 168    * surrounded by the context |aTagStack|. It requires that the parser have
 169    * been given a fragment content sink.
 170    *
 171    * @param aSourceBuffer The XML or HTML that hasn't been parsed yet.
 172    * @param aTagStack The context of the source buffer.
 173    * @return Success or failure.
 174    */
 175   NS_IMETHOD ParseFragment(const nsAString& aSourceBuffer,
 176                            nsTArray<nsString>& aTagStack) = 0;
 177
 178   /**
 179    * This method gets called when the tokens have been consumed, and it's time
 180    * to build the model via the content sink.
 181    * @update    gess5/11/98
 182    * @return  error code -- 0 if model building went well .
 183    */
 184   NS_IMETHOD BuildModel(void) = 0;
 185
 186   /**
 187    *  Call this method to cancel any pending parsing events.
 188    *  Parsing events may be pending if all of the document's content
 189    *  has been passed to the parser but the parser has been interrupted
 190    *  because processing the tokens took too long.
 191    *
 192    *  @update  kmcclusk 05/18/01
 193    *  @return  NS_OK if succeeded else ERROR.
 194    */
 195
 196   NS_IMETHOD CancelParsingEvents() = 0;
 197
 198   virtual void Reset() = 0;
 199
 200   /**
 201    * True if the insertion point (per HTML5) is defined.
 202    */
 203   virtual bool IsInsertionPointDefined() = 0;
 204
 205   /**
 206    * Call immediately before starting to evaluate a parser-inserted script or
 207    * in general when the spec says to increment the script nesting level.
 208    */
 209   virtual void IncrementScriptNestingLevel() = 0;
 210
 211   /**
 212    * Call immediately after having evaluated a parser-inserted script or
 213    * generally want to restore to the state before the last
 214    * IncrementScriptNestingLevel call.
 215    */
 216   virtual void DecrementScriptNestingLevel() = 0;
 217
 218   /**
 219    * True if this is an HTML5 parser whose script nesting level (in
 220    * the sense of
 221    * <https://html.spec.whatwg.org/multipage/parsing.html#script-nesting-level>)
 222    * is nonzero.
 223    */
 224   virtual bool HasNonzeroScriptNestingLevel() const = 0;
 225
 226   /**
 227    * Marks the HTML5 parser as not a script-created parser.
 228    */
 229   virtual void MarkAsNotScriptCreated(const char* aCommand) = 0;
 230
 231   /**
 232    * True if this is a script-created HTML5 parser.
 233    */
 234   virtual bool IsScriptCreated() = 0;
 235 };
 236
 237 NS_DEFINE_STATIC_IID_ACCESSOR(nsIParser, NS_IPARSER_IID)
 238
 239 /* ===========================================================*
 240   Some useful constants...
 241  * ===========================================================*/
 242
 243 #define NS_IPARSER_FLAG_XML 0x00000200
 244 #define NS_IPARSER_FLAG_HTML 0x00000400
 245
 246 #endif