docgen_bases/lib.rs
1//! `docgen-bases` — a faithful, dependency-light engine and static HTML renderer
2//! for [Obsidian Bases](https://obsidian.md/help/bases).
3//!
4//! A `.base` file is a YAML document describing filtered, sorted, grouped *views*
5//! over a vault's notes, computed from note frontmatter, file metadata, and an
6//! expression language (functions, methods, operators, formulas, summaries). This
7//! crate parses that YAML, evaluates the expression language over a caller-built
8//! [`Corpus`] of [`Note`]s, and renders each view to self-contained HTML — no
9//! scripts, no runtime — for build-time inclusion in a static site.
10//!
11//! The crate is pure: it performs no I/O and knows nothing about docgen. The host
12//! (docgen-build / docgen-core) constructs the [`Corpus`] from discovered docs and
13//! supplies a [`RenderOptions`] with the site base path.
14//!
15//! ## Quick start
16//! ```
17//! use docgen_bases::{render_base_source, Corpus, Note, RenderOptions};
18//!
19//! let mut note = Note::default();
20//! note.slug = "books/dune".into();
21//! note.basename = "Dune".into();
22//! note.tags = vec!["book".into()];
23//! let corpus = Corpus::new(vec![note]);
24//!
25//! let yaml = "filters:\n and:\n - file.hasTag(\"book\")\nviews:\n - type: table\n";
26//! let html = render_base_source(yaml, &corpus, &RenderOptions::default());
27//! assert!(html.contains("docgen-base-table"));
28//! ```
29
30// Test helpers build `Note`/`View` fixtures by field-reassigning a `default()`,
31// which is clearest for large structs; allow it in test code only.
32#![cfg_attr(test, allow(clippy::field_reassign_with_default))]
33
34pub mod ast;
35pub mod eval;
36pub mod filter;
37pub mod format;
38pub mod functions;
39mod interactive;
40pub mod lexer;
41pub mod model;
42pub mod note;
43pub mod parser;
44pub mod render;
45pub mod semver;
46pub mod summary;
47pub mod value;
48
49pub use interactive::view_interactive_enabled;
50pub use model::{parse_base, BaseFile};
51pub use note::{parse_date, parse_wikilink, properties_from_yaml, value_from_yaml, Corpus, Note};
52pub use render::{error_block, render_base, render_base_source, RenderOptions};
53pub use value::{BaseDate, BaseLink, Value};
54
55/// Errors surfaced by the base engine. Parsing/eval degrade gracefully inside the
56/// renderer (producing error blocks / empty cells), so this is mostly for callers
57/// that want to parse a base explicitly.
58#[derive(Debug, thiserror::Error)]
59pub enum BaseError {
60 #[error("parsing .base YAML: {0}")]
61 Yaml(#[from] serde_yml::Error),
62 #[error("parsing expression `{expr}`: {message}")]
63 Expr { expr: String, message: String },
64}