url_cleaner_engine/tutorial/cleaner/action.rs
1//! # [`Action`]
2//!
3//! Actions take a task state and modify it. For most actions this is modifying part of the task's URL, sometimes with a logic to decide if and when to do so.
4//!
5//! For example the [`RemoveQueryParams`](Action::RemoveQueryParams) removes all query params whose names are in the [`Set`].
6//!
7//! ```Json
8//! {"RemoveQueryParams": ["utm_source", "utm_content", "etc."]}
9//! ```
10//!
11//! Actions have various forms of [control flow](control_flow) that let you only apply modifications if certain conditions are met.
12//!
13//! For example, the following only removes the `t` and `s` query parameters on `x.com`:
14//!
15//! ```Json
16//! {"If": {
17//! "if": {"HostIs": "x.com"},
18//! "then": {"RemoveQueryParams": ["t", "s"]}
19//! }}
20//! ```
21//!
22//! [`Action::If`] allows an optional "else" action that's only applied when the condition isn't satisfied.
23//!
24//! ```Json
25//! {"If": {
26//! "if": {"HostIs": "x.com"},
27//! "then": {"RemoveQueryParams": ["t", "s"]},
28//! "else": "something that applies everywhere but twitter"
29//! }}
30//! ```
31//!
32//! Writing a long chain/sequence of [`Action::If`]s is both slow and ugly, so [maps] can be used to, as I call it, "do less nothing":
33//!
34//! ```Json
35//! {"PartMap": {
36//! "part": "Host",
37//! "map": {
38//! "x.com": {"RemoveQueryParams": ["t", "s"]},
39//! "youtube.com": {"RemoveQueryParams": "si"}
40//! }
41//! }}
42//! ```
43//!
44//! While, technically, an [`Action::PartMap`] is more expensive than a single [`Action::If`], the cost is only paid once.
45//!
46//! Having a 100-variant [`Action::PartMap`] is comically faster than an equivalent chain/sequence of 100 [`Action::If`]s.i
47//!
48//! In addition to [`Action::PartMap`], there is also [`Action::StringMap`], which uses [string sources](string_source) instead of [URL parts](url_part).
49
50pub(crate) use super::*;