Struct Session 

pub struct Session<D: Document> { /* private fields */ }

The state commands run on: the document Store, the file it came from, view state and the effects commands ask of the window. Commands are fn(&mut Session<D>, &Value).

Implementations

impl<D: Document> Session<D>

pub fn new(format: Arc<Format<D>>) -> Session<D>

A session with a new, empty document.

pub fn is_windowed(&self) -> bool

Whether a window can show dialogs (false in CLI / MCP sessions).

pub fn doc(&self) -> &D

The current document (inside a command: its working copy).

pub fn snapshot(&self) -> Arc<D>

The current document as an Arc (for a job or another thread).

pub fn store(&self) -> &Store<D>

The store (history, revision, dirty state). Changing it directly from inside a command drops the command’s own edits; use Session::edit there.

pub fn store_mut(&mut self) -> &mut Store<D>

pub fn revision(&self) -> Revision

pub fn is_dirty(&self) -> bool

pub fn format(&self) -> &Format<D>

pub fn edit<R>(&mut self, label: &str, f: impl FnOnce(&mut D) -> R) -> R

Change the document. Inside a command the change joins the command’s single undo step; outside (a view, a job’s apply) it is a step of its own called label.

pub fn edit_merged<R>( &mut self, label: &str, merge_key: &str, f: impl FnOnce(&mut D) -> R, ) -> R

Session::edit that folds into the previous step with the same label and merge key (one undo step for a whole drag).

pub fn try_edit<R, E>( &mut self, label: &str, f: impl FnOnce(&mut D) -> Result<R, E>, ) -> Result<R, E>

A change that may fail: on error nothing changes.

pub fn can_undo(&self) -> bool

pub fn can_redo(&self) -> bool

pub fn undo(&mut self) -> Option<String>

Undo the last step; returns its label.

pub fn redo(&mut self) -> Option<String>

Redo the next step; returns its label.

pub fn path(&self) -> Option<&Path>

The file the document was opened from or saved to.

pub fn display_name(&self) -> String

The document’s display name: the file name, or “Untitled”.

pub fn migrated_from(&self) -> Option<u64>

The schema version the open file had before it was upgraded on load, if it was.

pub fn file_generation(&self) -> u64

Changes when the file (path) changes; with the revision it keys caches of file state.

pub fn new_document(&mut self)

Start a new, empty document.

pub fn open(&mut self, path: &Path) -> Result<(), FormatError>

Open path (migrating older files). On error the current document stays.

pub fn replace( &mut self, doc: D, path: Option<PathBuf>, migrated_from: Option<u64>, )

Replace the document with doc as if opened from path: clears the history, clean.

pub fn replace_as_edit(&mut self, label: &str, doc: D)

Replace the document with doc as an undoable, unsaved change (recovered work, an import).

pub fn save(&mut self) -> Result<PathBuf, FormatError>

Save to the current file. Errors when the document has never been saved.

pub fn save_as(&mut self, path: &Path) -> Result<(), FormatError>

Save to path and make it the document’s file.

pub fn view_state(&self) -> &Map<String, Value>

App-defined view state (ui.set merges into it; it is not part of the document).

pub fn view<T: DeserializeOwned>(&self, key: &str) -> Option<T>

pub fn view_or<T: DeserializeOwned>(&self, key: &str, default: T) -> T

pub fn set_view<T: Serialize + ?Sized>(&mut self, key: &str, value: &T)

pub fn set_view_value(&mut self, key: &str, value: Value)

pub fn view_generation(&self) -> u64

Changes whenever the view state changes.

pub fn request(&mut self, effect: Effect)

Ask the window for something (ignored headless).

pub fn toast(&mut self, level: ToastLevel, text: impl Into<String>)

Show a message (headless: logged).

Trait Implementations

impl<D: Document> Host for Session<D>

type Error = CommandError

The error type command bodies return. CommandError itself, or the app’s own error with From<AppError> for CommandError (leave the id empty: the chokepoint fills it in).

fn journal(&mut self) -> &mut Journal

The execution state: nesting depth and journal.

fn before( &mut self, _spec: &CommandSpec<Self>, _params: &mut Value, depth: usize, ) -> Result<(), CommandError>

Rewrite params before validation (resolve names to ids, settle an ongoing gesture…). An Err refuses the call: Host::rejected sees it converted, and Registry::execute_host hands it back unchanged as ExecError::Host.

fn after( &mut self, spec: &CommandSpec<Self>, _params: &Value, result: &Result<Value, CommandError>, depth: usize, )

Called after every run (ok, error or panic), at every nesting depth.

fn rejected(&mut self, id: &str, error: &CommandError, depth: usize)

Called when a call is refused before running: unknown command, bad params, disabled, too deeply nested, or an error from Host::before.

fn validate( &mut self, _spec: &CommandSpec<Self>, _params: &Value, _depth: usize, ) -> Result<(), CommandError>

Extra parameter checks after the registry’s Validation policy and before Host::enabled_for (an Err is refused and goes to Host::rejected). With Validation::Off this is where a host validates when it wants to, e.g. only at depth 0 or only for agent calls. Default: nothing.

fn enabled_for( &mut self, spec: &CommandSpec<Self>, _params: &Value, ) -> Result<(), String>

Enabled check for one call; override when explicit targets in params change availability (the state may be adjusted temporarily, e.g. targets swapped in for the selection).

fn scrub(&self, _id: &str, _params: &mut Value)

Remove secrets from params before they reach the journal.