glum_lib/lib.rs
1//! glum — a reading-focused terminal markdown viewer.
2//!
3//! This crate is the library half of the `glum` binary: the markdown
4//! renderer, the TUI application loop, the clipboard transport, and the
5//! persistence store that remembers your reading position. It's published
6//! mostly so users can read the source as documentation and so contributors
7//! can navigate on [docs.rs]; you usually want the [`glum`] binary, not a
8//! direct dependency on this library.
9//!
10//! # What's inside
11//!
12//! - [`render`] — parses `CommonMark` with
13//! [`pulldown_cmark`](https://docs.rs/pulldown-cmark) and produces
14//! pre-styled, pre-wrapped [`ratatui`](https://docs.rs/ratatui) lines.
15//! Central entry point: [`render::render`].
16//! - [`app`] — the `ratatui` application loop: paging, theme cycling, table of
17//! contents, search, code-block copy, external-editor handoff. Entry
18//! point: [`app::run`].
19//! - [`theme`] — five color themes (`light`, `dark`, `sepia`, `night`,
20//! `plain`) plus their per-role styles (headings, code, quotes, rules,
21//! links). See [`theme::Theme::resolve`].
22//! - [`layout`] — two typographic layouts (`minimal`, `vivid`) that
23//! drive heading decorations and rule heaviness.
24//! - [`highlight`] — small per-language token highlighters for fenced code
25//! blocks. Intentionally lightweight: keyword sets, generic string /
26//! comment / number rules. See [`highlight::highlight_line`].
27//! - [`cli`] — [`clap`] argument definitions for the `glum` binary.
28//! - [`clipboard`] — OSC 52 copy with native (`pbcopy`, `wl-copy`, `xclip`,
29//! `xsel`) fallbacks. See [`clipboard::copy`].
30//! - [`positions`] — on-disk store for reading positions and remembered
31//! preferences, with SHA-256-hashed paths so the store doesn't reveal
32//! which files have been read.
33//! - [`typography`] — "smart quote" typographic substitution
34//! (`--` → `—`, `...` → `…`, straight → curly quotes).
35//! - [`watch`] — debounced filesystem watcher used by `--follow`.
36//!
37//! # Example: render a markdown string to styled lines
38//!
39//! ```no_run
40//! use glum_lib::layout::LayoutName;
41//! use glum_lib::render;
42//! use glum_lib::theme::{Theme, ThemeName};
43//!
44//! let md = "# Hello\n\nA paragraph with `code` and a [link](https://example.com).";
45//! let r = render::render(
46//! md,
47//! /* measure */ 72,
48//! Theme::resolve(ThemeName::Plain),
49//! LayoutName::Minimal,
50//! /* wrap_code */ true,
51//! );
52//! // `r.lines` is a `Vec<ratatui::text::Line<'static>>` ready to render;
53//! // `r.toc` is the heading outline; `r.code_blocks` is the set of fenced
54//! // blocks, each carrying its raw source text plus visual-row ranges.
55//! for line in &r.lines {
56//! println!("{}", line.to_string());
57//! }
58//! ```
59//!
60//! # Stability
61//!
62//! This library's API is not stabilized. It tracks glum's binary; minor
63//! releases may break library consumers. Pin exact versions if you depend
64//! on it.
65//!
66//! [`glum`]: https://crates.io/crates/glum
67//! [docs.rs]: https://docs.rs/glum
68//! [`clap`]: https://docs.rs/clap
69
70#![forbid(unsafe_code)]
71#![deny(rust_2018_idioms)]
72#![warn(missing_docs)]
73
74pub mod app;
75pub mod cli;
76pub mod clipboard;
77pub mod highlight;
78pub mod layout;
79pub mod positions;
80pub mod render;
81pub mod theme;
82pub mod typography;
83pub mod watch;