Skip to main content

smooth_reading/
lib.rs

1//! Guided fixation reading: the leading letters of every word are emphasised
2//! so the eye lands on an artificial fixation point and the brain completes
3//! the rest of the word.
4//!
5//! This crate is an independent, clean-room, zero-dependency implementation
6//! of the algorithm defined in the Smooth Reading
7//! [specification](https://github.com/PythonShe/Smooth_Reading/blob/main/docs/SPEC.md),
8//! producing byte-identical output with the TypeScript, Swift, Kotlin, Python
9//! and Dart ports across all shared fixtures.
10//!
11//! # Quick start
12//!
13//! ```
14//! use smooth_reading::{HtmlOptions, Options, Token, to_html, to_markdown, tokenize};
15//!
16//! // HTML: the first half of each word is wrapped in <b>.
17//! let html = to_html("Smooth reading works.", &Options::new(), &HtmlOptions::new());
18//! assert_eq!(html, "<b>Smo</b>oth <b>read</b>ing <b>wor</b>ks.");
19//!
20//! // Markdown.
21//! assert_eq!(to_markdown("Smooth reading", &Options::new(), "**"), "**Smo**oth **read**ing");
22//!
23//! // Tokens, for rendering with your own text engine.
24//! for token in tokenize("Smooth reading", &Options::new().fixation(4)) {
25//!     match token {
26//!         Token::Word { fixation_text, rest_text, .. } => println!("{fixation_text} | {rest_text}"),
27//!         Token::Separator { text } => print!("{text}"),
28//!     }
29//! }
30//! ```
31//!
32//! # Options
33//!
34//! [`Options`] holds the algorithm settings (`fixation` strength `1..=5`,
35//! `saccade` interval, `min_word_length`, `emphasize_numbers`, `locale`, a
36//! custom `fixation_length` override and a pluggable [`Segmenter`]);
37//! [`HtmlOptions`] holds the markup settings for [`to_html`]. Both are
38//! configured with chaining setters and clamp out-of-range values instead of
39//! failing.
40//!
41//! # Unicode
42//!
43//! The default [`SpecSegmenter`] is the spec's regular-expression scanner over
44//! a generated Unicode general-category table ([`unicode_data`], no runtime
45//! dependencies), with grapheme clustering that keeps combining marks, Hangul
46//! jamo, Indic conjuncts and emoji sequences whole. Right-to-left text is
47//! never reordered: the fixation is always the logical start of the word. A
48//! continuous run of Chinese, Japanese or Thai is one word; plug in a
49//! dictionary-based [`Segmenter`] for finer breaks.
50
51#![forbid(unsafe_code)]
52
53mod fixation;
54mod html;
55mod options;
56mod segment;
57mod tokenize;
58pub mod unicode_data;
59
60pub use fixation::fixation_length;
61pub use html::{DEFAULT_SKIP_TAGS, HtmlOptions, escape_html, to_html, to_markdown};
62pub use options::{FixationLengthFn, Options};
63pub use segment::{Segment, Segmenter, SpecSegmenter};
64pub use tokenize::{Token, TokenizeState, tokenize, tokenize_with_state};
65
66/// The crate version, kept in step with every other Smooth Reading port.
67pub const VERSION: &str = env!("CARGO_PKG_VERSION");