jots 0.2.0

Jot Syntax 1.0 RC6 parser (https://jotsyntax.org)
Documentation
//! Compiled regex primitives mirroring the Perl reference's "Grammar primitives
//! (§7)" block. The Rust `regex` crate has no lookbehind, so the §7.1 left
//! boundary is checked in code by [`is_left_boundary`] after each match instead
//! of via `(?<=^|\s)`.
//!
//! The identifier and filename character classes are the one axis that
//! varies between the Jot Syntax (ASCII) and Iota Syntaxis (Unicode XID)
//! variants, so every class-dependent regex lives on [`Grammar`], built
//! per variant and selected at runtime via [`grammar`]. Regexes with no
//! identifier classes (URLs, empty-payload rejects, fragment decoders,
//! ISO dates) stay as module statics. Each variant's set compiles
//! lazily on first use.

pub use fancy_regex::Regex;
use std::sync::LazyLock;

const UINT: &str = r"[0-9]+";

const ISO_DATE: &str = r"\d{4}-\d{2}-\d{2} (?: T \d{2}:\d{2} (?: :\d{2} )?
                                              (?: Z | [+\-]\d{2}:\d{2} )? )?";

/// Build a regex with the `(?x)` extended flag.
fn compile(pattern: &str) -> Regex {
    let body = format!("(?x){}", pattern);
    Regex::new(&body).unwrap_or_else(|e| panic!("regex compile failed: {e}\n---\n{body}\n---"))
}

/// `(?:^|preceded by [ \t\r\n])` — §7.1. The regex can't express this
/// natively, so we run it in user code over a candidate match's start byte.
pub fn is_left_boundary(text: &str, start: usize) -> bool {
    if start == 0 {
        return true;
    }
    let bytes = text.as_bytes();
    matches!(bytes[start - 1], b' ' | b'\t' | b'\r' | b'\n')
}

/// Every identifier-class-dependent regex, compiled for one variant.
/// Field names mirror the former module-static names.
pub struct Grammar {
    // ── Inter-jot resources ─────────────────────────────────────────
    pub inter_jot_cross_id: Regex,
    pub inter_jot_same_id: Regex,
    pub inter_jot_cross_file: Regex,
    pub inter_jot_same_file: Regex,
    // ── File references ─────────────────────────────────────────────
    pub cross_file_ref: Regex,
    pub file_ref: Regex,
    // ── ID references ───────────────────────────────────────────────
    pub cross_id_ref: Regex,
    pub id_ref: Regex,
    // ── Resources ───────────────────────────────────────────────────
    pub resource: Regex,
    // ── Bookmark / tags / categories ────────────────────────────────
    pub bookmark_decl: Regex,
    pub tagstring: Regex,
    pub tag: Regex,
    pub hashtag: Regex,
    pub category: Regex,
    /// A whole string that is exactly one `<word>` — validates the
    /// `category_root` flag value (§9.1).
    pub word_full: Regex,
    // ── Reject patterns ─────────────────────────────────────────────
    pub rej_annot_before_sep_id: Regex,
    pub rej_annot_before_sep_file_same: Regex,
    pub rej_annot_before_sep_file_cross: Regex,
    pub rej_spec_on_loc_id: Regex,
    pub rej_spec_on_loc_file_same: Regex,
    pub rej_spec_on_loc_file_cross: Regex,
    pub rej_cat_run: Regex,
    pub rej_filename_doubledot: Regex,
    pub rej_filename_start_file_cross: Regex,
    pub rej_frag_nonnum_id: Regex,
    pub rej_frag_nonnum_file_same: Regex,
    pub rej_frag_nonnum_file_cross: Regex,
    pub rej_frag_nonnum_res: Regex,
    pub rej_mutex_id: Regex,
    pub rej_mutex_file_same: Regex,
    pub rej_mutex_file_cross: Regex,
    pub rej_mutex_res: Regex,
    pub rej_mutex_inter_id: Regex,
    pub rej_mutex_inter_file_same: Regex,
    pub rej_mutex_inter_file_cross: Regex,
    pub rej_empty_bmr_id: Regex,
    pub rej_empty_bmr_file_same: Regex,
    pub rej_empty_bmr_file_cross: Regex,
    pub rej_empty_bmr_res: Regex,
    pub rej_bmr_nocomma_id: Regex,
    pub rej_bmr_nocomma_file_same: Regex,
    pub rej_bmr_nocomma_file_cross: Regex,
    pub rej_bmr_nocomma_res: Regex,
    pub rej_empty_bm_spec_id: Regex,
    pub rej_empty_bm_spec_file_same: Regex,
    pub rej_empty_bm_spec_file_cross: Regex,
    pub rej_empty_bm_spec_res: Regex,
    pub rej_tags_before_cat_id: Regex,
    pub rej_tags_before_cat_file_same: Regex,
    pub rej_tags_before_cat_file_cross: Regex,
    pub rej_tags_before_cat_res: Regex,
    pub rej_tags_before_cat_todo: Regex,
    pub rej_invalid_filename_chars: Regex,
    pub valid_res_token: Regex,
    // ── Decoders ────────────────────────────────────────────────────
    pub decode_bmr_range: Regex,
    pub decode_bm: Regex,
    pub decode_category_prefix: Regex,
    pub decode_tag_prefix: Regex,
    pub decode_todo_body: Regex,
    pub todo_malformed_due: Regex,
    pub blocker_entry_word: Regex,
    pub blocker_entry_wildcard: Regex,
}

