diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index a9d3d0a64b0..de39d8a226e 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -1109,6 +1109,7 @@ These modifiers are able to completely change the behavior of basic rules. | [$inline-font](#inline-font-modifier) | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | [$inline-script](#inline-script-modifier) | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | [$jsonprune](#jsonprune-modifier) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| [$xmlprune](#xmlprune-modifier) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | [$network](#network-modifier) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | [$permissions](#permissions-modifier) | ✅ | ⏳ | ⏳ | ❌ | ❌ | ❌ | | [$redirect](#redirect-modifier) | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | @@ -1471,10 +1472,10 @@ Keep in mind, though, that all JSONPath implementations have unique features/qui **Exceptions** -Basic URL exceptions shall not disable rules with `$jsonprune` modifier. They can be disabled as described below: +Basic URL exceptions shall not disable rules with the `$jsonprune` modifier. They can be disabled as described below: - `@@||example.org^$jsonprune` disables all `$jsonprune` rules for responses from URLs matching `||example.org^`. -- `@@||example.org^$jsonprune=text` disable all `$jsonprune` rules with the value of the `$jsonprune` modifier equal to `text` for responses from URLs matching `||example.org^`. +- `@@||example.org^$jsonprune=text` disables all `$jsonprune` rules with the value of the `$jsonprune` modifier equal to `text` for responses from URLs matching `||example.org^`. `$jsonprune` rules can also be disabled by `$document`, `$content` and `$urlblock` exception rules. @@ -1657,8 +1658,8 @@ In AdGuard for Windows, Mac and Android **running CoreLibs v1.11 or later**, JSO :::caution Restrictions -- `$jsonprune` rules are only compatible with these specific modifiers: `$domain`, `$third-party`, `$app`, `$important`, `$match-case`, and `$xmlhttprequest`. -- `$jsonprune` rules do not apply if the size of the original response is more than 10 MB. +- `$jsonprune` rules are only compatible with these modifiers: `$domain`, `$third-party`, `$app`, `$important`, `$match-case`, and `$xmlhttprequest`. +- `$jsonprune` rules do not apply if the size of the original response is greater than 10 MB. ::: @@ -1668,6 +1669,246 @@ Rules with the `$jsonprune` modifier are supported by AdGuard for Windows, Mac, ::: +#### **`$xmlprune`** {#xmlprune-modifier} + +`$xmlprune` rules modify the response to a matching request by removing XML items that match an [XPath 1.0](https://www.w3.org/TR/1999/REC-xpath-19991116/) expression. +The expression must return a [node-set](https://www.w3.org/TR/1999/REC-xpath-19991116/#node-sets). +`$xmlprune` rules do not modify responses which are not well-formed XML documents. + +**Syntax** + +- `||example.org^$xmlprune=expression` removes items that match the XPath expression `expression` from the response. + +Due to the way rule parsing works, the characters `$` and `,` must be escaped with `\` inside `expression`. + +**Exceptions** + +Basic URL exceptions shall not disable rules with the `$xmlprune` modifier. They can be disabled as described below: + +- `@@||example.org^$xmlprune` disables all `$xmlprune` rules for responses from URLs matching `||example.org^`. +- `@@||example.org^$xmlprune=text` disables all `$xmlprune` rules with the value of the `$xmlprune` modifier equal to `text` for responses from URLs matching `||example.org^`. + +`$xmlprune` rules can also be disabled by `$document`, `$content` and `$urlblock` exception rules. + +:::note + +When multiple `$xmlprune` rules match the same request, they are applied in lexicographical order. + +::: + +**Examples** + +- `||example.org^$xmlprune=/bookstore/book[position() mod 2 = 1]` removes odd-numbered books from the bookstore. + +
+Input + +```xml + + + + + + Everyday Italian + Giada De Laurentiis + 2005 + 30.00 + + + + Harry Potter + J K. Rowling + 2005 + 29.99 + + + + XQuery Kick Start + James McGovern + Per Bothner + Kurt Cagle + James Linn + Vaidyanathan Nagarajan + 2003 + 49.99 + + + + Learning XML + Erik T. Ray + 2003 + 39.95 + + + +``` + +
+ +
+Output + +```xml + + + + + + + + Harry Potter + J K. Rowling + 2005 + 29.99 + + + + + + Learning XML + Erik T. Ray + 2003 + 39.95 + + + +``` + +
+ +- `||example.org^$xmlprune=/bookstore/book[year = 2003]` removes books from the year 2003 from the bookstore. + +
+Input + +```xml + + + + + + Everyday Italian + Giada De Laurentiis + 2005 + 30.00 + + + + Harry Potter + J K. Rowling + 2005 + 29.99 + + + + XQuery Kick Start + James McGovern + Per Bothner + Kurt Cagle + James Linn + Vaidyanathan Nagarajan + 2003 + 49.99 + + + + Learning XML + Erik T. Ray + 2003 + 39.95 + + + +``` + +
+ +
+Output + +```xml + + + + + + Everyday Italian + Giada De Laurentiis + 2005 + 30.00 + + + + Harry Potter + J K. Rowling + 2005 + 29.99 + + + + + + + +``` + +
+ +- `||example.org^$xmlprune=//*/@*` removes all attributes from all elements. + +
+Input + +```xml + + + + + + Everyday Italian + Giada De Laurentiis + 2005 + 30.00 + + + +``` + +
+ +
+Output + +```xml + + + + + + Everyday Italian + Giada De Laurentiis + 2005 + 30.00 + + + +``` + +
+ +:::caution Restrictions + +- `$xmlprune` rules are only compatible with these modifiers: `$domain`, `$third-party`, `$app`, `$important`, `$match-case`, and `$xmlhttprequest`. +- `$xmlprune` rules do not apply if the size of the original response is greater than 10 MB. + +::: + +:::info Compatibility + +Rules with the `$xmlprune` modifier are supported by AdGuard for Windows, Mac, and Android, **running CoreLibs version 1.15 or later**. + +::: + #### **`$network`** {#network-modifier} This is basically a Firewall-like rule allowing to fully block or unblock access to a specified remote address.