From 1bdda03bfbaa7436ae00226bc32a334c8486a8bc Mon Sep 17 00:00:00 2001 From: garry-ut99 <72945564+garry-ut99@users.noreply.github.com> Date: Wed, 26 Jun 2024 13:44:02 +0000 Subject: [PATCH] Updated description of scriptlets's output logging method. --- Resources-Library.md | 59 +++++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/Resources-Library.md b/Resources-Library.md index 5aec911..eed6b26 100644 --- a/Resources-Library.md +++ b/Resources-Library.md @@ -135,6 +135,13 @@ - Starting with [1.46.1b17](https://github.com/gorhill/uBlock/commit/81498474d6d440b032681aa9952d593749b39efb) support for regex-based values as target domain has been added. Use sparingly, when no other solution is practical from a maintenance point of view -- keeping in mind that uBO has to iterate through all the regex-based values, unlike plain hostname or entity-based values which are mere lookups. Related discussion: [uBlockOrigin/uBlock-issues#2234](https://github.com/uBlockOrigin/uBlock-issues/discussions/2234). Example: `/img[a-z]{3,5}\.buzz/##+js(nowoif)`. - The usage of named arguments is optional, positional arguments are still supported as documented. Named arguments is required to use "log" and/or "debug" arguments. - The logging/debugging capabilities work only in the **dev build** of uBO or if the advanced setting `filterAuthorMode` is set to `true`. +- Starting with [1.57.3b1](https://github.com/gorhill/uBlock/commit/3b4f02db21), the old method of displaying scriptlets's logs in browser's dev console and via `(log, 1)` tokens is deprecated: + - now all scriptlets's logging output is automatically displayed in [the logger](./The-logger) & the logger's console pane. + - in the logger, toggling labels `info` and `error` in [filter input field](./The-logger#filtering-the-logger-output) can be used to reduce information displayed in the logger to informations and errors, including scriptlets, and with additional `not` operator selected, the opposite effect can be achieved. + - in the logger's console pane, toggling additionally [verbose mode button](./The-logger#verbose-mode), will cause console pane to print more logs from scriptlets. + - by default, scriptlets will print out only calls and informations related to their orders and targets, +to log _all_ calls without defusing any of them, a scriptlet without parameters can be used, example: `wikipedia.org##+js(aeld)` + - related discussions: [uBlockOrigin/uAssets/discussions/17907](https://github.com/uBlockOrigin/uAssets/discussions/17907) and [uBlockOrigin/uBlock-issues/discussions/3096](https://github.com/uBlockOrigin/uBlock-issues/discussions/3096) - The only filter lists deemed from a "trusted source" are uBO-specific filter lists (i.e. "uBlock filters -- ..."). The user's own filters from "My filters" are trusted only in the **dev build** of uBO. This behaviour can be overridden with the advanced setting `trustedListPrefixes`. - Tokens are parameters which modify the behavior of a scriptlet, they must be used after the required and optional parameters. @@ -158,10 +165,11 @@ Examples: - `tichyseinblick.de##+js(acis, Math, /\}\s*\(.*?\b(self|this|window)\b.*?\)/)` -Starting with [1.48.5b4](https://github.com/gorhill/uBlock/commit/edbe96a4010cff59a37c2aa2ec0fb89c48c913f9), you can use the logging abilites. +~~Starting with [1.48.5b4](https://github.com/gorhill/uBlock/commit/edbe96a4010cff59a37c2aa2ec0fb89c48c913f9), you can use the logging abilites.~~ (depracated) +(read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) Tokens: - - `log, 1`: output useful information at the dev console. + - ~~`log, 1`: output useful information at the dev console.~~ (deprecated) - `debug, 1`: break at key locations in the scriptlet. *** @@ -245,30 +253,47 @@ Examples: Tokens: - "runAt": when this parameter is present, uBO will take it into account to possibly defer defusing the event listener ([New in 1.49.3b4](https://github.com/gorhill/uBlock/commit/3c12173dfe4eea7c4b6758c556ed2dd5fcdbdd99)): - end: execute scriptlet at `DOMContentLoaded` event ("interactive") - - idle: execute scriptlet at `load` event ("complete") + - idle: execute scriptlet at `load` event ("complete") + - "debug": an integer value telling when to break into the debugger, useful to inspect the debugger's call stack. + - 1: break into the debugger when both type and pattern match, so effectively when defusing is taking place. + - 2: break into the debugger when either type or pattern matches. + +
+ ● "log": (depracated) + +▬▬► SPOILER START ◄▬▬ + - "log": an integer value telling when to log (see [uBlockOrigin/uAssets#17907](https://github.com/uBlockOrigin/uAssets/discussions/17907)): - 1: log only when both type and pattern matches, i.e. when a call to `addEventListener()` is defused - 2: log when either the type or pattern matches - 3: log all calls to `addEventListener()` - - "debug": an integer value telling when to break into the debugger, useful to inspect the debugger's call stack. - - 1: break into the debugger when both type and pattern match, so effectively when defusing is taking place. - - 2: break into the debugger when either type or pattern matches. Examples: - `wikipedia.org##+js(aeld, /mouse/, /.^/, log, 2)` - `wikipedia.org##+js(aeld, , /.^/, log, 2)` - `wikipedia.org##+js(aeld, , , log, 1)` - - `jpvhub.com##+js(aeld, click, popMagic, runAt, idle)` + - `wikipedia.org##+js(aeld, _, , log, 3)` The first filter will log calls to `addEventListener()` which have the pattern "mouse" in the event type (so "mouseover", "mouseout", etc.) **without defusing any of them** (because pattern can't match _anything_). The second filter will log all calls **without defusing any of them** (because type can't match _anything_). -The forth filter will log and defuse _all_ calls to `addEventListener()`. +The third filter will log and defuse _all_ calls to `addEventListener()` -In summary, if you need to only log all event listeners, use this filter: +The fourth filter will log _all_ calls to `addEventListener()` **without defusing any of them** -`example.com##+js(aeld, _, , log, 3)` +▬▬► SPOILER END ◄▬▬ + +
+ +(read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) + +Examples: + + - `jpvhub.com##+js(aeld, click, popMagic, runAt, idle)` + - `wikipedia.org##+js(aeld)` + +The second filter will log _all_ calls to `addEventListener()` **without defusing any of them** *** @@ -437,7 +462,7 @@ Parameters: - optional, a URL which must be a match for the pruning to occur. If left blank, the pruning can be performed regardless. Tokens: - - `log, 1` + - ~~`log, 1`~~ (deprecated, read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) - `logdoc, 1`: Dumps the whole document being worked on to the console Examples: @@ -777,7 +802,8 @@ in order for the substitution to occur - `sedCount, n`: This will cause the scriptlet to stop after `n` instances of substitution. Since a mutation oberver is used by the scriptlet, it's advised to stop it whenever it becomes pointless. Default to zero, which means the scriptlet never stops - `stay, 1`: Force the scriptlet to stay at work forever - `quitAfter, ms`: This tells the scriptlet to quit `ms` milliseconds after the page has been loaded, i.e. after the `DOMContentLoaded` event has been fired - - `log, 1`: This will cause the scriptlet to output information at the console, useful as a debugging tool for filter authors + - ~~`log, 1`~~: This will cause the scriptlet to output information at the console, useful as a debugging tool for filter authors +(deprecated, read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) Examples: - `example.com##+js(rpnt, #text, /^Advertisement$/)` @@ -816,7 +842,8 @@ in order for the removing to occur - `sedCount, n`: This will cause the scriptlet to stop after `n` instances of removing. Since a mutation oberver is used by the scriptlet, it's advised to stop it whenever it becomes pointless. Default to zero, which means the scriptlet never stops - `stay, 1`: Force the scriptlet to stay at work forever - `quitAfter, ms`: This tells the scriptlet to quit `ms` milliseconds after the page has been loaded, i.e. after the `DOMContentLoaded` event has been fired - - `log, 1`: This will cause the scriptlet to output information at the console, useful as a debugging tool for filter authors + - ~~`log, 1`~~: This will cause the scriptlet to output information at the console, useful as a debugging tool for filter authors +(deprecated, read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) Examples: - `example.com##+js(rmnt, #text, Example)` @@ -878,7 +905,8 @@ Parameters: Tokens: -`log, 1`: This will cause the scriptlet to output information at the console, useful as a debugging tool for filter authors +~~`log, 1`~~: This will cause the scriptlet to output information at the console, useful as a debugging tool for filter authors +(deprecated, read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) Examples: @@ -1248,7 +1276,8 @@ Parameters: - optional, `obj`: Use an `object` element instead of `iframe` element (default) as a decoy to be used in place of a popup window, when the page requires a valid `window` instance to be returned. Tokens: - - `log, 1`: Cause the scriptlet to log information regarding how `window.open()` is used by the page on which the scriptlet is used. + - ~~`log, 1`~~: Cause the scriptlet to log information regarding how `window.open()` is used by the page on which the scriptlet is used. +(deprecated, read [General purpose scriptlets](#general-purpose-scriptlets) about the new logging method) Examples: - `file-up.org##+js(nowoif)`