dom/base/FragmentDirective.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   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
   7 #ifndef DOM_FRAGMENTDIRECTIVE_H_
   8 #define DOM_FRAGMENTDIRECTIVE_H_
   9
  10 #include "js/TypeDecls.h"
  11 #include "mozilla/dom/BindingDeclarations.h"
  12
  13 #include "mozilla/dom/fragmentdirectives_ffi_generated.h"
  14 #include "nsCycleCollectionParticipant.h"
  15 #include "nsStringFwd.h"
  16 #include "nsWrapperCache.h"
  17
  18 class nsINode;
  19 class nsIURI;
  20 class nsRange;
  21 namespace mozilla::dom {
  22 class Document;
  23 class Text;
  24
  25 /**
  26  * @brief The `FragmentDirective` class is the C++ representation of the
  27  * `Document.fragmentDirective` webidl property.
  28  *
  29  * This class also serves as the main interface to interact with the fragment
  30  * directive from the C++ side. It allows to find text fragment ranges from a
  31  * given list of `TextDirective`s using
  32  * `FragmentDirective::FindTextFragmentsInDocument()`.
  33  * To avoid Text Directives being applied multiple times, this class implements
  34  * the `uninvoked directive` mechanism, which in the spec is defined to be part
  35  * of the `Document` [0].
  36  *
  37  * [0]
  38  * https://wicg.github.io/scroll-to-text-fragment/#document-uninvoked-directives
  39  */
  40 class FragmentDirective final : public nsISupports, public nsWrapperCache {
  41  public:
  42   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  43   NS_DECL_CYCLE_COLLECTION_WRAPPERCACHE_CLASS(FragmentDirective)
  44
  45  public:
  46   explicit FragmentDirective(Document* aDocument);
  47   FragmentDirective(Document* aDocument,
  48                     nsTArray<TextDirective>&& aTextDirectives)
  49       : mDocument(aDocument),
  50         mUninvokedTextDirectives(std::move(aTextDirectives)) {}
  51
  52  protected:
  53   ~FragmentDirective() = default;
  54
  55  public:
  56   Document* GetParentObject() const { return mDocument; };
  57
  58   JSObject* WrapObject(JSContext* aCx,
  59                        JS::Handle<JSObject*> aGivenProto) override;
  60
  61   /**
  62    * @brief Sets Text Directives as "uninvoked directive".
  63    */
  64   void SetTextDirectives(nsTArray<TextDirective>&& aTextDirectives) {
  65     mUninvokedTextDirectives = std::move(aTextDirectives);
  66   }
  67
  68   /** Returns true if there are Text Directives that have not been applied to
  69    * the `Document`.
  70    */
  71   bool HasUninvokedDirectives() const {
  72     return !mUninvokedTextDirectives.IsEmpty();
  73   };
  74
  75   /** Searches for the current uninvoked text directives and creates a range for
  76    * each one that is found.
  77    *
  78    * When this method returns, the uninvoked directives for this document are
  79    * cleared.
  80    *
  81    * This method tries to follow the specification as close as possible in how
  82    * to find a matching range for a text directive. However, instead of using
  83    * collator-based search, a standard case-insensitive search is used
  84    * (`nsString::find()`).
  85    */
  86   nsTArray<RefPtr<nsRange>> FindTextFragmentsInDocument();
  87
  88   /** Utility function which parses the fragment directive and removes it from
  89    * the hash of the given URI. This operation happens in-place.
  90    *
  91    * If aTextDirectives is nullptr, the parsed fragment directive is discarded.
  92    */
  93   static void ParseAndRemoveFragmentDirectiveFromFragment(
  94       nsCOMPtr<nsIURI>& aURI,
  95       nsTArray<TextDirective>* aTextDirectives = nullptr);
  96
  97  private:
  98   RefPtr<nsRange> FindRangeForTextDirective(
  99       const TextDirective& aTextDirective);
 100   RefPtr<nsRange> FindStringInRange(nsRange* aSearchRange,
 101                                     const nsAString& aQuery,
 102                                     bool aWordStartBounded,
 103                                     bool aWordEndBounded);
 104
 105   RefPtr<Document> mDocument;
 106   nsTArray<TextDirective> mUninvokedTextDirectives;
 107 };
 108
 109 }  // namespace mozilla::dom
 110
 111 #endif  // DOM_FRAGMENTDIRECTIVE_H_