blockworx/tools/

content_path.rs

//! The content path: the chain of block names from the document root down to
//! the level being drawn, as a plain string — `top/Thing 1/Core`.
//!
//! It reads along the status strip as a breadcrumb, is printed across the
//! bottom of every PDF sheet, and is parsed back by the command palette's
//! `go <path>`, so a path can be copied out of one window and pasted into
//! another to navigate there.

use crate::path::{BlockPath, Scope, child_blocks};
use blockworx_doc::{document::IndexedDocument, id::BlockId};

/// The document read a path walks: the whole document with its index, since
/// resolving a name needs each scope's children.
type Doc<'a> = IndexedDocument<'a>;

/// What separates two names in a path string.
const SEPARATOR: char = '/';
/// The same separator, for a caller measuring what it costs in a line.
pub const SEPARATOR_STR: &str = "/";

/// A block's name for path purposes: its title, or its id when untitled. The
/// navigator's richer `name/type` label would only make a path harder to read
/// and to retype.
fn name_of(document: &Doc<'_>, id: BlockId) -> String {
    document
        .doc
        .block(&id)
        .map(|block| block.title.name.trim().to_owned())
        .filter(|name| !name.is_empty())
        .unwrap_or_else(|| id.to_string())
}

/// The path's names, outermost first. Every segment is a block the path
/// descended into — the document root is the unnamed scope they hang from,
/// so it contributes nothing and the empty path (the root itself) has no
/// segments at all.
///
/// The segments rather than the joined string: the printed sheet links each
/// ancestor segment to that ancestor's page, so it needs to know where one
/// name ends and the next begins.
pub fn segments(document: &Doc<'_>, path: &BlockPath) -> Vec<String> {
    path.segments()
        .iter()
        .map(|&id| name_of(document, id))
        .collect()
}

/// The path as a string, outermost first: `top/Thing 1/Core`.
pub fn to_string(document: &Doc<'_>, path: &BlockPath) -> String {
    join(&segments(document, path))
}

/// The one spelling of a path: its names, separated.
pub fn join(segments: &[String]) -> String {
    segments.join(&SEPARATOR.to_string())
}

/// Resolve a path string back to a [`BlockPath`], matching names down the tree
/// from the document root. Names match case-insensitively after trimming, and
/// the first sibling that matches wins. `None` if any name names nothing.
pub fn parse(document: &Doc<'_>, text: &str) -> Option<BlockPath> {
    let names = text
        .split(SEPARATOR)
        .map(str::trim)
        .filter(|name| !name.is_empty());
    let mut path = BlockPath::empty();
    let mut current = Scope::Root;
    for name in names {
        let child = child_blocks(document, current)
            .into_iter()
            .find(|&id| name_of(document, id).eq_ignore_ascii_case(name))?;
        path.push(child);
        current = Scope::Block(child);
    }
    Some(path)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::widget::test_fixtures::{self as fx, Scene};
    use blockworx_doc::fixtures::block_id;
    use blockworx_geom::{Rect, pos2};

    fn body() -> Rect {
        Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 60.0))
    }

    /// `top → Thing 1 → Core`, returning the ids in path order.
    fn nested() -> (Scene, Vec<BlockId>) {
        let scene = Scene::new(vec![
            fx::block_in(1, Scope::Root, body()),
            fx::titled(1, "top"),
            fx::block_in(2, Scope::Block(block_id(1)), body()),
            fx::titled(2, "Thing 1"),
            fx::block_in(3, Scope::Block(block_id(2)), body()),
            fx::titled(3, "Core"),
        ]);
        (scene, vec![block_id(1), block_id(2), block_id(3)])
    }

    fn path_of(ids: &[BlockId]) -> BlockPath {
        let mut path = BlockPath::empty();
        for &id in ids {
            path.push(id);
        }
        path
    }

    #[test]
    fn a_path_reads_as_names_from_the_root_down() {
        let (mut scene, ids) = nested();
        let indexed = scene.indexed();
        assert_eq!(to_string(&indexed, &path_of(&ids)), "top/Thing 1/Core");
        assert_eq!(
            to_string(&indexed, &BlockPath::empty()),
            "",
            "the document root is the unnamed scope the path hangs from"
        );
    }

    /// An untitled block still names a level: its id stands in, so the string
    /// never has an empty segment to parse back.
    #[test]
    fn an_untitled_block_falls_back_to_its_id() {
        let id = block_id(1);
        let mut scene = Scene::new(vec![
            fx::block_in(1, Scope::Root, body()),
            fx::titled(1, ""),
        ]);
        let indexed = scene.indexed();
        let text = to_string(&indexed, &path_of(&[id]));
        assert_eq!(text, id.to_string());
        assert_eq!(parse(&indexed, &text), Some(path_of(&[id])));
    }

    /// What the display shows round-trips back to the path it came from —
    /// the whole point of copying the string out.
    #[test]
    fn a_displayed_path_parses_back_to_itself() {
        let (mut scene, ids) = nested();
        let indexed = scene.indexed();
        let path = path_of(&ids);
        assert_eq!(
            parse(&indexed, &to_string(&indexed, &path)),
            Some(path.clone())
        );
        // Spacing and case are forgiven.
        assert_eq!(parse(&indexed, " top / thing 1 / core "), Some(path));
        assert_eq!(parse(&indexed, "top"), Some(path_of(&ids[..1])));
    }

    /// The document root names no level, so it contributes no segments for a
    /// breadcrumb — or a printed sheet — to draw a line from.
    #[test]
    fn the_root_contributes_no_segments() {
        let (mut scene, _) = nested();
        let indexed = scene.indexed();
        assert!(segments(&indexed, &BlockPath::empty()).is_empty());
    }

    #[test]
    fn a_name_that_names_nothing_fails_to_parse() {
        let (mut scene, _) = nested();
        let indexed = scene.indexed();
        assert_eq!(parse(&indexed, "top/Thing 1/Nope"), None);
        assert_eq!(
            parse(&indexed, "Core"),
            None,
            "names resolve level by level"
        );
    }
}