From 79065e55b2a7fb11d384c4bbb22efdd697e814c8 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Wed, 15 Oct 2025 15:26:04 +0300 Subject: [PATCH 1/5] Update $urltransform documentation --- .../ad-filtering/create-own-filters.md | 27 +++++++++++++++---- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 06975e04043..c81108bbb30 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 which use a version of [CoreLibs] older than 1.20 only support a single +`substitute` transformation as the value of the `$urltransform` modifier. + +::: + **Changing the origin** :::info Compatibility From 17f34326c97cfb4b397f4c70110ec2882cbcd86d Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Wed, 15 Oct 2025 15:50:12 +0300 Subject: [PATCH 2/5] Add spaces --- docs/general/ad-filtering/create-own-filters.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index c81108bbb30..10530e46463 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -2923,9 +2923,9 @@ decode = "b64" | "pct" ``` - **`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. + - **`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. From de0b99620e1294b4d09129ab992ef76134ebbea4 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh <57908117+ngorskikh@users.noreply.github.com> Date: Thu, 16 Oct 2025 12:12:28 +0300 Subject: [PATCH 3/5] Update docs/general/ad-filtering/create-own-filters.md Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 10530e46463..3dab19e48d5 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -2925,7 +2925,7 @@ decode = "b64" | "pct" - **`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. + - **`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. From bb7d3e83a4938f5cdcd67745a7f2bdef7055563a Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh <57908117+ngorskikh@users.noreply.github.com> Date: Thu, 16 Oct 2025 12:12:35 +0300 Subject: [PATCH 4/5] Update docs/general/ad-filtering/create-own-filters.md Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 3dab19e48d5..6844e2eb21a 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -2934,7 +2934,7 @@ In the `$urltransform` value, two characters must be escaped: the comma `,` and :::info Compatibility AdGuard products which use a version of [CoreLibs] older than 1.20 only support a single -`substitute` transformation as the value of the `$urltransform` modifier. +`substitute` transformation for the value of the `$urltransform` modifier. ::: From c04502016adf58f567299f80c56e116ffbaac226 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh <57908117+ngorskikh@users.noreply.github.com> Date: Thu, 16 Oct 2025 12:12:42 +0300 Subject: [PATCH 5/5] Update docs/general/ad-filtering/create-own-filters.md Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 6844e2eb21a..b89239263f7 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -2933,7 +2933,7 @@ In the `$urltransform` value, two characters must be escaped: the comma `,` and :::info Compatibility -AdGuard products which use a version of [CoreLibs] older than 1.20 only support a single +AdGuard products that use a [CoreLibs] version older than 1.20 only support a single `substitute` transformation for the value of the `$urltransform` modifier. :::