rich/

box.rs

//! Box-drawing character sets.
//!
//! Port of upstream `rich/box.py`. A [`Box`] is parsed from an 8-line template
//! (exactly as upstream), giving named access to every corner, edge, and
//! junction. Panels, rules, and (later) tables draw their borders from these.
//!
//! All of upstream's built-in boxes are provided, along with [`Box::substitute`]
//! — the platform-dependent fallback applied on legacy Windows consoles (fancy
//! boxes → `SQUARE`) and non-UTF-8 terminals (→ `ASCII`).

/// Which divider a [`Box::get_row`] draws.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RowLevel {
    /// Separator below the header (`head_row_*`).
    Head,
    /// Separator between body rows (`row_*`).
    Row,
    /// Separator above the footer (`foot_row_*`).
    Foot,
    /// A blank row between body rows: `mid_left`, spaces, `mid_vertical`,
    /// `mid_right` (upstream's `level="mid"`, drawn by `Table(leading=…)`).
    Mid,
}

/// A set of box-drawing characters. Mirrors `rich.box.Box`.
///
/// The field names match upstream's 8×4 grid:
/// ```text
/// top_left    top              top_divider     top_right
/// head_left   (space)          head_vertical   head_right
/// head_row_left head_row_horizontal head_row_cross head_row_right
/// mid_left    (space)          mid_vertical    mid_right
/// row_left    row_horizontal   row_cross       row_right
/// foot_row_left foot_row_horizontal foot_row_cross foot_row_right
/// foot_left   (space)          foot_vertical   foot_right
/// bottom_left bottom           bottom_divider  bottom_right
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Box {
    pub top_left: char,
    pub top: char,
    pub top_divider: char,
    pub top_right: char,

    pub head_left: char,
    pub head_vertical: char,
    pub head_right: char,

    pub head_row_left: char,
    pub head_row_horizontal: char,
    pub head_row_cross: char,
    pub head_row_right: char,

    pub mid_left: char,
    pub mid_vertical: char,
    pub mid_right: char,

    pub row_left: char,
    pub row_horizontal: char,
    pub row_cross: char,
    pub row_right: char,

    pub foot_row_left: char,
    pub foot_row_horizontal: char,
    pub foot_row_cross: char,
    pub foot_row_right: char,

    pub foot_left: char,
    pub foot_vertical: char,
    pub foot_right: char,

    pub bottom_left: char,
    pub bottom: char,
    pub bottom_divider: char,
    pub bottom_right: char,
}

impl Box {
    /// Parse a box from the 8-line, 4-column template (as upstream does).
    ///
    /// Panics at const-eval time if the template is malformed, so the built-in
    /// constants are validated when the crate compiles.
    const fn parse(template: &str) -> Box {
        let rows = split_rows(template);
        Box {
            top_left: rows[0][0],
            top: rows[0][1],
            top_divider: rows[0][2],
            top_right: rows[0][3],

            head_left: rows[1][0],
            head_vertical: rows[1][2],
            head_right: rows[1][3],

            head_row_left: rows[2][0],
            head_row_horizontal: rows[2][1],
            head_row_cross: rows[2][2],
            head_row_right: rows[2][3],

            mid_left: rows[3][0],
            mid_vertical: rows[3][2],
            mid_right: rows[3][3],

            row_left: rows[4][0],
            row_horizontal: rows[4][1],
            row_cross: rows[4][2],
            row_right: rows[4][3],

            foot_row_left: rows[5][0],
            foot_row_horizontal: rows[5][1],
            foot_row_cross: rows[5][2],
            foot_row_right: rows[5][3],

            foot_left: rows[6][0],
            foot_vertical: rows[6][2],
            foot_right: rows[6][3],

            bottom_left: rows[7][0],
            bottom: rows[7][1],
            bottom_divider: rows[7][2],
            bottom_right: rows[7][3],
        }
    }

    /// The top border for the given column `widths`. Port of `Box.get_top`.
    /// `edge` controls whether the left/right corner glyphs are drawn.
    pub fn get_top(&self, widths: &[usize], edge: bool) -> String {
        let mut parts = String::new();
        if edge {
            parts.push(self.top_left);
        }
        let last = widths.len().saturating_sub(1);
        for (index, &width) in widths.iter().enumerate() {
            for _ in 0..width {
                parts.push(self.top);
            }
            if index != last {
                parts.push(self.top_divider);
            }
        }
        if edge {
            parts.push(self.top_right);
        }
        parts
    }

