diff --git a/src/docs/markdown/caddyfile/directives/map.md b/src/docs/markdown/caddyfile/directives/map.md index 11481e7..0e9717f 100644 --- a/src/docs/markdown/caddyfile/directives/map.md +++ b/src/docs/markdown/caddyfile/directives/map.md @@ -20,9 +20,19 @@ map [] { ``` - **<source>** is the input value to switch on. Usually a placeholder. + - **<destinations...>** are the placeholders to create that hold the output values. -- **<input>** is the input value to match. If prefixed with `~`, is treated as a regular expression. -- **<outputs...>** 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. + +- **<input>** is the input value to match. If prefixed with `~`, it is treated as a regular expression. + +- **<outputs...>** 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. + - **<default>** specifies the output values to store if no inputs are matched. @@ -31,20 +41,22 @@ map [] { 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`.