Struct DocumentSession 

pub struct DocumentSession { /* private fields */ }

One open prov document: a metadata editor and a body editor over the same file, reconciled on save.

Implementations

impl DocumentSession

pub fn open(path: impl Into<PathBuf>) -> Result<Self, SessionError>

Open a prov document from disk, parsing the body in the grammar its extension declares, with no schema.

pub fn open_with_schema( path: impl Into<PathBuf>, schema: Schema, ) -> Result<Self, SessionError>

Open a prov document from disk carrying the workspace schema.

pub fn open_managed( path: impl Into<PathBuf>, schema: Option<Schema>, derived: Vec<String>, ) -> Result<Self, SessionError>

Open a prov document declaring the keys the workspace maintains, so the metadata model draws their rows and declines every edit to them.

derived is Facets::managed_key_names — id, content_hash, and whatever the workspace named as its updated stamp. It is a separate entry point rather than something open_with_schema does for you because declining an edit is a policy, and a repair tool that means to rewrite a stale id is as legitimate a frontend as an editor that must not. This crate hands over the list and lets the frontend decide (see crate::facets); most editors want it, and this is the one line that says so.

The set has to arrive here rather than being applied afterwards: flower takes it before it builds its first row list.

Examples found in repository

examples/inspect.rs (line 20)

fn main() {
    let path = std::path::PathBuf::from(std::env::args().nth(1).expect("a document"));
    let view = WorkspaceView::discover(&path).expect("discovery");
    match &view {
        Some(v) => println!("workspace: {}", v.root_dir().display()),
        None => println!("workspace: none"),
    }
    let facets = view
        .as_ref()
        .map(|v| v.facets().clone())
        .unwrap_or_default();
    let schema = view.as_ref().map(|v| v.schema_for(&path));
    let session =
        DocumentSession::open_managed(&path, schema, facets.managed_key_names()).expect("open");

    println!("\nkeys:");
    for (key, facet) in facets.classify(session.meta()) {
        let flags = [
            facet.structural().then_some("structural"),
            facet.managed().then_some("managed"),
        ]
        .into_iter()
        .flatten()
        .collect::<Vec<_>>()
        .join(",");
        println!("  {key:<14} {:<9} {flags}", facet.kind());
    }

    println!("\nlinks:");
    for link in links_in(session.meta(), &facets) {
        let landing = match &view {
            Some(v) => v.resolve(&path, &link),
            None => resolve_without_workspace(&path, &link),
        };
        let mark = if matches!(landing, Destination::Document { exists: true, .. }) {
            "→"
        } else {
            "·"
        };
        println!(
            "  {mark} {:<10} {:<22} {}",
            link.relation.name,
            link.display(),
            landing.describe()
        );
    }
}

pub fn open_with( path: impl Into<PathBuf>, body_format: BodyFormat, schema: Option<Schema>, ) -> Result<Self, SessionError>

Open a prov document from disk, parsing the body as body_format, with an optional workspace schema.

pub fn from_text( path: impl Into<PathBuf>, text: &str, body_format: BodyFormat, schema: Option<Schema>, ) -> Result<Self, SessionError>

Build a session from in-memory text. The path still drives prov’s carrier/format detection (extension for a config doc, content sniffing for a fenced block). schema governs the metadata model when present.

pub fn path(&self) -> &Path

pub fn has_body(&self) -> bool

Whether the document has an editable prose body.

pub fn metadata(&self) -> &Model<ProvBackend>

The metadata editor (its rows are what a metadata pane renders).

pub fn metadata_mut(&mut self) -> &mut Model<ProvBackend>

pub fn meta(&self) -> &Value

The metadata value tree — what crate::links and crate::facets ask their questions of.

The model’s own copy, not a reparse: it is rebuilt on every edit, so this is current and free.

Examples found in repository

examples/inspect.rs (line 23)

fn main() {
    let path = std::path::PathBuf::from(std::env::args().nth(1).expect("a document"));
    let view = WorkspaceView::discover(&path).expect("discovery");
    match &view {
        Some(v) => println!("workspace: {}", v.root_dir().display()),
        None => println!("workspace: none"),
    }
    let facets = view
        .as_ref()
        .map(|v| v.facets().clone())
        .unwrap_or_default();
    let schema = view.as_ref().map(|v| v.schema_for(&path));
    let session =
        DocumentSession::open_managed(&path, schema, facets.managed_key_names()).expect("open");

    println!("\nkeys:");
    for (key, facet) in facets.classify(session.meta()) {
        let flags = [
            facet.structural().then_some("structural"),
            facet.managed().then_some("managed"),
        ]
        .into_iter()
        .flatten()
        .collect::<Vec<_>>()
        .join(",");
        println!("  {key:<14} {:<9} {flags}", facet.kind());
    }

    println!("\nlinks:");
    for link in links_in(session.meta(), &facets) {
        let landing = match &view {
            Some(v) => v.resolve(&path, &link),
            None => resolve_without_workspace(&path, &link),
        };
        let mark = if matches!(landing, Destination::Document { exists: true, .. }) {
            "→"
        } else {
            "·"
        };
        println!(
            "  {mark} {:<10} {:<22} {}",
            link.relation.name,
            link.display(),
            landing.describe()
        );
    }
}

pub fn cursor_path(&self) -> Option<Vec<Seg>>

The metadata path the cursor is on, whichever projection the model is showing.

flower has two — a flat row list and a page stack — and asks the question a different way in each. A frontend that wants “the row under the cursor” should not have to know which one it set, least of all a frontend that switches between them; getting it wrong reads as a link that follows the wrong document rather than as an error.

pub fn body(&self) -> &Doc

The body editor.

pub fn body_mut(&mut self) -> &mut Doc

pub fn set_metadata(&mut self, path: &[Seg], value: Value)

Programmatically set the metadata value at path — the flat, by-path edit a UI/FFI issues (vs. driving the selection).

pub fn dirty(&self) -> bool

true if the metadata or the body has unsaved edits.

pub fn reassemble(&mut self) -> Result<String, SessionError>

Reconcile the body edits into the document and return the full reassembled text — exactly the bytes save writes. Does not touch disk.

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

Write the reassembled document (metadata edits + body edits) to disk.