diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 06975e04043..b89239263f7 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -2909,18 +2909,35 @@ If multiple `$urltransform` rules match a single request, we will apply each of **Syntax** -`$urltransform` syntax is similar to replacement with regular expressions [in Perl](http://perldoc.perl.org/perlrequick.html#Search-and-replace). +`$urltransform` value is a series of one or more transformations separated by `|`. The first transformation is +applied to the input URL. Each of the following transformations is applied to the output of the previous one. +The output of a failed transformation (for example, if Base64 decoding failed or if substitution found no matches) +is its input, unchanged. Formally: ```text -urltransform = "/" regexp "/" replacement "/" modifiers +urltransform = transforms +transforms = transform | transform "|" transforms +transform = substitute | decode +substitute = "/" regexp "/" replacement "/" modifiers +decode = "b64" | "pct" ``` -- **`regexp`** — a regular expression. -- **`replacement`** — a string that will be used to replace the string corresponding to `regexp`. -- **`modifiers`** — a regular expression flags. For example, `i` — insensitive search, or `s` — single-line mode. +- **`substitute`** is similar to replacement with regular expressions [in Perl](https://perldoc.perl.org/perlrequick.html#Search-and-replace). + - **`regexp`** — a regular expression. + - **`replacement`** — a string that replaces whatever is matched by `regexp`. `$1`, `$2`, etc. in the replacement string are replaced with the contents of the corresponding capture group. + - **`modifiers`** — regular expression flags, e.g., `i` for case-insensitive search. +- **`b64`** — decodes a [Base64-encoded](https://datatracker.ietf.org/doc/html/rfc4648) string, both the default and the URL-safe alphabets are supported. +- **`pct`** — decodes a [percent-encoded](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) string. In the `$urltransform` value, two characters must be escaped: the comma `,` and the dollar sign `$`. Use the backslash character `\` for this. For example, an escaped comma looks like this: `\,`. +:::info Compatibility + +AdGuard products that use a [CoreLibs] version older than 1.20 only support a single +`substitute` transformation for the value of the `$urltransform` modifier. + +::: + **Changing the origin** :::info Compatibility