pixbar 0.2.0

Sub-cell-precision two-value progress bar for narrow terminal widths (Unicode 1/8 block, no font patching required).
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
113

//! Cell-IR → ANSI string serializer with run-length-merged SGR sequences.
//!
//! Adjacent cells that share fg/bg do not re-emit `\x1b[…m`. Empty cells
//! emit only a space (no SGR) so the terminal's native background shows
//! through trailing whitespace. The output always ends with a final
//! `\x1b[0m` reset when any color was written.

use crate::{render::{Cell, CellKind}, glyphs::glyph_for, Capability, Rgb, Theme};

/// Serialize a [`Cell`] sequence to an ANSI truecolor string.
///
/// `theme` provides the three layer colors; `cap` selects the glyph table.
/// The returned string contains `ESC[38;2;…m` / `ESC[48;2;…m` SGR escapes
/// with same-color runs deduplicated and a trailing `ESC[0m` reset.
pub fn encode(cells: &[Cell], theme: &Theme, cap: Capability) -> String {
    let mut out = String::with_capacity(cells.len() * 24);
    let mut last_fg: Option<Rgb> = None;
    let mut last_bg: Option<Rgb> = None;

    for c in cells {
        let (fg, bg, empty) = layer_colors(c.kind, theme);
        if empty {
            if last_fg.is_some() || last_bg.is_some() {
                out.push_str("\x1b[0m");
                last_fg = None;
                last_bg = None;
            }
            out.push(' ');
            continue;
        }
        if last_fg != Some(fg) {
            out.push_str(&format!("\x1b[38;2;{};{};{}m", fg.0, fg.1, fg.2));
            last_fg = Some(fg);
        }
        match bg {
            Some(b) if last_bg != Some(b) => {
                out.push_str(&format!("\x1b[48;2;{};{};{}m", b.0, b.1, b.2));
                last_bg = Some(b);
            }
            None if last_bg.is_some() => {
                out.push_str("\x1b[49m");
                last_bg = None;
            }
            _ => {}
        }
        out.push(glyph_for(c.kind, c.sub_fill, cap));
    }
    if last_fg.is_some() || last_bg.is_some() {
        out.push_str("\x1b[0m");
    }
    out
}

/// Serialize a [`Cell`] sequence to a colorless glyph-only string.
///
/// Emits one glyph per cell with no SGR escapes — suitable for `NO_COLOR`
/// environments, log files, pipelines that don't understand ANSI, or any
/// consumer that wants to apply its own styling. Boundary cells lose
/// their bg-paint slice (see the
/// [boundary-cells note on `CellKind`](crate::render::CellKind#boundary-cells-expect-a-per-cell-background-paint)).
pub fn encode_plain(cells: &[Cell], cap: Capability) -> String {
    let mut out = String::with_capacity(cells.len());
    for c in cells {
        out.push(crate::glyphs::glyph_for(c.kind, c.sub_fill, cap));
    }
    out
}

/// Returns (fg, optional bg, is_empty_cell).
fn layer_colors(kind: CellKind, theme: &Theme) -> (Rgb, Option<Rgb>, bool) {
    match kind {
        CellKind::Empty                                       => (theme.primary,   None,                   true),
        CellKind::PrimaryFull                                 => (theme.primary,   None,                   false),
        CellKind::SecondaryFull                               => (theme.secondary, None,                   false),
        CellKind::OverflowFull                                => (theme.overflow,  None,                   false),
        CellKind::PrimaryBoundary | CellKind::DegradedOverlap => (theme.primary,   Some(theme.secondary),  false),
        CellKind::SecondaryBoundary                           => (theme.secondary, None,                   false),
        CellKind::OverflowInnerBoundary                       => (theme.primary,   Some(theme.overflow),   false),
        CellKind::OverflowOuterBoundary                       => (theme.overflow,  None,                   false),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test] fn empty_cells_emit_spaces_only() {
        let cells = vec![Cell { kind: CellKind::Empty, sub_fill: 0 }; 3];
        assert_eq!(encode(&cells, &Theme::default(), Capability::EighthBlock), "   ");
    }

    #[test] fn encode_plain_emits_glyphs_no_escapes() {
        let cells = vec![
            Cell { kind: CellKind::PrimaryFull,    sub_fill: 0 },
            Cell { kind: CellKind::PrimaryBoundary, sub_fill: 4 },
            Cell { kind: CellKind::Empty,          sub_fill: 0 },
        ];
        let out = encode_plain(&cells, Capability::EighthBlock);
        assert_eq!(out, "█▌ ");
        assert!(!out.contains('\x1b'));
    }

    #[test] fn rle_does_not_resend_same_fg() {
        let cells = vec![
            Cell { kind: CellKind::PrimaryFull, sub_fill: 0 },
            Cell { kind: CellKind::PrimaryFull, sub_fill: 0 },
        ];
        let out = encode(&cells, &Theme::default(), Capability::EighthBlock);
        // Exactly one SGR fg + glyphs + reset.
        assert_eq!(out.matches("\x1b[38;2;").count(), 1);
        assert!(out.ends_with("██\x1b[0m"));
    }
}