ashlar-command 0.1.0

Commands: registry, typed params, one execute chokepoint, discovery
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

//! `cmd!` / `query!`: the shape of existing app command tables, so they port by search and
//! replace.

/// A mutating command:
/// `cmd!(id, label, [menu…], shortcut, params, enabled, run)`.
///
/// `params` is a legacy text doc (`r#"{"name":str}"#`) or a typed list
/// (`[Param::string("name").required()]`, built in a `const` so the table can be `static`).
/// `run` returns the host's [`crate::Host::Error`].
///
/// ```
/// use ashlar_command::{CommandError, CommandSpec, Host, Journal, Param, always, cmd};
/// struct Doc { title: String, journal: Journal }
/// impl Host for Doc {
///     type Error = CommandError;
///     fn journal(&mut self) -> &mut Journal { &mut self.journal }
/// }
/// let spec: CommandSpec<Doc> = cmd!("doc.rename", "Rename…", ["Edit"], Some("Mod+R"), [Param::string("title").required()], always, |d, p| {
///     d.title = p["title"].as_str().unwrap_or_default().to_string();
///     Ok(serde_json::Value::Null)
/// });
/// assert!(spec.mutates);
/// ```
#[macro_export]
macro_rules! cmd {
    ($id:literal, $label:literal, [$($m:literal),* $(,)?], $sc:expr, [$($p:expr),* $(,)?], $en:expr, $run:expr $(,)?) => {
        $crate::CommandSpec {
            id: $id,
            label: $label,
            menu: &[$($m),*],
            shortcut: $sc,
            params: $crate::Params::Static({
                const PARAMS: &[$crate::Param] = &[$($p),*];
                PARAMS
            }),
            enabled: $en,
            run: $run,
            mutates: true,
        }
    };
    ($id:literal, $label:literal, [$($m:literal),* $(,)?], $sc:expr, $params:literal, $en:expr, $run:expr $(,)?) => {
        $crate::CommandSpec {
            id: $id,
            label: $label,
            menu: &[$($m),*],
            shortcut: $sc,
            params: $crate::Params::Text($params),
            enabled: $en,
            run: $run,
            mutates: true,
        }
    };
}

/// A pure query (always enabled, not in menus, not journaled):
/// `query!(id, label, params, run)`.
#[macro_export]
macro_rules! query {
    ($id:literal, $label:literal, [$($p:expr),* $(,)?], $run:expr $(,)?) => {
        $crate::CommandSpec {
            id: $id,
            label: $label,
            menu: &[],
            shortcut: None,
            params: $crate::Params::Static({
                const PARAMS: &[$crate::Param] = &[$($p),*];
                PARAMS
            }),
            enabled: $crate::always,
            run: $run,
            mutates: false,
        }
    };
    ($id:literal, $label:literal, $params:literal, $run:expr $(,)?) => {
        $crate::CommandSpec {
            id: $id,
            label: $label,
            menu: &[],
            shortcut: None,
            params: $crate::Params::Text($params),
            enabled: $crate::always,
            run: $run,
            mutates: false,
        }
    };
}