From ddc5aa44338f9c21a9ee192371f9ee5c0c9ec141 Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Mon, 9 Oct 2023 23:13:15 +0300 Subject: [PATCH 1/8] describe else directive --- .../ad-filtering/create-own-filters.md | 46 +++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 6a05e7b37b6..30bfa49d8cd 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3872,12 +3872,24 @@ Filter URL: `https://example.org/path/filter.txt` #### Conditions {#conditions-directive} -Filters maintainers can use conditions to supply different rules depending on the ad blocker type. When an adblocker encounters an `!#if` directive, followed eventually by an `!#endif` directive, it will compile the code inside of the directives block only if the specified condition is true. Condition supports all the basic logical operators. +Filters maintainers can use conditions to supply different rules depending on the ad blocker type. +A conditional directive beginning with a `!#if` directive must explicitly be terminated with an `!#endif` directive. +Conditions support all basic logical operators. -A conditional directive beginning with an `!#if` directive must explicitly be terminated with an `!#endif` directive. +There are two possible scenarios: + +1. When an ad blocker encounters a `!#if` directive and no `!#else` directive, + it will compile the code between `!#if` and `!#endif` directives only if the specified condition is true. + +1. If there is an `!#else` directive, the code between `!#if` and `!#else` will be compiled if the condition is true; + otherwise, the code between `!#else` and `!#endif` will be compiled. + +:::note Whitespaces matter. `!#if` is a valid directive, while `!# if` is not. +::: + **Syntax** ```adblock @@ -3886,6 +3898,16 @@ rules_list !#endif ``` +or + +```adblock +!#if (conditions) +true_conditions_rules_list +!#else +false_conditions_rules_list +!#endif +``` + where: - `!#if (conditions)` — start of the block @@ -3903,7 +3925,7 @@ where: - `adguard_ext_opera` — AdGuard Browser Extension for Opera - `adguard_ext_android_cb` — AdGuard Content Blocker for mobile Samsung and Yandex browsers - `ext_ublock` — special case; this one is declared when a uBlock version of a filter is compiled by the [FiltersRegistry](https://github.com/AdguardTeam/FiltersRegistry) -- `rules_list` — list of rules +- `rules_list`, `true_conditions_rules_list`, `false_conditions_rules_list` — lists of rules - `!#endif` — end of the block **Examples** @@ -3923,6 +3945,23 @@ domain.com##div.ad !#endif ``` +```adblock +!#if (adguard && !adguard_ext_safari) +! for all AdGuard products except AdGuard for Safari +||example.org^$third-party +domain.com##div.ad +!#else +! for AdGuard for Safari only +||subdomain.example.org^$third-party +!#endif +``` + +:::info Compatibility + +The `!#else` directive is supported by the [FiltersDownloader][gh-filters-downloader] v1.1.16 or later. + +::: + #### Safari affinity {#safari-affinity-directive} Safari's limit for each content blocker is 150,000 active rules. But in AdGuard for Safari and AdGuard for iOS, we've split the rules into 6 content blockers, thus increasing the rule limit to 900,000. @@ -4231,3 +4270,4 @@ If you need an advice on how to create your own filters properly, our forum has [and-cb]: #what-product "AdGuard Content Blocker for Samsung Internet and Yandex Browser on Android" [sec-fetch-dest-header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest +[gh-filters-downloader]: https://github.com/AdguardTeam/FiltersDownloader/ From b43902e27cf38973e77d1a6a7571c70cc0d43043 Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Tue, 10 Oct 2023 16:36:40 +0300 Subject: [PATCH 2/8] fix FiltersDownloader version --- 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 30bfa49d8cd..e7a7419e852 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3958,7 +3958,7 @@ domain.com##div.ad :::info Compatibility -The `!#else` directive is supported by the [FiltersDownloader][gh-filters-downloader] v1.1.16 or later. +The `!#else` directive is supported by the [FiltersDownloader][gh-filters-downloader] v1.1.20 or later. ::: From a034ed202aacc785775acad424fd3588969d111c Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Wed, 11 Oct 2023 11:17:00 +0300 Subject: [PATCH 3/8] update compatibility note for else directive --- .../ad-filtering/create-own-filters.md | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index e7a7419e852..5f041068936 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3911,7 +3911,10 @@ false_conditions_rules_list where: - `!#if (conditions)` — start of the block -- `conditions` — just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. Ad blocker authors define on their own what exact constants do they declare. Possible values: +- `conditions` — just like in some popular programming languages, + preprocessor conditions are based on constants declared by ad blockers. + Ad blocker authors define on their own what exact constants do they declare. + Possible values: - `adguard` always declared; shows maintainers that this is one of AdGuard products; should be enough in 95% of cases - product-specific constants for cases when you need a rule to work (or not work — then `!` should be used before constant) in a specific product only: - `adguard_app_windows` — AdGuard for Windows @@ -3924,7 +3927,7 @@ where: - `adguard_ext_edge` — AdGuard Browser Extension for Edge Legacy - `adguard_ext_opera` — AdGuard Browser Extension for Opera - `adguard_ext_android_cb` — AdGuard Content Blocker for mobile Samsung and Yandex browsers - - `ext_ublock` — special case; this one is declared when a uBlock version of a filter is compiled by the [FiltersRegistry](https://github.com/AdguardTeam/FiltersRegistry) + - `ext_ublock` — special case; this one is declared when a uBlock version of a filter is compiled by the [FiltersRegistry] - `rules_list`, `true_conditions_rules_list`, `false_conditions_rules_list` — lists of rules - `!#endif` — end of the block @@ -3960,6 +3963,14 @@ domain.com##div.ad The `!#else` directive is supported by the [FiltersDownloader][gh-filters-downloader] v1.1.20 or later. +It is already supported for filter lists which are compiled by the [FiltersRegistry], +but may not be supported by AdGuard products yet during adding a filter list with `!#else` as a custom one. +Following products will support it in the mentioned versions or later: + +- AdGuard for Windows, Mac, and Android, running CoreLibs v1.13; +- AdGuard Browser Extension v4.3; +- AdGuard for Safari v1.11.16. + ::: #### Safari affinity {#safari-affinity-directive} @@ -4023,7 +4034,7 @@ example.org#@#.adBanner ### Hints -"Hint" is a special comment, instruction to the filters compiler used on the server side (see [FiltersRegistry](https://github.com/AdguardTeam/FiltersRegistry)). +"Hint" is a special comment, instruction to the filters compiler used on the server side (see [FiltersRegistry]). **Syntax** @@ -4270,4 +4281,5 @@ If you need an advice on how to create your own filters properly, our forum has [and-cb]: #what-product "AdGuard Content Blocker for Samsung Internet and Yandex Browser on Android" [sec-fetch-dest-header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest -[gh-filters-downloader]: https://github.com/AdguardTeam/FiltersDownloader/ +[gh-filters-downloader]: https://github.com/AdguardTeam/FiltersDownloader +[FiltersRegistry]: https://github.com/AdguardTeam/FiltersRegistry From 5a8e54356ca79348fba7edc846ef559c4fbda17f Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Wed, 11 Oct 2023 11:21:10 +0300 Subject: [PATCH 4/8] fix syntax desc --- docs/general/ad-filtering/create-own-filters.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 5f041068936..255a7e85778 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3910,7 +3910,7 @@ false_conditions_rules_list where: -- `!#if (conditions)` — start of the block +- `!#if (conditions)` — start of the block when conditions are true - `conditions` — just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. Ad blocker authors define on their own what exact constants do they declare. @@ -3928,6 +3928,7 @@ where: - `adguard_ext_opera` — AdGuard Browser Extension for Opera - `adguard_ext_android_cb` — AdGuard Content Blocker for mobile Samsung and Yandex browsers - `ext_ublock` — special case; this one is declared when a uBlock version of a filter is compiled by the [FiltersRegistry] +- `!#else` — start of the block when conditions are false - `rules_list`, `true_conditions_rules_list`, `false_conditions_rules_list` — lists of rules - `!#endif` — end of the block From 2891f2766bb3e1fb32439c3f582889e7cf96de93 Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Wed, 11 Oct 2023 11:25:34 +0300 Subject: [PATCH 5/8] fix grammar --- 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 255a7e85778..faace4e133b 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3964,9 +3964,9 @@ domain.com##div.ad The `!#else` directive is supported by the [FiltersDownloader][gh-filters-downloader] v1.1.20 or later. -It is already supported for filter lists which are compiled by the [FiltersRegistry], -but may not be supported by AdGuard products yet during adding a filter list with `!#else` as a custom one. -Following products will support it in the mentioned versions or later: +It is already supported for filter lists compiled by the [FiltersRegistry], +but it still may not be supported by AdGuard products when adding a filter list with `!#else` as a custom one. +The following products will support it in the mentioned versions or later: - AdGuard for Windows, Mac, and Android, running CoreLibs v1.13; - AdGuard Browser Extension v4.3; From ab2cefee9bf74e55fe16cf5034795357c6c7c4ab Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Fri, 20 Oct 2023 12:02:41 +0300 Subject: [PATCH 6/8] fix conditions desc --- 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 faace4e133b..80dea5abcf4 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3913,7 +3913,7 @@ where: - `!#if (conditions)` — start of the block when conditions are true - `conditions` — just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. - Ad blocker authors define on their own what exact constants do they declare. + Authors of ad blockers define on their own what exact constants they declare. Possible values: - `adguard` always declared; shows maintainers that this is one of AdGuard products; should be enough in 95% of cases - product-specific constants for cases when you need a rule to work (or not work — then `!` should be used before constant) in a specific product only: From 2d5a720b58ca6d1c8485fac088026b5cef58e0bd Mon Sep 17 00:00:00 2001 From: Slava <45171506+slavaleleka@users.noreply.github.com> Date: Fri, 20 Oct 2023 12:03:19 +0300 Subject: [PATCH 7/8] fix "an" 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 80dea5abcf4..e093014f540 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3878,7 +3878,7 @@ Conditions support all basic logical operators. There are two possible scenarios: -1. When an ad blocker encounters a `!#if` directive and no `!#else` directive, +1. When an ad blocker encounters an `!#if` directive and no `!#else` directive, it will compile the code between `!#if` and `!#endif` directives only if the specified condition is true. 1. If there is an `!#else` directive, the code between `!#if` and `!#else` will be compiled if the condition is true; From 6890db854feafc1772bc92e27caa9cbb28a73096 Mon Sep 17 00:00:00 2001 From: Slava Leleka Date: Fri, 20 Oct 2023 21:09:42 +0300 Subject: [PATCH 8/8] fix extension version --- 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 81b47f5082b..8b4e54dc5d6 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3968,7 +3968,7 @@ but it still may not be supported by AdGuard products when adding a filter list The following products will support it in the mentioned versions or later: - AdGuard for Windows, Mac, and Android, running CoreLibs v1.13; -- AdGuard Browser Extension v4.3; +- AdGuard Browser Extension v4.2.208; - AdGuard for Safari v1.11.16. :::