    /// A horizontal divider row between columns at a given `level`. Port of
    /// `Box.get_row`. `edge` controls whether the left/right glyphs are drawn.
    pub fn get_row(&self, widths: &[usize], level: RowLevel, edge: bool) -> String {
        let (left, horizontal, cross, right) = match level {
            RowLevel::Head => (
                self.head_row_left,
                self.head_row_horizontal,
                self.head_row_cross,
                self.head_row_right,
            ),
            RowLevel::Row => (
                self.row_left,
                self.row_horizontal,
                self.row_cross,
                self.row_right,
            ),
            RowLevel::Foot => (
                self.foot_row_left,
                self.foot_row_horizontal,
                self.foot_row_cross,
                self.foot_row_right,
            ),
            RowLevel::Mid => (self.mid_left, ' ', self.mid_vertical, self.mid_right),
        };
        let mut parts = String::new();
        if edge {
            parts.push(left);
        }
        let last = widths.len().saturating_sub(1);
        for (index, &width) in widths.iter().enumerate() {
            for _ in 0..width {
                parts.push(horizontal);
            }
            if index != last {
                parts.push(cross);
            }
        }
        if edge {
            parts.push(right);
        }
        parts
    }

    /// Return a version of this box safe for the target terminal. Port of
    /// `Box.substitute`.
    ///
    /// On a legacy Windows console (`legacy_windows` + `safe`), the fancy boxes
    /// that legacy code pages can't draw — `ROUNDED`, `HEAVY`, `HEAVY_HEAD` —
    /// fall back to `SQUARE` (`DOUBLE`/`SQUARE`/`MINIMAL` are kept). On a
    /// non-UTF-8 terminal (`ascii_only`), any non-ASCII box becomes `ASCII`.
    pub fn substitute(&self, legacy_windows: bool, safe: bool, ascii_only: bool) -> Box {
        let mut result = *self;
        if legacy_windows && safe && (result == ROUNDED || result == HEAVY || result == HEAVY_HEAD)
        {
            result = SQUARE;
        }
        if ascii_only && !result.is_ascii() {
            result = ASCII;
        }
        result
    }

    /// Whether every glyph is ASCII. Upstream passes `ascii=True` to exactly
    /// the built-in boxes drawn in ASCII (`ASCII`, `ASCII2`,
    /// `ASCII_DOUBLE_HEAD`, `MARKDOWN`), which `substitute` keeps on an
    /// ASCII-only terminal.
    pub fn is_ascii(&self) -> bool {
        [
            self.top_left,
            self.top,
            self.top_divider,
            self.top_right,
            self.head_left,
            self.head_vertical,
            self.head_right,
            self.head_row_left,
            self.head_row_horizontal,
            self.head_row_cross,
            self.head_row_right,
            self.mid_left,
            self.mid_vertical,
            self.mid_right,
            self.row_left,
            self.row_horizontal,
            self.row_cross,
            self.row_right,
            self.foot_row_left,
            self.foot_row_horizontal,
            self.foot_row_cross,
            self.foot_row_right,
            self.foot_left,
            self.foot_vertical,
            self.foot_right,
            self.bottom_left,
            self.bottom,
            self.bottom_divider,
            self.bottom_right,
        ]
        .iter()
        .all(char::is_ascii)
    }

    /// If this box draws its header border with special characters, the most
    /// similar box that does not; otherwise the box itself. Port of
    /// `Box.get_plain_headed_box`: a table without a header draws with it.
    pub fn get_plain_headed_box(&self) -> Box {
        match *self {
            b if b == HEAVY_HEAD || b == SQUARE_DOUBLE_HEAD => SQUARE,
            b if b == MINIMAL_DOUBLE_HEAD || b == MINIMAL_HEAVY_HEAD => MINIMAL,
            b if b == ASCII_DOUBLE_HEAD => ASCII2,
            other => other,
        }
    }

    /// The bottom border for the given column `widths`. Port of `Box.get_bottom`.
    /// `edge` controls whether the left/right corner glyphs are drawn.
    pub fn get_bottom(&self, widths: &[usize], edge: bool) -> String {
        let mut parts = String::new();
        if edge {
            parts.push(self.bottom_left);
        }
        let last = widths.len().saturating_sub(1);
        for (index, &width) in widths.iter().enumerate() {
            for _ in 0..width {
                parts.push(self.bottom);
            }
            if index != last {
                parts.push(self.bottom_divider);
            }
        }
        if edge {
            parts.push(self.bottom_right);
        }
        parts
    }
}

/// Split an 8-line template into an `[8][4]` grid of chars (const-eval helper).
const fn split_rows(template: &str) -> [[char; 4]; 8] {
    let bytes = template.as_bytes();
    let mut rows = [[' '; 4]; 8];
    // We iterate chars manually because box glyphs are multi-byte UTF-8 and the
    // template has a fixed shape: 4 columns per line, newline-separated.
    let mut i = 0usize; // byte index
    let mut row = 0usize;
    let mut col = 0usize;
    while i < bytes.len() {
        let (ch, width) = next_char(bytes, i);
        if ch == '\n' {
            row += 1;
            col = 0;
            i += width;
            continue;
        }
        if row < 8 && col < 4 {
            rows[row][col] = ch;
        }
        col += 1;
        i += width;
    }
    rows
}

