From 37ef13b094c5f9509de324ab245c16c84d96a536 Mon Sep 17 00:00:00 2001 From: Jeremy Roman Date: Tue, 12 Sep 2023 12:33:14 -0400 Subject: [PATCH 1/4] Expand introductory text and examples Some simple introductory examples are added, along with some brief overview text of both URL patterns and (component-specific) pattern strings. Some more detailed examples already exist within the relevant parsing code. This contributes to resolving #127. --- spec.bs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/spec.bs b/spec.bs index 87c5689..7ab324a 100644 --- a/spec.bs +++ b/spec.bs @@ -92,12 +92,54 @@ table { top: -0.8em; left: -0.8em; } + +/* props from https://resources.whatwg.org/standard.css */ +dl.props { display: grid; grid-template-columns: max-content auto; row-gap: 0.25em; column-gap: 1em; } +dl.props > dt { grid-column-start: 1; margin: 0; } +dl.props > dd { grid-column-start: 2; margin: 0; } +p + dl.props { margin-top: -0.5em; }

The {{URLPattern}} class

+A {{URLPattern}} consists of several [=components=], each of which represents a [=pattern string|pattern=] which could be matched against the corresponding component of a [=URL=]. + +It can be constructed using a string for each component, or from a shorthand string. It can optionally be resolved relative to a base URL. + +
+ The shorthand "`https://example.com/:category/*`" corresponds to the following components: + +
+ : [=protocol component|protocol=] + :: "`https`" + : [=username component|username=] + :: "" + : [=password component|password=] + :: "" + : [=hostname component|hostname=] + :: "`example.com`" + : [=port component|port=] + :: "" + : [=pathname component|pathname=] + :: "`/:category/*`" + : [=search component|search=] + :: "" + : [=hash component|hash=] + :: "" +
+ + It matches the following URLs: + * `https://example.com/products/` + * `https://example.com/blog/our-greatest-product-ever` + + It does not match the following URLs: + * `https://example.com/` + * `http://example.com/products/` + * `https://example.com:8443/blog/our-greatest-product-ever` +
+ typedef (USVString or URLPatternInit) URLPatternInput; @@ -833,6 +875,18 @@ To <dfn>compute protocol matches a special scheme flag</dfn> given a [=construct A <dfn>pattern string</dfn> is a string that is written to match a set of target strings. A <dfn for="pattern string">well formed</dfn> pattern string conforms to a particular pattern syntax. This pattern syntax is directly based on the syntax used by the popular [path-to-regexp](https://github.com/pillarjs/path-to-regexp) JavaScript library. +It can be [=parse a pattern string|parsed=] to produce a [=part list=] which describes, in order, what must appear in a component string for the pattern string to match. + +<div class="example"> + Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (`/` in the pathname, `.` in the hostname). For example, the pathname pattern "`/blog/:title`" will match "`/blog/hello-world`" but not "`/blog/2012/02"`. + + A regular expression can also be used instead, so the pathname pattern "`/blog/:year(\\d+)/:month(\\d+)`" will match "`/blog/2012/02`". + + A group can also be made optional, or repeated, by using a modifier. For example, the pathname pattern "`/products/:id?"` will match both "`/products`" and "`/products/2`" (but not "`/products/`"). In the pathname specifically, groups automatically require a leading `/`; to avoid this, the group can be explicitly deliminated, as in the pathname pattern "`/products/{:id}?"`. + + A full wildcard `*` can also be used to match as much as possible, as in the pathname pattern "`/products/*`". +</div> + <h3 id=parsing-patterns>Parsing Patterns</h3> <h4 id=tokens>Tokens</h4> From c87f5901b97faf7b318b842b748697840c1d2593 Mon Sep 17 00:00:00 2001 From: Jeremy Roman <jbroman@chromium.org> Date: Wed, 13 Sep 2023 06:05:32 -0400 Subject: [PATCH 2/4] Fix some refs to use the correct dfn. --- spec.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.bs b/spec.bs index 7ab324a..bc45c8f 100644 --- a/spec.bs +++ b/spec.bs @@ -104,7 +104,7 @@ p + dl.props { margin-top: -0.5em; } <h2 id=urlpattern-class>The {{URLPattern}} class </h2> -A {{URLPattern}} consists of several [=components=], each of which represents a [=pattern string|pattern=] which could be matched against the corresponding component of a [=URL=]. +A {{URLPattern}} consists of several [=components=], each of which represents a [=/pattern string|pattern=] which could be matched against the corresponding component of a [=/URL=]. It can be constructed using a string for each component, or from a shorthand string. It can optionally be resolved relative to a base URL. @@ -875,7 +875,7 @@ To <dfn>compute protocol matches a special scheme flag</dfn> given a [=construct A <dfn>pattern string</dfn> is a string that is written to match a set of target strings. A <dfn for="pattern string">well formed</dfn> pattern string conforms to a particular pattern syntax. This pattern syntax is directly based on the syntax used by the popular [path-to-regexp](https://github.com/pillarjs/path-to-regexp) JavaScript library. -It can be [=parse a pattern string|parsed=] to produce a [=part list=] which describes, in order, what must appear in a component string for the pattern string to match. +It can be [=parse a pattern string|parsed=] to produce a [=/part list=] which describes, in order, what must appear in a component string for the pattern string to match. <div class="example"> Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (`/` in the pathname, `.` in the hostname). For example, the pathname pattern "`/blog/:title`" will match "`/blog/hello-world`" but not "`/blog/2012/02"`. From 3687cfa3115b20fde1245f9bd64e6a42d67d4922 Mon Sep 17 00:00:00 2001 From: Jeremy Roman <jbroman@chromium.org> Date: Wed, 13 Sep 2023 09:16:52 -0400 Subject: [PATCH 3/4] Explicitly qualify component refs. --- spec.bs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/spec.bs b/spec.bs index bc45c8f..0b2c625 100644 --- a/spec.bs +++ b/spec.bs @@ -112,21 +112,21 @@ It can be constructed using a string for each component, or from a shorthand str The shorthand "`https://example.com/:category/*`" corresponds to the following components: <dl class="props"> - : [=protocol component|protocol=] + : [=URLPattern/protocol component|protocol=] :: "`https`" - : [=username component|username=] + : [=URLPattern/username component|username=] :: "" - : [=password component|password=] + : [=URLPattern/password component|password=] :: "" - : [=hostname component|hostname=] + : [=URLPattern/hostname component|hostname=] :: "`example.com`" - : [=port component|port=] + : [=URLPattern/port component|port=] :: "" - : [=pathname component|pathname=] + : [=URLPattern/pathname component|pathname=] :: "`/:category/*`" - : [=search component|search=] + : [=URLPattern/search component|search=] :: "" - : [=hash component|hash=] + : [=URLPattern/hash component|hash=] :: "" </dl> From 1f066e3e1a1b61019e2572adc7473959450a23da Mon Sep 17 00:00:00 2001 From: Jeremy Roman <jbroman@chromium.org> Date: Wed, 13 Sep 2023 09:30:30 -0400 Subject: [PATCH 4/4] Correct quotation mark typos --- spec.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.bs b/spec.bs index 0b2c625..99fc9ea 100644 --- a/spec.bs +++ b/spec.bs @@ -878,11 +878,11 @@ A <dfn>pattern string</dfn> is a string that is written to match a set of target It can be [=parse a pattern string|parsed=] to produce a [=/part list=] which describes, in order, what must appear in a component string for the pattern string to match. <div class="example"> - Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (`/` in the pathname, `.` in the hostname). For example, the pathname pattern "`/blog/:title`" will match "`/blog/hello-world`" but not "`/blog/2012/02"`. + Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (`/` in the pathname, `.` in the hostname). For example, the pathname pattern "`/blog/:title`" will match "`/blog/hello-world`" but not "`/blog/2012/02`". A regular expression can also be used instead, so the pathname pattern "`/blog/:year(\\d+)/:month(\\d+)`" will match "`/blog/2012/02`". - A group can also be made optional, or repeated, by using a modifier. For example, the pathname pattern "`/products/:id?"` will match both "`/products`" and "`/products/2`" (but not "`/products/`"). In the pathname specifically, groups automatically require a leading `/`; to avoid this, the group can be explicitly deliminated, as in the pathname pattern "`/products/{:id}?"`. + A group can also be made optional, or repeated, by using a modifier. For example, the pathname pattern "`/products/:id?"` will match both "`/products`" and "`/products/2`" (but not "`/products/`"). In the pathname specifically, groups automatically require a leading `/`; to avoid this, the group can be explicitly deliminated, as in the pathname pattern "`/products/{:id}?`". A full wildcard `*` can also be used to match as much as possible, as in the pathname pattern "`/products/*`". </div>