Mirrors/uBlock
1
0
Fork 0
mirror of https://github.com/gorhill/uBlock.git synced 2024-10-06 09:37:12 +02:00
Code Issues Releases Wiki Activity

Updated Static filter syntax (markdown)

Raymond Hill 2021-01-12 08:48:06 -05:00
parent c7ad10c5c4
commit b78e65e0c3
1 changed files with 9 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Static-filter-syntax.md

@ -552,39 +552,25 @@ See also: [`empty`](#empty), [`redirect`](#redirect)
#### `queryprune`
<details>
<summary>Work in progress, syntax still experimental - valid only on uBO 1.31.0, documentation not complete</summary>
New in [1.32.0](https://github.com/gorhill/uBlock/commit/1e2eb037e5b4754feb4a40519951b3e7a73d545d).
New in [1.31.0](https://github.com/gorhill/uBlock/commit/1e2eb037e5b4754feb4a40519951b3e7a73d545d).
To remove query parameters form the URL of network requests.
Available only to filter list authors.
To remove query parameters from the URL of network requests. uBO can also parse and enforce [AdGuard's `removeparam`](https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters?aid=16593#removeparam-modifier) as a synonym of `queryprune`.
`queryprune` is a modifier option (like `csp`) in that it does not cause a network request to be blocked but rather modified before being emitted.
`queryprune` must be assigned a value, which value will determine which parameters from a query string will be removed. The syntax for the value is that of regular expression *except* for the following rules:
`queryprune` must be assigned a value, which value will determine which exact parameter from a query string will be removed:
- do not wrap the regex directive between `/`
- do not use regex special values `^` and `$`
- do not use literal comma character in the value, though you can use hex-encoded version, `\x2c`
- to match the start of a query parameter, prepend `|`
- to match the end of a query parameter, append `|`
*$queryprune=utm_source
`queryprune` regex-like values will be tested against each key-value parameter pair as `[key]=[value]` string. This way you can prune according to either the key, the value, or both.
The above filter tells uBO to remove the query parameter `utm_source` when present in a URL.
**Important:** avoiding `queryprune` from being visited at all is best, I do hope filter authors will be as carefully as possible when crafting `queryprune` filters as I am careful at minimizing all overhead in the code -- otherwise all the coding efforts are going to waste. So typically the query parameter of interest will be part of the filter pattern:
The value assigned to `queryprune` can be a literal regular expression, in which case uBO will remove query parameters matching the regular expression:
||reddit.com^*utm_$queryprune=|utm_
||youtube.com^*fbclid*$queryprune=fbclid
||youtube.com^*gclid*$queryprune=gclid
*$queryprune=/^utm_/
This way uBO will scan the query parameters only when the URL is found to match the targeted query parameters. Mind performance when crafting filters. Your proposed filters forces uBO to scan every URL matching `reddit.com` and `youtube.com`.
The above filter will remove all query parameters which name starts with `utm_`, regardless of their value. When using a literal regular expression, it is tested against each query parameter name-value pair assembled into a single string as `name=value`.
Additionally, prepending `queryprune` values with `|` when the match is of the "starts with" kind also helps.
</details>
Poorly crafted `queryprune` filters can have deleterious effects on performance, experienced filter authors are expected to understand well how to craft optimal filters.
***