/// Decode one UTF-8 char starting at `bytes[i]`, returning it and its byte len.
/// A small const-fn UTF-8 decoder (std's `chars()` isn't const).
const fn next_char(bytes: &[u8], i: usize) -> (char, usize) {
    let b0 = bytes[i];
    if b0 < 0x80 {
        (b0 as char, 1)
    } else if b0 >> 5 == 0b110 {
        let cp = ((b0 as u32 & 0x1f) << 6) | (bytes[i + 1] as u32 & 0x3f);
        (char_from_u32(cp), 2)
    } else if b0 >> 4 == 0b1110 {
        let cp = ((b0 as u32 & 0x0f) << 12)
            | ((bytes[i + 1] as u32 & 0x3f) << 6)
            | (bytes[i + 2] as u32 & 0x3f);
        (char_from_u32(cp), 3)
    } else {
        let cp = ((b0 as u32 & 0x07) << 18)
            | ((bytes[i + 1] as u32 & 0x3f) << 12)
            | ((bytes[i + 2] as u32 & 0x3f) << 6)
            | (bytes[i + 3] as u32 & 0x3f);
        (char_from_u32(cp), 4)
    }
}

const fn char_from_u32(cp: u32) -> char {
    match char::from_u32(cp) {
        Some(c) => c,
        None => '\u{fffd}',
    }
}

// ── Built-in boxes (subset of upstream `rich/box.py`) ──

pub const ASCII: Box = Box::parse("+--+\n| ||\n|-+|\n| ||\n|-+|\n|-+|\n| ||\n+--+\n");

pub const SQUARE: Box = Box::parse("┌─┬┐\n│ ││\n├─┼┤\n│ ││\n├─┼┤\n├─┼┤\n│ ││\n└─┴┘\n");

pub const ROUNDED: Box = Box::parse("╭─┬╮\n│ ││\n├─┼┤\n│ ││\n├─┼┤\n├─┼┤\n│ ││\n╰─┴╯\n");

pub const HEAVY: Box = Box::parse("┏━┳┓\n┃ ┃┃\n┣━╋┫\n┃ ┃┃\n┣━╋┫\n┣━╋┫\n┃ ┃┃\n┗━┻┛\n");

/// The default `Table` box: heavy top border + head separator, light body.
pub const HEAVY_HEAD: Box = Box::parse("┏━┳┓\n┃ ┃┃\n┡━╇┩\n│ ││\n├─┼┤\n├─┼┤\n│ ││\n└─┴┘\n");

pub const DOUBLE: Box = Box::parse("╔═╦╗\n║ ║║\n╠═╬╣\n║ ║║\n╠═╬╣\n╠═╬╣\n║ ║║\n╚═╩╝\n");

pub const MINIMAL: Box = Box::parse("  ╷ \n  │ \n╶─┼╴\n  │ \n╶─┼╴\n╶─┼╴\n  │ \n  ╵ \n");

pub const ASCII2: Box = Box::parse("+-++\n| ||\n+-++\n| ||\n+-++\n+-++\n| ||\n+-++\n");

pub const ASCII_DOUBLE_HEAD: Box = Box::parse("+-++\n| ||\n+=++\n| ||\n+-++\n+-++\n| ||\n+-++\n");

pub const SQUARE_DOUBLE_HEAD: Box = Box::parse("┌─┬┐\n│ ││\n╞═╪╡\n│ ││\n├─┼┤\n├─┼┤\n│ ││\n└─┴┘\n");

pub const MINIMAL_HEAVY_HEAD: Box = Box::parse("  ╷ \n  │ \n╺━┿╸\n  │ \n╶─┼╴\n╶─┼╴\n  │ \n  ╵ \n");

pub const MINIMAL_DOUBLE_HEAD: Box = Box::parse("  ╷ \n  │ \n ═╪ \n  │ \n ─┼ \n ─┼ \n  │ \n  ╵ \n");

/// A fully blank box (all spaces): no visible borders, though its border
/// lines still take up rows. Not in upstream, which uses `box=None` for a
/// table without borders.
pub const NONE: Box = Box::parse("    \n    \n    \n    \n    \n    \n    \n    \n");

/// A boxless table with a light head/foot rule. Used by Markdown tables.
pub const SIMPLE: Box = Box::parse("    \n    \n ── \n    \n    \n ── \n    \n    \n");

pub const SIMPLE_HEAD: Box = Box::parse("    \n    \n ── \n    \n    \n    \n    \n    \n");

