farben 0.19.0-beta.2

Markup for the Terminal, but safer and faster.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! Macros that strip ANSI, strip markup, and escape markup brackets.

/// Removes all CSI ANSI escape sequences from a formatted string.
///
/// Accepts the same arguments as [`format!`]. Every sequence of the form
/// `ESC [ ... <letter>` is removed. Non-CSI `ESC` bytes are left intact.
///
/// The return type is `String`.
///
/// # Examples
///
/// ```
/// use farben::prelude::*;
///
/// let colored = "\x1b[31mError\x1b[0m";
/// let plain = unansi!("{}", colored);
/// assert_eq!(plain, "Error");
/// ```
///
/// Format arguments work exactly as they do with `format!`:
///
/// ```
/// use farben::prelude::*;
///
/// let code = 42;
/// let plain = unansi!("\x1b[1mcode {code}\x1b[0m");
/// assert_eq!(plain, "code 42");
/// ```
#[macro_export]
macro_rules! unansi {
    ($fmt:literal $($rest:tt)*) => {{
        $crate::strip_ansi(&format!($fmt $($rest)*))
    }};
    ($s:expr) => {{
        $crate::strip_ansi(&$s.to_string())
    }};
}

/// Removes all Farben markup tags from a formatted string.
///
/// Accepts the same arguments as [`format!`]. Every tag like `[bold]` or `[/]`
/// is removed. Invalid markup is left as-is without panicking.
///
/// The return type is `String`.
///
/// # Example
/// ```
/// use farben::prelude::*;
///
/// let stripped = unmarkup!("[bold red]Just the text");
/// assert_eq!("Just the text", stripped);
///
/// let invalid = unmarkup!("[I'm unclosed");
/// assert_eq!("[I'm unclosed", invalid);
///
/// let text = "hey!";
/// let formatted = unmarkup!("[bold red]{text}");
/// assert_eq!("hey!", formatted);
/// ```
#[macro_export]
macro_rules! unmarkup {
    ($($arg:tt)*) => {{
        $crate::strip_markup(&format!($($arg)*))
    }};
}

/// Escapes markup brackets in a formatted string so they render as literal text.
///
/// Every `[` becomes `[[` and every `]` becomes `]]`. The lexer treats `[[` as
/// a literal `[` and `]]` as a literal `]`, so the result contains no parseable tags.
///
/// Accepts the same arguments as [`format!`].
///
/// The return type is `String`.
///
/// # Example
/// ```
/// use farben::prelude::*;
///
/// let safe = untag!("[bold]hello[/]");
/// assert_eq!(safe, "[[bold]]hello[[/]]");
///
/// let name = "world";
/// let safe = untag!("[bold]{name}[/]");
/// assert_eq!(safe, "[[bold]]world[[/]]");
/// ```
#[macro_export]
macro_rules! untag {
    ($($arg:tt)*) => {{
        $crate::escape_tags(&format!($($arg)*))
    }};
}

// --- Deprecated aliases ---------------------------------------------------

#[deprecated(since = "0.19.0", note = "renamed to `unansi!`")]
#[macro_export]
/// Deprecated in favor of [`unansi!`].
macro_rules! ansi_strip {
    ($($arg:tt)*) => {{
        $crate::unansi!($($arg)*)
    }};
}

#[deprecated(since = "0.19.0", note = "renamed to `unmarkup!`")]
#[macro_export]
/// Deprecated in favor of [`unmarkup!`]
macro_rules! markup_strip {
    ($($arg:tt)*) => {{
        $crate::unmarkup!($($arg)*)
    }};
}