farben 0.19.0

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

//! Core coloring functions.
//!
//! Runtime entry points for parsing and rendering farben markup into ANSI escape sequences.
//! The [`inline`](farben_core::inline) pre-processor is applied automatically when the
//! `inline` feature is enabled, converting `*bold*`, `/italic/`, and `` `code` `` syntax
//! into standard farben tags before tokenization.

use std::sync::OnceLock;

use crate::color_enabled;
#[cfg(feature = "inline")]
use farben_core::inline;
use farben_core::{ansi, errors, parser, registry};

/// Parses and renders a farben markup string, appending a final SGR reset.
///
/// # Errors
///
/// Returns a `LexError` if the input contains an unclosed tag, an unknown tag name,
/// or a malformed color value.
pub fn try_color(input: impl Into<String>) -> Result<String, errors::LexError> {
    let input = input.into();
    #[cfg(feature = "inline")]
    let input = inline::preprocess(&input);
    let mut res = parser::render_str(&input)?;
    if color_enabled() {
        res.push_str("\x1b[0m");
    }
    Ok(res)
}

/// Parses and renders a farben markup string, appending a final SGR reset.
///
/// # Panics
///
/// Panics if the input is not valid farben markup. Use [`try_color`] to handle errors explicitly.
#[cfg(not(feature = "compile"))]
pub fn color(input: impl Into<String>) -> String {
    color_runtime(input, false)
}

/// Parses and renders a farben markup string without appending a trailing reset sequence.
///
/// Styles applied by this call bleed into subsequent terminal output. Use when chaining
/// multiple colored segments where you want the style to carry forward. For the
/// reset-appending variant, see [`color`].
///
/// # Panics
///
/// Panics if the input is not valid farben markup. Use [`try_color`] for error handling.
#[cfg(not(feature = "compile"))]
pub fn colorb(input: impl Into<String>) -> String {
    color_runtime(input, true)
}

static CODE_STYLE_INIT: OnceLock<()> = OnceLock::new();
/// Parses and renders a farben markup string, appending a final SGR reset.
///
/// The runtime fallback used internally by [`macro@crate::color_fmt`], [`macro@crate::cprint`], and [`macro@crate::cprintln`].
/// Always a function regardless of active feature flags.
///
/// # Panics
///
/// Panics if the input contains invalid farben markup. Use [`try_color`] for error handling.
pub fn color_runtime(input: impl Into<String>, bleed: bool) -> String {
    CODE_STYLE_INIT.get_or_init(|| {
        if registry::search_registry("code").is_err() {
            let _ = registry::insert_style(
                "code",
                ansi::Style::parse("[bg:ansi(238) bright-white]").unwrap(),
            );
        }
    });
    let input = input.into();
    #[cfg(feature = "inline")]
    let input = inline::preprocess(&input);
    let mut res = parser::render_str(&input).unwrap_or_else(|e| {
        panic!(
            "{}",
            errors::LexErrorDisplay {
                error: &e,
                input: &input
            }
        );
    });
    if !bleed {
        if color_enabled() {
            res.push_str("\x1b[0m");
        }
        farben_core::clear_active_stack();
    }
    res
}

/// Parses and renders inline markdown into an ANSI-escaped string.
///
/// Processes inline markdown syntax at runtime, converting bold, italic,
/// underline, strikethrough, and inline code spans into ANSI escape sequences.
/// Always succeeds — unclosed delimiters are treated as plain text.
///
/// # Examples
///
/// ```
/// use farben::markdown;
/// let s = markdown("**bold** and *italic*");
/// ```
#[cfg(feature = "markdown")]
pub fn markdown(input: impl Into<String>) -> String {
    farben_md::renderer::render(&farben_md::lexer::tokenize(&input.into()))
}