summaryrefslogtreecommitdiffstats
path: root/dom/chrome-webidl/MatchPattern.webidl
blob: b17a15f3ea82ffc0b34354d5fd2b7ff28142a61e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

interface Cookie;
interface URI;

/**
 * A URL match pattern as used by the WebExtension and Chrome extension APIs.
 *
 * A match pattern is a string with one of the following formats:
 *
 *  - "<all_urls>"
 *    The literal string "<all_urls>" matches any URL with a supported
 *    protocol.
 *
 *  - <proto>://<host>/<path>
 *    A URL pattern with the following placeholders:
 *
 *    - <proto>
 *      The protocol to match, or "*" to match either "http" or "https".
 *    - <host>
 *      The hostname to match. May be either a complete, literal hostname to
 *      match a specific host, the wildcard character "*", to match any host,
 *      or a subdomain pattern, with "*." followed by a domain name, to match
 *      that domain name or any subdomain thereof.
 *    - <path>
 *      A glob pattern for paths to match. A "*" may appear anywhere within
 *      the path, and will match any string of characters. If no "*" appears,
 *      the URL path must exactly match the pattern path.
 */
[ChromeOnly, Exposed=Window]
interface MatchPattern {
  [Throws]
  constructor(DOMString pattern, optional MatchPatternOptions options = {});

  /**
   * Returns true if the given URI matches the pattern.
   *
   * If explicit is true, only explicit domain matches, without wildcards, are
   * considered.
   */
  [Throws]
  boolean matches(URI uri, optional boolean explicit = false);

  [Throws]
  boolean matches(DOMString url, optional boolean explicit = false);

  /**
   * Returns true if a URL exists which a) would be able to access the given
   * cookie, and b) would be matched by this match pattern.
   */
  boolean matchesCookie(Cookie cookie);

  /**
   * Returns true if this pattern will match any host which would be matched
   * by the given pattern.
   */
  boolean subsumes(MatchPattern pattern);

  /**
   * Returns true if this pattern will match any host which would be matched
   * by the given pattern, ignoring the scheme.
   */
  boolean subsumesDomain(MatchPattern pattern);

  /**
   * Returns true if there is any host which would be matched by both this
   * pattern and the given pattern.
   */
  boolean overlaps(MatchPattern pattern);

  /**
   * The match pattern string represented by this pattern.
   */
  [Constant]
  readonly attribute DOMString pattern;

  /**
   * Whether the match pattern matches all http(s) URLs.
   */
  [Constant]
  readonly attribute boolean matchesAllWebUrls;
};

/**
 * A set of MatchPattern objects, which implements the MatchPattern API and
 * matches when any of its sub-patterns matches.
 */
[ChromeOnly, Exposed=Window]
interface MatchPatternSet {
  [Throws]
  constructor(sequence<(DOMString or MatchPattern)> patterns, optional MatchPatternOptions options = {});

  /**
   * Returns true if the given URI matches any sub-pattern.
   *
   * If explicit is true, only explicit domain matches, without wildcards, are
   * considered.
   */
  [Throws]
  boolean matches(URI uri, optional boolean explicit = false);

  [Throws]
  boolean matches(DOMString url, optional boolean explicit = false);

  /**
   * Returns true if any sub-pattern matches the given cookie.
   */
  boolean matchesCookie(Cookie cookie);

  /**
   * Returns true if any sub-pattern subsumes the given pattern.
   */
  boolean subsumes(MatchPattern pattern);

  /**
   * Returns true if any sub-pattern subsumes the given pattern,
   * ignoring any of the schemes in the patterns.
   */
  boolean subsumesDomain(MatchPattern pattern);

  /**
   * Returns true if any sub-pattern overlaps the given pattern.
   */
  boolean overlaps(MatchPattern pattern);

  /**
   * Returns true if any sub-pattern overlaps any sub-pattern the given
   * pattern set.
   */
  boolean overlaps(MatchPatternSet patternSet);

  /**
   * Returns true if any sub-pattern overlaps *every* sub-pattern in the given
   * pattern set.
   */
  boolean overlapsAll(MatchPatternSet patternSet);

  [Cached, Constant, Frozen]
  readonly attribute sequence<MatchPattern> patterns;

  /**
   * Whether all http(s) URLs are matched by any of the sub-patterns.
   */
  [Constant]
  readonly attribute boolean matchesAllWebUrls;
};

dictionary MatchPatternOptions {
  /**
   * If true, the path portion of the pattern is ignored, and replaced with a
   * wildcard. The `pattern` property is updated to reflect this.
   */
  boolean ignorePath = false;

  /**
   * If true, the set of schemes this pattern can match is restricted to
   * those accessible by WebExtensions.
   */
  boolean restrictSchemes = true;
};