sim-citizen 0.1.1

Citizen support outside the SIM kernel.
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

//! Builds the read-construct `Expr` for a versioned text citizen form.

use sim_kernel::{Expr, Symbol};

/// Builds the `citizen/read-construct` [`Expr`] for a `v1` text citizen form.
///
/// Text-form citizens (pitch, chord, MIDI, and sound shapes) read-construct
/// from a single canonical string tagged with the `v1` form version. This is
/// the shared spelling of that wire form: a `citizen/read-construct` extension
/// whose payload is the vector `[class, v1, form]`.
///
/// The kernel owns `Expr` and `Symbol`; this helper only assembles them, so it
/// adds no dependency beyond the kernel.
///
/// # Examples
///
/// ```
/// # use sim_citizen::text_read_construct_expr;
/// # use sim_kernel::{Expr, Symbol};
/// let class = Symbol::qualified("pitch", "Pitch");
/// let expr = text_read_construct_expr(class.clone(), "C4");
/// assert_eq!(
///     expr,
///     Expr::Extension {
///         tag: Symbol::qualified("citizen", "read-construct"),
///         payload: Box::new(Expr::Vector(vec![
///             Expr::Symbol(class),
///             Expr::Symbol(Symbol::new("v1")),
///             Expr::String("C4".to_owned()),
///         ])),
///     }
/// );
/// ```
pub fn text_read_construct_expr(class: Symbol, form: impl Into<String>) -> Expr {
    Expr::Extension {
        tag: Symbol::qualified("citizen", "read-construct"),
        payload: Box::new(Expr::Vector(vec![
            Expr::Symbol(class),
            Expr::Symbol(Symbol::new("v1")),
            Expr::String(form.into()),
        ])),
    }
}

#[cfg(test)]
mod tests {
    use super::text_read_construct_expr;
    use sim_kernel::{Expr, Symbol};

    /// Reproduces the wire form the music shape crates hand-roll and asserts the
    /// helper matches it: class symbol, `v1` tag, string payload, in order.
    fn shape_crate_read_construct_expr(class: Symbol, form: String) -> Expr {
        Expr::Extension {
            tag: Symbol::qualified("citizen", "read-construct"),
            payload: Box::new(Expr::Vector(vec![
                Expr::Symbol(class),
                Expr::Symbol(Symbol::new("v1")),
                Expr::String(form),
            ])),
        }
    }

    #[test]
    fn text_read_construct_expr_matches_shape_crate_form() {
        let class = Symbol::qualified("pitch", "Chord");
        let expr = text_read_construct_expr(class.clone(), "C4,E4,G4");
        assert_eq!(
            expr,
            shape_crate_read_construct_expr(class, "C4,E4,G4".to_owned())
        );
    }

    #[test]
    fn text_read_construct_expr_has_class_v1_and_string_payload() {
        let class = Symbol::qualified("pitch", "Pitch");
        let expr = text_read_construct_expr(class.clone(), "C4");
        match expr {
            Expr::Extension { tag, payload } => {
                assert_eq!(tag, Symbol::qualified("citizen", "read-construct"));
                match *payload {
                    Expr::Vector(items) => {
                        assert_eq!(
                            items,
                            vec![
                                Expr::Symbol(class),
                                Expr::Symbol(Symbol::new("v1")),
                                Expr::String("C4".to_owned()),
                            ]
                        );
                    }
                    other => panic!("payload must be a vector, found {other:?}"),
                }
            }
            other => panic!("must be an extension, found {other:?}"),
        }
    }
}