Skip to content
calternal docs

calternal_notes_core::frontmatter

Lossless YAML-safe Note frontmatter access.

The frontmatter writer is centralized here. It moves managed keys into one stable tier order, keeps custom key segments verbatim, and reattaches the body byte-for-byte. Writes use a line scanner. Date reads also decode bounded YAML mappings so quoted and explicit keys remain protected (#1148 review).

Source: crates/calternal-notes-core/src/frontmatter.rs

Structs

Section titled “Structs”

NoteDateValues

Section titled “NoteDateValues”
pub struct NoteDateValues

Raw date properties plus presence of the two app-managed keys. Alias values are readable fallbacks; migrations use the presence bits to avoid replacing even malformed User-authored values (#1148, DESIGN §§9, 17).

Fields

  • pub created: Option<String>
  • pub last_edited: Option<String>
  • pub has_date_key: bool
  • pub has_last_edited_key: bool

Implements: Debug, Clone, Default, PartialEq, Eq

Source: crates/calternal-notes-core/src/frontmatter.rs:26

NoteFrontmatterPatch

Section titled “NoteFrontmatterPatch”
pub struct NoteFrontmatterPatch

None leaves a field unchanged. An empty tags list removes tags:.

Fields

  • pub calternal_id: Option<String>
  • pub title: Option<String>
  • pub created: Option<String>
  • pub last_edited: Option<String>
  • pub slug: Option<String>
  • pub calternal_events: Option<Vec<String>>
  • pub tags: Option<Vec<String>>
  • pub user_properties: BTreeMap<String: Scalar user keys to set or remove. None removes a key.

Implements: Debug, Clone, Default, PartialEq, Eq

Source: crates/calternal-notes-core/src/frontmatter.rs:43

NoteMeta

Section titled “NoteMeta”
pub struct NoteMeta

No doc comment.

Fields

  • pub calternal_id: Option<String>
  • pub created: Option<String>
  • pub last_edited: Option<String>
  • pub slug: Option<String>
  • pub tags: Vec<String>

Implements: Debug, Clone, Default, PartialEq, Eq

Source: crates/calternal-notes-core/src/frontmatter.rs:14

Enums

Section titled “Enums”

NoteDateField

Section titled “NoteDateField”
pub enum NoteDateField

Choose which Note date a caller needs. Created maps to date:; Modified maps to last edited: and each has read-only aliases for imported Notes.

Variants

  • Created
  • LastEdited

Implements: Debug, Clone, Copy, PartialEq, Eq

Source: crates/calternal-notes-core/src/frontmatter.rs:36

Functions

Section titled “Functions”

add_missing_note_dates

Section titled “add_missing_note_dates”
pub fn add_missing_note_dates(
    text: &str,
    created: Option<&str>,
    last_edited: Option<&str>,
) -> String

Add only absent managed date lines. All existing frontmatter and body bytes remain untouched, including a BOM and CRLF spelling (#1148).

Source: crates/calternal-notes-core/src/frontmatter.rs:116

extract_note_date_values

Section titled “extract_note_date_values”
pub fn extract_note_date_values(text: &str) -> NoteDateValues

Read the managed date values and their Obsidian-compatible aliases without rewriting source properties. Primary keys win when present (#1148).

Source: crates/calternal-notes-core/src/frontmatter.rs:70

extract_note_meta

Section titled “extract_note_meta”
pub fn extract_note_meta(text: &str) -> NoteMeta

Read app-managed Note metadata. This flat reader supports the flow list written by this crate and block lists from hand-authored YAML.

Source: crates/calternal-notes-core/src/frontmatter.rs:588

extract_note_properties

Section titled “extract_note_properties”
pub fn extract_note_properties(text: &str) -> BTreeMap<String, String>

Project top-level scalar properties for API display. The writer retains raw multiline segments independently of this projection.

Source: crates/calternal-notes-core/src/frontmatter.rs:605

extract_note_title

Section titled “extract_note_title”
pub fn extract_note_title(text: &str) -> Option<String>

Read the managed title with the same scalar rules as the frontmatter writer.

Source: crates/calternal-notes-core/src/frontmatter.rs:599

frontmatter_bounds

Section titled “frontmatter_bounds”
pub fn frontmatter_bounds(text: &str) -> Option<(usize, usize)>

Find the byte bounds of a leading frontmatter block as (body_start, closing_fence_start). A BOM before the opening fence remains outside the returned range. Fence pairs around prose are card breaks, not metadata.

Source: crates/calternal-notes-core/src/frontmatter.rs:184

note_date_timestamp

Section titled “note_date_timestamp”
pub fn note_date_timestamp(text: &str, field: NoteDateField, zone: Tz) -> Option<DateTime<Utc>>

Read a parseable primary date or alias from one Note. Invalid primary values do not hide a valid fallback property (#1148).

Source: crates/calternal-notes-core/src/frontmatter.rs:102

parse_note_date_value

Section titled “parse_note_date_value”
pub fn parse_note_date_value(value: &str, zone: Tz) -> Option<DateTime<Utc>>

Parse one frontmatter date using the User’s zone for values with no offset. It accepts existing date-only, minute, second and RFC 3339 forms (#1148).

Source: crates/calternal-notes-core/src/frontmatter.rs:83

set_calternal_id

Section titled “set_calternal_id”
pub fn set_calternal_id(text: &str, id: &str) -> String

Set one app-managed calternal-id while keeping every other byte unchanged. Hosts validate and mint the ID before calling this helper.

Source: crates/calternal-notes-core/src/frontmatter.rs:582

set_note_frontmatter

Section titled “set_note_frontmatter”
pub fn set_note_frontmatter(text: &str, patch: &NoteFrontmatterPatch) -> String

Upsert Note frontmatter. Managed fields are tiered; user segments and the body remain byte-identical. calternal-events sits with managed keys and tags stays last, as in the reference writer.

Source: crates/calternal-notes-core/src/frontmatter.rs:890

set_note_frontmatter_scalar

Section titled “set_note_frontmatter_scalar”
pub fn set_note_frontmatter_scalar(text: &str, field: &str, value: Option<&str>) -> String

Set or remove one top-level scalar while keeping every other source byte. This uses the same YAML-safe scalar writer as set_note_frontmatter. Live edits use this path so one changed property does not rewrite other fields.

Source: crates/calternal-notes-core/src/frontmatter.rs:575

valid_user_property_key

Section titled “valid_user_property_key”
pub fn valid_user_property_key(key: &str) -> bool

User property keys cannot replace managed fields or alter YAML structure.

Source: crates/calternal-notes-core/src/frontmatter.rs:620