impl Grammar {
    fn new(unicode: bool) -> Self {
        // The variant predicate (SPEC §7.1 variant note; ARCHITECTURE
        // "Variants"): identifier bodies are `[A-Za-z0-9_]` in the ASCII
        // variant and XID_Start/XID_Continue plus underscore in the
        // Unicode variant; `<letter>` (the hashtag start guard) is
        // `[A-Za-z]` vs XID_Start — underscore stays excluded there in
        // both variants (vector 77). `<filename>` widens along with
        // `<word-char>` (decided 2026-07-04). Digits, whitespace, the
        // trim set, and the sigils never vary.
        let wi = if unicode { r"\p{XID_Start}\p{XID_Continue}_" } else { "A-Za-z0-9_" };
        let li = if unicode { r"\p{XID_Start}" } else { "A-Za-z" };

        let word = format!("[{wi}]+");
        // §7.2 — one or more chained `..word` segments (tagstring tail).
        // Reused by the annotated-suffix rejection regexes so a chained
        // `..tag1..tag2::cat` is caught as tags-before-category, not just
        // the single-tag `..tag::cat` form.
        let tag_tail = format!(r"(?: \.\. {word} )+");
        let fseg = format!(r"[{wi}~,@!()][{wi}~,@!()\-]*");
        let filename = format!(r"{fseg} (?: \. {fseg} )*");
        let filepath = format!(r"{filename} (?: / {filename} )*");

        // Specifier alternatives. Order matters: `##` must precede `#`
        // (regex alternation is leftmost-first); the `:N` form requires a
        // digit lookahead so `::` doesn't get mistaken for a fragment intro.
        let specifier = format!(
            r"(?: \#\# (?: {word} , (?:{word})? | , {word} )
                | : (?=[0-9]) [0-9]+ (?: [-+] [0-9]+ )?
                | \# (?!\#) {word} )"
        );
        let annotations = format!(
            r"(?: :: {word} (?: :: {word} )* )?
              (?: \.\. {word} )*"
        );
        let annot_nonempty =
            format!(r"(?: \.\. {word} | :: {word} (?: :: {word} )*)+");
        let id_locator = format!(r"-- (?: {word} -- )? {word}");
        let file_locator_same = format!(r"// {filepath}");
        let file_locator_cross = format!(r"/// {word} / {filepath}");
        let empty_bmr = format!(r"\#\#, (?![{wi}])");
        // `##` with no comma at all, followed by whitespace/EOL — broadened
        // EmptyBookmarkRange condition (13.6).
        let empty_bmr_nocomma = r"\#\# (?=[ \t\r\n]|\z)";
        // `#` bookmark specifier with an empty name (13.7): `--42#` + ws/EOL.
        let empty_bm_spec = r"\# (?=[ \t\r\n]|\z)";

        let w = &word;
        let t = &tag_tail;
        let f = &filename;
        let p = &filepath;
        let s = &specifier;
        let a = &annotations;
        let ane = &annot_nonempty;
        let idl = &id_locator;
        let fls = &file_locator_same;
        let flc = &file_locator_cross;
        let d = ISO_DATE;

        Grammar {
            inter_jot_cross_id: compile(&format!(r"-- ({w}) -- ({w}) ;; ({f}) ({s})? ({a})")),
            inter_jot_same_id: compile(&format!(r"-- ({w}) ;; ({f}) ({s})? ({a})")),
            inter_jot_cross_file: compile(&format!(r"/// ({w}) / ({p}) ;; ({f}) ({s})? ({a})")),
            inter_jot_same_file: compile(&format!(r"// ({p}) ;; ({f}) ({s})? ({a})")),

            cross_file_ref: compile(&format!(r"/// ({w}) / ({p}) ({s})? ({a})")),
            file_ref: compile(&format!(r"// ({p}) ({s})? ({a})")),

            cross_id_ref: compile(&format!(r"-- ({w}) -- ({w}) ({s})? ({a})")),
            id_ref: compile(&format!(r"-- ({w}) ({s})? ({a})")),

            resource: compile(&format!(r";; ({f}) ({s})? ({a})")),

            bookmark_decl: compile(&format!(r"!! ({w})")),
            // `<tagstring>` — one or more chained `..word` segments (§7.2).
            // `tag` matches a single `..word` tail; the scan loop uses
            // `tagstring` to find chain bounds and `tag` to walk segments.
            tagstring: compile(&format!(r"(?: \.\. {w} )+")),
            tag: compile(&format!(r"\.\. ({w})")),
            hashtag: compile(&format!(r"\# (?=[{li}]) ({w})")),
            category: compile(&format!(r":: ({w} (?: :: {w} )*)")),
            word_full: compile(&format!(r"\A {w} \z")),

            rej_annot_before_sep_id: compile(&format!(r"{idl} {ane} ;; {f} (?:{s})? {a}")),
            rej_annot_before_sep_file_same: compile(&format!(r"{fls} {ane} ;; {f} (?:{s})? {a}")),
            rej_annot_before_sep_file_cross: compile(&format!(r"{flc} {ane} ;; {f} (?:{s})? {a}")),

            rej_spec_on_loc_id: compile(&format!(r"{idl} {s} (?:{ane})? ;; {f} (?:{s})? {a}")),
            rej_spec_on_loc_file_same: compile(&format!(r"{fls} {s} (?:{ane})? ;; {f} (?:{s})? {a}")),
            rej_spec_on_loc_file_cross: compile(&format!(r"{flc} {s} (?:{ane})? ;; {f} (?:{s})? {a}")),

            rej_cat_run: compile(&format!(r"(:: [{wi}:]*)")),
            rej_filename_doubledot: compile(&format!(r";; ({fseg} \.\. \S*)")),
            rej_filename_start_file_cross: compile(&format!(r"/// {w} / ([-.] \S*)")),

            rej_frag_nonnum_id: compile(&format!(r"{idl} : (?![0-9:]) [^\s]+")),
            rej_frag_nonnum_file_same: compile(&format!(r"{fls} : (?![0-9:]) [^\s]+")),
            rej_frag_nonnum_file_cross: compile(&format!(r"{flc} : (?![0-9:]) [^\s]+")),
            rej_frag_nonnum_res: compile(&format!(r";; {f} : (?![0-9:]) [^\s]+")),

            rej_mutex_id: compile(&format!(r"{idl} {s} {s}")),
            rej_mutex_file_same: compile(&format!(r"{fls} {s} {s}")),
            rej_mutex_file_cross: compile(&format!(r"{flc} {s} {s}")),
            rej_mutex_res: compile(&format!(r";; {f} {s} {s}")),
            rej_mutex_inter_id: compile(&format!(r"{idl} ;; {f} {s} {s}")),
            rej_mutex_inter_file_same: compile(&format!(r"{fls} ;; {f} {s} {s}")),
            rej_mutex_inter_file_cross: compile(&format!(r"{flc} ;; {f} {s} {s}")),

            rej_empty_bmr_id: compile(&format!(r"{idl} {empty_bmr}")),
            rej_empty_bmr_file_same: compile(&format!(r"{fls} {empty_bmr}")),
            rej_empty_bmr_file_cross: compile(&format!(r"{flc} {empty_bmr}")),
            rej_empty_bmr_res: compile(&format!(r";; {f} {empty_bmr}")),

            rej_bmr_nocomma_id: compile(&format!(r"{idl} {empty_bmr_nocomma}")),
            rej_bmr_nocomma_file_same: compile(&format!(r"{fls} {empty_bmr_nocomma}")),
            rej_bmr_nocomma_file_cross: compile(&format!(r"{flc} {empty_bmr_nocomma}")),
            rej_bmr_nocomma_res: compile(&format!(r";; {f} {empty_bmr_nocomma}")),

            rej_empty_bm_spec_id: compile(&format!(r"{idl} {empty_bm_spec}")),
            rej_empty_bm_spec_file_same: compile(&format!(r"{fls} {empty_bm_spec}")),
            rej_empty_bm_spec_file_cross: compile(&format!(r"{flc} {empty_bm_spec}")),
            rej_empty_bm_spec_res: compile(&format!(r";; {f} {empty_bm_spec}")),

            rej_tags_before_cat_id: compile(&format!(r"{idl} (?:{s})? {t} ::{w} [^\s]*")),
            rej_tags_before_cat_file_same: compile(&format!(r"{fls} (?:{s})? {t} ::{w} [^\s]*")),
            rej_tags_before_cat_file_cross: compile(&format!(r"{flc} (?:{s})? {t} ::{w} [^\s]*")),
            rej_tags_before_cat_res: compile(&format!(r";; {f} (?:{s})? {t} ::{w} [^\s]*")),
            rej_tags_before_cat_todo: compile(&format!(
                r"\?\? [ \t]* (?:!{{1,3}})? {w} (?:[ \t]*@{d})? {t} ::{w} [^\r\n]*"
            )),

            rej_invalid_filename_chars: compile(&format!(r";; ([{wi}~,@!()] \S*)")),

            valid_res_token: compile(&format!(r"\A {f} (?:{s})? {a} \z")),

            decode_bmr_range: compile(&format!(r"\A \#\# ({w})? , ({w})? \z")),
            decode_bm: compile(&format!(r"\A \# ({w}) \z")),
            decode_category_prefix: compile(&format!(r"\A :: ({w} (?: :: {w} )*)")),
            decode_tag_prefix: compile(&format!(r"\A \.\. ({w})")),

            decode_todo_body: compile(&format!(
                r"\A
                  (\.)?
                  (!{{1,3}})?
                  (?: \( ([^)\r\n]*) \) )?
                  ({w})
                  (?: [ \t]* @ ({d}) )?
                  (
                      (?: :: {w} (?: :: {w} )* )?
                      (?: \.\. {w} )*
                  )
                  (?:
                      (?: : [ \t]* | [ \t]+ :? [ \t]* ) (.*)
                  )?
                  \z"
            )),
            // `@` directly attached to the action but the tail failed the todo
            // grammar — a grammar-level malformed due date (11.10).
            todo_malformed_due: compile(&format!(
                r"\A \.? !{{0,3}} (?: \( [^)\r\n]* \) )? {w} @ \S*"
            )),

            // Blocker-entry validators (content between the parens, one entry
            // after comma-splitting). Wildcard form REQUIRES a category.
            blocker_entry_word: compile(&format!(
                r"\A ({w}) ( :: {w} (?: :: {w} )* )? ( (?: \.\. {w} )* ) \z"
            )),
            blocker_entry_wildcard: compile(&format!(
                r"\A \* ( :: {w} (?: :: {w} )* ) ( (?: \.\. {w} )* ) \z"
            )),
        }
    }
}

