dom/chrome-webidl/MatchPattern.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 interface Cookie;
   6 interface URI;
   7
   8 /**
   9  * A URL match pattern as used by the WebExtension and Chrome extension APIs.
  10  *
  11  * A match pattern is a string with one of the following formats:
  12  *
  13  *  - "<all_urls>"
  14  *    The literal string "<all_urls>" matches any URL with a supported
  15  *    protocol.
  16  *
  17  *  - <proto>://<host>/<path>
  18  *    A URL pattern with the following placeholders:
  19  *
  20  *    - <proto>
  21  *      The protocol to match, or "*" to match either "http" or "https".
  22  *    - <host>
  23  *      The hostname to match. May be either a complete, literal hostname to
  24  *      match a specific host, the wildcard character "*", to match any host,
  25  *      or a subdomain pattern, with "*." followed by a domain name, to match
  26  *      that domain name or any subdomain thereof.
  27  *    - <path>
  28  *      A glob pattern for paths to match. A "*" may appear anywhere within
  29  *      the path, and will match any string of characters. If no "*" appears,
  30  *      the URL path must exactly match the pattern path.
  31  */
  32 [ChromeOnly, Exposed=Window]
  33 interface MatchPattern {
  34   [Throws]
  35   constructor(DOMString pattern, optional MatchPatternOptions options = {});
  36
  37   /**
  38    * Returns true if the given URI matches the pattern.
  39    *
  40    * If explicit is true, only explicit domain matches, without wildcards, are
  41    * considered.
  42    */
  43   [Throws]
  44   boolean matches(URI uri, optional boolean explicit = false);
  45
  46   [Throws]
  47   boolean matches(DOMString url, optional boolean explicit = false);
  48
  49   /**
  50    * Returns true if a URL exists which a) would be able to access the given
  51    * cookie, and b) would be matched by this match pattern.
  52    */
  53   boolean matchesCookie(Cookie cookie);
  54
  55   /**
  56    * Returns true if this pattern will match any host which would be matched
  57    * by the given pattern.
  58    */
  59   boolean subsumes(MatchPattern pattern);
  60
  61   /**
  62    * Returns true if this pattern will match any host which would be matched
  63    * by the given pattern, ignoring the scheme.
  64    */
  65   boolean subsumesDomain(MatchPattern pattern);
  66
  67   /**
  68    * Returns true if there is any host which would be matched by both this
  69    * pattern and the given pattern.
  70    */
  71   boolean overlaps(MatchPattern pattern);
  72
  73   /**
  74    * The match pattern string represented by this pattern.
  75    */
  76   [Constant]
  77   readonly attribute DOMString pattern;
  78
  79   /**
  80    * Whether the match pattern matches all http(s) URLs.
  81    */
  82   [Constant]
  83   readonly attribute boolean matchesAllWebUrls;
  84 };
  85
  86 /**
  87  * A set of MatchPattern objects, which implements the MatchPattern API and
  88  * matches when any of its sub-patterns matches.
  89  */
  90 [ChromeOnly, Exposed=Window]
  91 interface MatchPatternSet {
  92   [Throws]
  93   constructor(sequence<(DOMString or MatchPattern)> patterns, optional MatchPatternOptions options = {});
  94
  95   /**
  96    * Returns true if the given URI matches any sub-pattern.
  97    *
  98    * If explicit is true, only explicit domain matches, without wildcards, are
  99    * considered.
 100    */
 101   [Throws]
 102   boolean matches(URI uri, optional boolean explicit = false);
 103
 104   [Throws]
 105   boolean matches(DOMString url, optional boolean explicit = false);
 106
 107   /**
 108    * Returns true if any sub-pattern matches the given cookie.
 109    */
 110   boolean matchesCookie(Cookie cookie);
 111
 112   /**
 113    * Returns true if any sub-pattern subsumes the given pattern.
 114    */
 115   boolean subsumes(MatchPattern pattern);
 116
 117   /**
 118    * Returns true if any sub-pattern subsumes the given pattern,
 119    * ignoring any of the schemes in the patterns.
 120    */
 121   boolean subsumesDomain(MatchPattern pattern);
 122
 123   /**
 124    * Returns true if any sub-pattern overlaps the given pattern.
 125    */
 126   boolean overlaps(MatchPattern pattern);
 127
 128   /**
 129    * Returns true if any sub-pattern overlaps any sub-pattern the given
 130    * pattern set.
 131    */
 132   boolean overlaps(MatchPatternSet patternSet);
 133
 134   /**
 135    * Returns true if any sub-pattern overlaps *every* sub-pattern in the given
 136    * pattern set.
 137    */
 138   boolean overlapsAll(MatchPatternSet patternSet);
 139
 140   [Cached, Constant, Frozen]
 141   readonly attribute sequence<MatchPattern> patterns;
 142
 143   /**
 144    * Whether all http(s) URLs are matched by any of the sub-patterns.
 145    */
 146   [Constant]
 147   readonly attribute boolean matchesAllWebUrls;
 148 };
 149
 150 dictionary MatchPatternOptions {
 151   /**
 152    * If true, the path portion of the pattern is ignored, and replaced with a
 153    * wildcard. The `pattern` property is updated to reflect this.
 154    */
 155   boolean ignorePath = false;
 156
 157   /**
 158    * If true, the set of schemes this pattern can match is restricted to
 159    * those accessible by WebExtensions.
 160    */
 161   boolean restrictSchemes = true;
 162 };