mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-22 04:56:17 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Add map regexp capture groups (#145)

Browse source 
https://github.com/caddyserver/caddy/pull/3991

The `outputs` bit was getting a bit long so I split it up into multiple paragraphs.

The capture group explanation is copied from the `path_regexp` matcher docs.

Added bullets in front of the example cases, because the newlines get collapsed in markdown otherwise, unless we either add bullets or double newlines. I think bullets work better here.
This commit is contained in:
Francis Lavoie 2021-04-05 17:20:09 -04:00 • committed by GitHub
parent b3381f9f5c
commit d3013905cb
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 24 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

36
src/docs/markdown/caddyfile/directives/map.md
View file

@ -20,9 +20,19 @@ map [<matcher>] <source> <destinations...> {
```
- **&lt;source&gt;** is the input value to switch on. Usually a placeholder.
- **&lt;destinations...&gt;** are the placeholders to create that hold the output values.
- **&lt;input&gt;** is the input value to match. If prefixed with `~`, is treated as a regular expression.
- **&lt;outputs...&gt;** is one or more output values to store in the associated placeholder. The first output is written to the first destination, the second output to the second destination, etc. As a special case, the Caddyfile parser treats outputs that are a literal hyphen (`-`) as null/nil values. This is useful if you want to fall back to a default value for that particular output in the case of the given input, but want to use non-default values for other outputs. The number of outputs for each mapping must not exceed the number of destinations; however, for convenience, there may be fewer outputs than destinations, and any missing outputs will be filled in implicitly.
- **&lt;input&gt;** is the input value to match. If prefixed with `~`, it is treated as a regular expression.
- **&lt;outputs...&gt;** is one or more output values to store in the associated placeholder. The first output is written to the first destination, the second output to the second destination, etc.
As a special case, the Caddyfile parser treats outputs that are a literal hyphen (`-`) as null/nil values. This is useful if you want to fall back to a default value for that particular output in the case of the given input, but want to use non-default values for other outputs.
The number of outputs for each mapping must not exceed the number of destinations; however, for convenience, there may be fewer outputs than destinations, and any missing outputs will be filled in implicitly.
If a regular expression was used as the input, then the capture groups can be referenced with `${capture_group}` where `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
- **&lt;default&gt;** specifies the output values to store if no inputs are matched.
@ -31,20 +41,22 @@ map [<matcher>] <source> <destinations...> {
The following example demonstrates most aspects of this directive:
```caddy-d
map {host} {my_placeholder} {magic_number} {
example.com "some value" 3
foo.example.com "another value"
map {host} {my_placeholder} {magic_number} {
example.com "some value" 3
foo.example.com "another value"
(.*)\.example.com "${1} subdomain" 5
~.*\.net$ - 7
~.*\.xyz$ - 15
~.*\.net$ - 7
~.*\.xyz$ - 15
default "unknown domain" 42
default "unknown domain" 42
}
```
This directive switches on the value of `{host}`, i.e. the domain name of the request.
If the request is for `example.com`, set `{my_placeholder}` to `some value`, and `{magic_number}` to `3`.
Else, if the request is for `foo.example.com`, set `{my_placeholder}` to `another value`, and let `{magic_number}` default to `42`.
Else, if the request is for any host that ends in `.net` or `.xyz`, set only `{magic_number}` to `7` or `15`, respectively. Leave `{my_placeholder}` unset.
Else (for all other hosts), the default values will apply: `{my_placeholder}` will be set to `unknown domain` and `{magic_number}` will be set to `42`.
- If the request is for `example.com`, set `{my_placeholder}` to `some value`, and `{magic_number}` to `3`.
- Else, if the request is for `foo.example.com`, set `{my_placeholder}` to `another value`, and let `{magic_number}` default to `42`.
- Else, if the request is for any subdomain of `example.com`, set `{my_placeholder}` to a string containing the value of the first regexp capture group, i.e the entire subdomain, and set `{magic_number}` to 5.
- Else, if the request is for any host that ends in `.net` or `.xyz`, set only `{magic_number}` to `7` or `15`, respectively. Leave `{my_placeholder}` unset.
- Else (for all other hosts), the default values will apply: `{my_placeholder}` will be set to `unknown domain` and `{magic_number}` will be set to `42`.