typg_core/lib.rs
1/// typg-core: The gentle detective of font discovery
2///
3/// Like a seasoned librarian who knows every book by heart, this library
4/// helps you find fonts based on their hidden stories. It's the quiet hero
5/// for font management systems that need to ask polite questions and get
6/// thoughtful answers from massive font collections.
7///
8/// ## Three Acts of Font Discovery
9///
10/// **Discovery**: The gentle art of finding what's already there
11/// - Befriends all font formats (TTF, OTF, TTC, OTC, WOFF, WOFF2)
12/// - Handles font collections like a skilled orchestra conductor
13/// - Processes collections in parallel, never making anyone wait too long
14///
15/// **Indexing**: Getting acquainted with every font's personality
16/// - Remembers names, family secrets, and style preferences
17/// - Takes careful notes on variable font axes and their moods
18/// - Catalogs OpenType features and script talents
19/// - Classifies fonts by weight, width, and family tendencies
20///
21/// **Search**: Asking the right questions to find kindred spirits
22/// - Matches names with the graceful accuracy of a matchmaker
23/// - Finds fonts that speak specific languages and write specific scripts
24/// - Filters by variable font capabilities like a talent scout
25/// - Looks for special features hidden in the font's DNA
26/// - Combines criteria with boolean logic that's more poetry than math
27///
28/// ## A Sample Conversation
29///
30/// ```rust,no_run
31/// use std::path::PathBuf;
32/// use typg_core::query::Query;
33/// use typg_core::search::{search, SearchOptions};
34/// use typg_core::tags::tag4;
35///
36/// // Let's find an Arabic font that's flexible like a dancer.
37/// let query = Query::new()
38/// .with_scripts(vec![tag4("arab").unwrap()])
39/// .with_axes(vec![tag4("wght").unwrap()])
40/// .require_variable(true);
41///
42/// // Where do we look for our font friends?
43/// let font_dirs = vec![
44/// PathBuf::from("/System/Library/Fonts"),
45/// PathBuf::from("/Library/Fonts"),
46/// PathBuf::from("~/fonts"),
47/// ];
48///
49/// let options = SearchOptions::default();
50/// let results = search(&font_dirs, &query, &options)?;
51///
52/// println!("Found {} fonts that caught our eye:", results.len());
53/// for font in results {
54/// println!(" {} ({})",
55/// font.metadata.names.first().unwrap_or(&"<mysterious>".to_string()),
56/// if font.metadata.is_variable { "adaptable" } else { "steady" }
57/// );
58/// }
59/// #
60/// # Ok::<(), Box<dyn std::error::Error>>(())
61/// ```
62///
63/// ## The Art of Performance
64///
65/// - **Parallel Processing**: Uses Rayon like a well-coordinated kitchen staff
66/// - **Cached Metadata**: Remembers what it learned, like a good friend
67/// - **Memory Efficiency**: Takes small bites, never choking on the whole meal
68/// - **Configurable Threading**: Lets you decide how many hands on deck
69///
70/// ## The Cast of Characters
71///
72/// - [`Query`]: Your diplomatic envoy to the font kingdom
73/// - [`TypgFontFaceMeta`]: The comprehensive biography of every font
74/// - [`TypgFontSource`]: Where each font calls home and how it dresses
75/// - [`TypgFontFaceMatch`]: The perfect marriage of metadata and location
76///
77/// ## Playground Rules
78///
79/// Built on cross-platform font playground equipment (read-fonts, skrifa)
80/// and plays nicely with all major operating systems. No proprietary
81/// gatekeeping - just pure metadata magic that works everywhere.
82///
83/// ## Making Friends
84///
85/// - Use with typg-python for Python conversations
86/// - Pair with typg-index for database-backed social networking
87/// - Cache your discoveries to avoid repeating stories
88/// - Be mindful of memory when hosting large font parties
89///
90/// ---
91///
92/// Crafted with care at FontLab https://www.fontlab.com/
93pub mod discovery;
94#[cfg(feature = "hpindex")]
95pub mod index;
96pub mod output;
97pub mod query;
98pub mod search;
99pub mod tags;