Skip to content

Commit

Permalink
support !#else directive. #20 AG-26168
Browse files Browse the repository at this point in the history
Squashed commit of the following:

commit a568d65
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 22:08:47 2023 +0300

    fix linter

commit 4ea3cb5
Merge: dd94c11 4e77339
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 22:07:38 2023 +0300

    merge master into the branch

commit dd94c11
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 22:03:09 2023 +0300

    fix FiltersDownloaderCreator() comment

commit e6588f7
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 19:22:29 2023 +0300

    remove not used function

commit bf0c4bf
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 16:51:22 2023 +0300

    fix jsdoc

commit b912971
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 16:49:35 2023 +0300

    add more tests

commit 5b79151
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 16:49:25 2023 +0300

    handle invalid else directive

commit 31fd9bb
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 16:26:39 2023 +0300

    fix tests

commit d50744d
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 16:17:07 2023 +0300

    improve tests

commit dbe5e67
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 15:42:44 2023 +0300

    use one function instead of findConditionEnd and findConditionElse

commit a50ddcf
Merge: 86ce098 086b55a
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Mon Oct 2 15:18:59 2023 +0300

    Merge branch 'master' into feature/AG-26168

commit 86ce098
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Fri Sep 29 21:13:00 2023 +0300

    add tests for else directive

commit 7f1eb3f
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Fri Sep 29 21:12:49 2023 +0300

    add logging for tests

commit eb9fc5c
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Fri Sep 29 21:12:23 2023 +0300

    support else directive

commit cfeba9c
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Fri Sep 29 17:23:22 2023 +0300

    add cosmetic code fixes

commit e3e0597
Author: Slava Leleka <v.leleka@adguard.com>
Date:   Fri Sep 29 17:19:38 2023 +0300

    update readme
  • Loading branch information
slavaleleka committed Oct 3, 2023
1 parent 4e77339 commit afc60c5
Show file tree
Hide file tree
Showing 4 changed files with 529 additions and 47 deletions.
54 changes: 40 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,61 @@ This utility tool resolves preprocessor directives in filter content.

### Directives syntax

```
```adblock
!#if condition
Anything goes here
!#include URL_or_a_relative_path
!#endif
```

- !#if, !#endif - filters maintainers can use these conditions to supply different rules depending on the ad blocker type.
- condition - just like in some popular programming languages, pre-processor conditions are based on constants declared by ad blockers. Ad blocker authors define on their own what exact constants do they declare.
- !#include - this directive allows to include contents of a specified file into the filter.
or with an `else` branch:

```adblock
!#if condition
!#include URL_or_a_relative_path
!#else
!#include another_URL_or_a_relative_path
!#endif
```

- `!#if`, `!#else`, `!#endif` — filters maintainers can use these conditions
to supply different rules depending on the ad blocker type.
- `condition` — just like in some popular programming languages,
pre-processor conditions are based on constants declared by ad blockers.
Ad blocker authors define on their own what exact constants do they declare.
- `!#include` — this directive allows to include contents of a specified file into the filter.

#### Logical conditions

When an adblocker encounters an `!#if` directive and no `!#else` directive,
it will compile the code between `!#if` and `!#endif` only if the specified condition is true.

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.

#### Logical Conditions
When an adblocker encounters an !#if directive, followed eventually by an !#endif directive, it will compile the code between the directives only if the specified condition is true. Condition supports all the basic logical operators.
Condition supports all the basic logical operators, i.e. `&&`, `||`, `!` and parentheses.

Example:
```

```adblock
!#if (adguard && !adguard_ext_safari)
||example.org^$third-party
!#endif
```

#### Include
The !#include directive supports only files from the same origin to make sure that the filter maintainer is in control of the specified file. The included file can also contain pre-processor directives (even other !#include directives).

The `!#include` directive supports only files from the same origin
to make sure that the filter maintainer is in control of the specified file.
The included file can also contain pre-processor directives (even other !#include directives).

Ad blockers should consider the case of recursive !#include and implement a protection mechanism.

Examples:

Filter URL: https://example.org/path/filter.txt
Filter URL: `https://example.org/path/filter.txt`

```
```adblock
!
! Valid (same origin):
!#include https://example.org/path/includedfile.txt
Expand All @@ -50,16 +74,18 @@ Filter URL: https://example.org/path/filter.txt
```

## Build

To build one file for browser environment:
```

```bash
yarn build
```

See `/build` for results.
See `build/` directory for results.

## Usage

```
```js
const FilterCompilerConditionsConstants = {
adguard: true,
....
Expand All @@ -86,6 +112,6 @@ promise.then((compiled) => {

## Tests

```
```bash
yarn test
```
Loading

0 comments on commit afc60c5

Please sign in to comment.