Your first app

This is the example from the README: a list of notes with one command. It is compiled as a doc test, so it stays correct.

cargo new jot && cd jot
cargo add ashlar-rs
cargo add serde --features derive

use ashlar::prelude::*;

#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
struct Doc {
    notes: Vec<String>,
}

fn add(s: &mut Session<Doc>, p: &Value) -> Result<Value, CommandError> {
    let text = p.get("text").and_then(Value::as_str).unwrap_or("New note").to_string();
    s.edit("Add Note", |d| d.notes.push(text)); // one undo step per command
    Ok(json!(s.doc().notes.len()))
}

fn main() -> Result<(), ashlar::app::Error> {
    App::<Doc>::new("jot", env!("CARGO_PKG_VERSION"))
        .format(Format::new("example.jot", "jot 0.1"))
        .commands([cmd!("note.add", "Add Note", ["Edit"], Some("Mod+Shift+N"), [Param::string("text")], always, add)])
        .view(|ui, cx: &mut Cx<'_, Doc>| {
            for n in &cx.doc().notes {
                ui.label(n);
            }
            if ui.button("Add").clicked() {
                cx.dispatch("note.add", json!({}));
            }
        })
        .run() // undo/redo, save/open/autosave, menus, palette, crash guard, control port
}

cargo run

What each part does

The document. Doc is any type that is Clone + Default + Serialize + Deserialize + Send + Sync + 'static; such types implement Document automatically. The session keeps it as an Arc<Doc> and gives each state a Revision.

The command. add runs on the Session<Doc>. s.edit(label, f) changes the document and records one undo step named “Add Note”. The command reads its parameters from a JSON Value and returns a JSON result, which is what the CLI, the control port and MCP see.

cmd! registers it: id note.add, label “Add Note”, in the Edit menu, on Mod+Shift+N (Mod is ⌘ on macOS and Ctrl elsewhere), with one optional string parameter text, always enabled. See Commands.

Format names the file format (example.jot) and the program that writes it (jot 0.1). Without one the app gets a default format called <name>.document. Either way the app has File > New, Open, Save, Save As and Revert, and autosave with recovery. Setting a format (or a file extension) also turns on opening files dropped on the window. See Documents and undo.

The view is a closure that draws the UI each frame with egui. Cx gives it the document, and cx.dispatch runs a command after the view returns. See Views and components.

run() opens the window. It also adds:

• Undo and Redo (Mod+Z, Mod+Shift+Z), and the File and View menus.
• The command palette (Mod+Shift+P) and a keyboard shortcut editor.
• Autosave every 60 seconds and a recovery dialog after a crash.
• A crash guard: a panic in the view shows an error instead of closing the window.
• --control <port> for agents, and --headless for tests (see Testing apps).

Smaller still

The smallest app has an empty document and no commands:

use ashlar::prelude::*;

#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
struct Doc {}

fn main() -> Result<(), ashlar::app::Error> {
    let mut on = false;
    App::<Doc>::new("hello", env!("CARGO_PKG_VERSION"))
        .view(move |ui, _cx: &mut Cx<'_, Doc>| {
            ui.heading("Hello, ashlar");
            ui.checkbox(&mut on, "Switch");
        })
        .run()
}

More builder options

The full list is on docs.rs.