tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

MatchPattern.webidl (4730B)

      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 };