static GRAMMAR_ASCII: LazyLock<Grammar> = LazyLock::new(|| Grammar::new(false));
static GRAMMAR_UNICODE: LazyLock<Grammar> = LazyLock::new(|| Grammar::new(true));

/// Select the compiled grammar for a variant. Each set compiles lazily
/// on first use, so an ASCII-only process never pays for the Unicode
/// classes (and vice versa).
pub fn grammar(unicode: bool) -> &'static Grammar {
    if unicode { &GRAMMAR_UNICODE } else { &GRAMMAR_ASCII }
}

// ── Variant-invariant regexes ───────────────────────────────────────────────

// ── URLs ────────────────────────────────────────────────────────────────────

pub static URL_RE: LazyLock<Regex> = LazyLock::new(|| {
    compile(
        r#"==
        (?:
            \( ([^)]*) \) (https?://\S+)
          | \[ ([^\]]*) \] (https?://\S+)
          | (https?://\S+)
        )"#,
    )
});

// ── Todos ───────────────────────────────────────────────────────────────────

pub static TODO_LINE: LazyLock<Regex> = LazyLock::new(|| compile(r"\?\? ([^\r\n]*)"));

// ── Reject patterns (no identifier classes) ─────────────────────────────────

pub static REJ_URL_BARE: LazyLock<Regex> = LazyLock::new(|| compile(r"== (\S+)"));
pub static REJ_URL_UNMATCHED_PAREN: LazyLock<Regex> =
    LazyLock::new(|| compile(r"== \( [^)]* \) (?!https?://) [^\s)]* \) \S*"));
pub static REJ_URL_UNMATCHED_BRACKET: LazyLock<Regex> =
    LazyLock::new(|| compile(r"== \[ [^\]]* \] (?!https?://) [^\s\]]* \] \S*"));

// Empty payload — caller uses caps[1] for the sigil span.
pub static REJ_EMPTY_DOT: LazyLock<Regex> = LazyLock::new(|| compile(r"(\.\.) (?:[ \t\r\n]|\z)"));
pub static REJ_EMPTY_COLON: LazyLock<Regex> = LazyLock::new(|| compile(r"(::) (?:[ \t\r\n]|\z)"));
pub static REJ_EMPTY_DASH: LazyLock<Regex> = LazyLock::new(|| compile(r"(--) (?:[ \t\r\n]|\z)"));
pub static REJ_EMPTY_SLASH: LazyLock<Regex> = LazyLock::new(|| compile(r"(//) (?:[ \t\r\n]|\z)"));
pub static REJ_EMPTY_SEMI: LazyLock<Regex> = LazyLock::new(|| compile(r"(;;) (?:[ \t\r\n]|\z)"));
pub static REJ_EMPTY_EQ: LazyLock<Regex> = LazyLock::new(|| compile(r"(==) (?:[ \t\r\n]|\z)"));

pub static REJ_EMPTY_BANG: LazyLock<Regex> = LazyLock::new(|| compile(r"!! (?:[ \t\r\n]|\z)"));

pub static REJ_FILENAME_START_RES: LazyLock<Regex> =
    LazyLock::new(|| compile(r";; ([-.] \S*)"));
pub static REJ_FILENAME_START_FILE_SAME: LazyLock<Regex> =
    LazyLock::new(|| compile(r"// ([-.] \S*)"));

// ── Decoders (no identifier classes) ────────────────────────────────────────

pub static DECODE_FRAG_RANGE: LazyLock<Regex> =
    LazyLock::new(|| compile(&format!(r"\A : ({U}) - ({U}) \z", U = UINT)));
pub static DECODE_FRAG_OFFSET: LazyLock<Regex> =
    LazyLock::new(|| compile(&format!(r"\A : ({U}) \+ ({U}) \z", U = UINT)));
pub static DECODE_FRAG_SINGLE: LazyLock<Regex> =
    LazyLock::new(|| compile(&format!(r"\A : ({U}) \z", U = UINT)));

// Failure classifiers for todo bodies that miss `decode_todo_body`.
// Whitespace between the importance prefix and `(`, or between `)`
// and the action, is a blocker-slot parse error (§4.6 Todos).
pub static TODO_WS_BEFORE_PAREN: LazyLock<Regex> =
    LazyLock::new(|| compile(r"\A \.? !{0,3} [ \t]+ \("));
pub static TODO_WS_AFTER_PAREN: LazyLock<Regex> =
    LazyLock::new(|| compile(r"\A \.? !{0,3} \( [^)\r\n]* \) [ \t]"));

// Completion timestamp (`.@<iso-date>`) — recognized only during the
// done-todo description post-scan. The leading group anchors the
// construct boundary (start of description or preceding whitespace).
pub static COMPLETION_TIME: LazyLock<Regex> = LazyLock::new(|| {
    compile(&format!(r"(\A | [ \t]) \.@ ({D})", D = ISO_DATE))
});

pub static ISO_DATE_VALIDATOR: LazyLock<Regex> = LazyLock::new(|| {
    compile(
        r"\A (\d{4}) - (\d{2}) - (\d{2})
          (?: T (\d{2}) : (\d{2}) (?: : (\d{2}) )? )?",
    )
});