pub const SIMPLE_HEAVY: Box = Box::parse("    \n    \n ━━ \n    \n    \n ━━ \n    \n    \n");

pub const HORIZONTALS: Box = Box::parse(" ── \n    \n ── \n    \n ── \n ── \n    \n ── \n");

pub const HEAVY_EDGE: Box = Box::parse("┏━┯┓\n┃ │┃\n┠─┼┨\n┃ │┃\n┠─┼┨\n┠─┼┨\n┃ │┃\n┗━┷┛\n");

pub const DOUBLE_EDGE: Box = Box::parse("╔═╤╗\n║ │║\n╟─┼╢\n║ │║\n╟─┼╢\n╟─┼╢\n║ │║\n╚═╧╝\n");

/// The box Markdown tables use for GFM output (pipes + a light head rule).
pub const MARKDOWN: Box = Box::parse("    \n| ||\n|-||\n| ||\n|-||\n|-||\n| ||\n    \n");

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

    #[test]
    fn rounded_corners() {
        assert_eq!(ROUNDED.top_left, '╭');
        assert_eq!(ROUNDED.top_right, '╮');
        assert_eq!(ROUNDED.bottom_left, '╰');
        assert_eq!(ROUNDED.bottom_right, '╯');
        assert_eq!(ROUNDED.top, '─');
        assert_eq!(ROUNDED.mid_left, '│');
        assert_eq!(ROUNDED.mid_right, '│');
    }

    #[test]
    fn square_and_ascii() {
        assert_eq!(SQUARE.top_left, '┌');
        assert_eq!(ASCII.top_left, '+');
        assert_eq!(ASCII.top, '-');
        assert_eq!(ASCII.mid_left, '|');
    }

    #[test]
    fn get_top_and_bottom_single_column() {
        assert_eq!(ROUNDED.get_top(&[3], true), "╭───╮");
        assert_eq!(ROUNDED.get_bottom(&[3], true), "╰───╯");
        // Without edges, the corners are omitted.
        assert_eq!(ROUNDED.get_top(&[3], false), "───");
        assert_eq!(SQUARE.get_row(&[2, 2], RowLevel::Head, false), "──┼──");
    }

    #[test]
    fn additional_boxes_parse() {
        // SIMPLE / MARKDOWN have blank edges and a head rule.
        assert_eq!(SIMPLE.top_left, ' ');
        assert_eq!(SIMPLE.head_row_horizontal, '─');
        assert_eq!(SIMPLE_HEAVY.head_row_horizontal, '━');
        assert_eq!(MARKDOWN.mid_left, '|');
        assert_eq!(MARKDOWN.head_row_horizontal, '-');
        assert_eq!(DOUBLE_EDGE.top_left, '╔');
        assert_eq!(DOUBLE_EDGE.mid_vertical, '│');
        assert_eq!(HEAVY_EDGE.top_left, '┏');
        assert_eq!(SQUARE_DOUBLE_HEAD.head_row_horizontal, '═');
        assert_eq!(ASCII2.head_row_cross, '+');
    }

    #[test]
    fn plain_headed_boxes() {
        assert_eq!(HEAVY_HEAD.get_plain_headed_box(), SQUARE);
        assert_eq!(SQUARE_DOUBLE_HEAD.get_plain_headed_box(), SQUARE);
        assert_eq!(MINIMAL_DOUBLE_HEAD.get_plain_headed_box(), MINIMAL);
        assert_eq!(MINIMAL_HEAVY_HEAD.get_plain_headed_box(), MINIMAL);
        assert_eq!(ASCII_DOUBLE_HEAD.get_plain_headed_box(), ASCII2);
        assert_eq!(ROUNDED.get_plain_headed_box(), ROUNDED);
    }

    #[test]
    fn substitute_legacy_and_ascii() {
        // Legacy Windows: fancy → SQUARE; DOUBLE/SQUARE kept.
        assert_eq!(ROUNDED.substitute(true, true, false), SQUARE);
        assert_eq!(HEAVY.substitute(true, true, false), SQUARE);
        assert_eq!(HEAVY_HEAD.substitute(true, true, false), SQUARE);
        assert_eq!(DOUBLE.substitute(true, true, false), DOUBLE);
        assert_eq!(SQUARE.substitute(true, true, false), SQUARE);
        // `safe=false` disables the legacy fallback.
        assert_eq!(ROUNDED.substitute(true, false, false), ROUNDED);
        // Non-UTF-8: anything non-ASCII → ASCII.
        assert_eq!(ROUNDED.substitute(false, true, true), ASCII);
        assert_eq!(DOUBLE.substitute(false, true, true), ASCII);
        assert_eq!(ASCII.substitute(false, true, true), ASCII);
        // No flags → unchanged.
        assert_eq!(ROUNDED.substitute(false, true, false), ROUNDED);
    }
}