typg_core/lib.rs
1/// typg-core: the engine behind fast font search.
2///
3/// Point it at a folder of fonts. Tell it what you need — Arabic script support,
4/// a weight axis, ligatures, a specific glyph. It reads every font file in
5/// parallel, extracts the OpenType metadata that matters, and hands back the
6/// matches. Thousands of fonts in under a second on a modern machine.
7///
8/// # How a search works, end to end
9///
10/// 1. **Discovery** ([`discovery`]) walks your directories, collecting every
11/// `.ttf`, `.otf`, `.ttc`, and `.otc` file it finds. Broken symlinks and
12/// permission errors get a warning, not a crash.
13///
14/// 2. **Search** ([`search`]) opens each file with the `read-fonts` and `skrifa`
15/// crates (Google's Rust font-parsing libraries), pulls out metadata —
16/// names, axes, features, scripts, tables, codepoints, weight/width
17/// classification — and checks it against your query. This step runs on
18/// all available CPU cores via `rayon`.
19///
20/// 3. **Query** ([`query`]) is the filter specification. Every criterion is
21/// optional; an empty query matches everything. Criteria combine with AND
22/// logic: a font must satisfy *all* of them to appear in results.
23///
24/// 4. **Output** ([`output`]) serializes results to JSON or NDJSON for
25/// downstream tools and pipelines.
26///
27/// 5. **Tags** ([`tags`]) handles parsing and formatting of OpenType tags —
28/// the four-character codes (`wght`, `liga`, `latn`, `GSUB`) that identify
29/// axes, features, scripts, and tables inside a font.
30///
31/// 6. **Index** ([`index`], behind the `hpindex` feature flag) stores extracted
32/// metadata in an LMDB database with Roaring Bitmap inverted indices.
33/// Queries that would take seconds over thousands of files on disk take
34/// milliseconds against the index.
35///
36/// # Quick example
37///
38/// Find all variable fonts with Arabic script support and a weight axis:
39///
40/// ```rust,no_run
41/// use std::path::PathBuf;
42/// use typg_core::query::Query;
43/// use typg_core::search::{search, SearchOptions};
44/// use typg_core::tags::tag4;
45///
46/// let query = Query::new()
47/// .with_scripts(vec![tag4("arab").unwrap()])
48/// .with_axes(vec![tag4("wght").unwrap()])
49/// .require_variable(true);
50///
51/// let dirs = vec![PathBuf::from("/Library/Fonts")];
52/// let results = search(&dirs, &query, &SearchOptions::default())?;
53///
54/// for font in &results {
55/// println!("{}", font.source.path_with_index());
56/// }
57/// # Ok::<(), Box<dyn std::error::Error>>(())
58/// ```
59///
60/// # Font vocabulary cheat sheet
61///
62/// | Term | What it means |
63/// |------|--------------|
64/// | **OpenType** | The modern font format standard. A `.ttf` or `.otf` file is an OpenType font. |
65/// | **Variable font** | A single font file that contains a continuous range of weights, widths, or other design variations. Controlled by *axes*. |
66/// | **Axis** | A dimension of variation in a variable font. `wght` = weight (thin→black), `wdth` = width (condensed→expanded), `opsz` = optical size. |
67/// | **Feature** | An OpenType layout feature like `liga` (ligatures), `smcp` (small caps), or `kern` (kerning). Controls how glyphs are substituted or positioned. |
68/// | **Script** | A writing system tag like `latn` (Latin), `arab` (Arabic), `cyrl` (Cyrillic). Tells the shaping engine which rules to apply. |
69/// | **Table** | A named data block inside the font file. `GSUB` holds glyph substitution rules, `GPOS` holds positioning rules, `OS/2` holds classification metadata. |
70/// | **TTC/OTC** | TrueType/OpenType Collection — a single file bundling multiple font faces. Each face has a numeric index. |
71/// | **cmap** | The character map table. Maps Unicode codepoints to glyph IDs — it's how the font says "I can draw this character." |
72/// | **OS/2** | A metadata table carrying weight class, width class, font family classification, and other attributes originally designed for IBM's OS/2 operating system (the name stuck). |
73///
74/// Made by FontLab <https://www.fontlab.com/>
75pub mod discovery;
76#[cfg(feature = "hpindex")]
77pub mod index;
78pub mod output;
79pub mod query;
80pub mod search;
81pub mod tags;