font_map/
lib.rs

1//! # font-map
2//! ## Font parser / enumerator with support for code generation
3//!
4//! [![Crates.io](https://img.shields.io/crates/v/font-map.svg)](https://crates.io/crates/font-map/)
5//! [![Build Status](https://github.com/rscarson/font-map/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/rscarson/font-map/actions?query=branch%3Amaster)
6//! [![docs.rs](https://img.shields.io/docsrs/font-map)](https://docs.rs/font-map/latest/)
7//! [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/rscarson/font-map/master/LICENSE)
8//!
9//! This crate provides functionality for parsing font files and enumerating the glyphs they contain.
10//!
11//! The base usecase for this crate is to create an enum of all the glyphs in a font file,  
12//! for use in fontend projects, where you want to refer to glyphs by name rather than by codepoint:
13//!
14//! ```rust
15//! use font_map::font;
16//!
17//! font!(Icon, "google_material_symbols/font.ttf");
18//!
19//! const DELETE: Icon = Icon::Delete;
20//! ```
21//!
22//! The generated code includes information for each glyph, such as:
23//! - codepoint, and postfix-name
24//! - Plus a generated SVG preview image visible on hover
25//!
26//! You can also access `Icon::FONT_FAMILY` to simplify font usage in your frontend.
27//!
28//! -----
29//!
30//! Another use is to use it for introspection of font files:
31//!
32//! ```rust
33//! use font_map::font::Font;
34//!
35//! # use font_map::error::ParseError;
36//! # fn main() -> Result<(), ParseError> {
37//! let font = Font::from_file("google_material_symbols/font.ttf")?;
38//! if let Some(glyph) = font.glyph_named("delete") {
39//!     let codepoint = glyph.codepoint();
40//!     let svg = glyph.svg_preview();
41//! }
42//! # Ok(())
43//! # }
44//! ```
45//!
46//! ## Features
47//! - `macros` - Enables the `font!` macro for code generation
48//! - `codegen` - Enables the `FontCodegenExt` trait for runtime code generation
49//! - `extended-svg` - Enables compressed and base64 encoded SVG data in the generated code (Needed for image previews)
50//!
51//! ## Known Limitations
52//! This crate was made for a very specific use-case, and as such currently has a few limitations:
53//! - Only supports TTF fonts
54//! - And even then, only a subset of the spec, namely:
55//! - Only some formats of the `cmap` table
56//! - Only Unicode, or MS encoding 1 and 10, and `Macintosh::0` of the `name` table
57//! - Only formats 2.5 or below of the `post` table
58//!
59#![warn(missing_docs)]
60#![warn(clippy::pedantic)]
61#![cfg_attr(docsrs, feature(doc_cfg))]
62pub use font_map_core::*;
63
64#[cfg(feature = "macros")]
65#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
66pub use font_map_macros::*;
67
68/// **Only designed to be used inside `build.rs`**
69///
70/// This macro is used to generate the code for a font file, and set up the build script to rerun
71/// if the font file changes.
72///
73/// The generated code will include an enum with all the glyphs in the font, optionally split by
74/// category
75///
76/// To include the generated code, see `[font_map::include_font]`
77///
78/// # Example
79/// ```no_run
80/// use font_map::build_font;
81///
82/// fn main() {
83///     build_font!(
84///         path = "../examples/slick.ttf",
85///         name = SlickFont,
86///         skip_categories = false, /* Can be omitted - if `true`, generate one giant enum instead of a set of categories */
87///     );
88/// }
89/// ```
90#[cfg(feature = "macros")]
91#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
92#[allow(clippy::needless_doctest_main)]
93#[macro_export]
94macro_rules! build_font {
95    (
96        path = $path:literal,
97        name = $name:ident,
98        skip_categories = $skip_categories:literal $(,)?
99    ) => {
100        const FONT_BYTES: &[u8] = include_bytes!($path);
101        println!(concat!("cargo:rerun-if-changed=", $path));
102
103        let target_dir = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set");
104        let target_path = std::path::Path::new(&target_dir)
105            .join($path)
106            .display()
107            .to_string();
108
109        //
110        // Load the font and perform code generation
111        let font = font_map::font::Font::new(FONT_BYTES).expect("Bundled font was invalid!");
112        let generator =
113            font_map::codegen::FontDesc::from_font(stringify!($name), &font, $skip_categories);
114        let code = generator
115            .codegen(Some(font_map::codegen::quote! {
116                /// The raw bytes of the font file
117                pub const FONT_BYTES: &[u8] = include_bytes!(#target_path);
118            }))
119            .to_string();
120
121        //
122        // Create the target file
123        let dir = std::env::var("OUT_DIR").expect("OUT_DIR not set");
124        let target =
125            std::path::Path::new(&dir).join(&format!("font_generated_{}.rs", stringify!($name)));
126        std::fs::write(&target, code).expect("Failed to write generated icon-enum");
127
128        //
129        // Manually run rustfmt on the generated file
130        let _ = std::process::Command::new("rustfmt")
131            .arg(&target)
132            .status()
133            .expect("Failed to run rustfmt on generated icon-enum");
134
135        //
136        // Provide an ENV var with the path to the generated file
137        println!(
138            concat!("cargo:rustc-env=FONT_GEN_", stringify!($name), "={}"),
139            target.display()
140        );
141    };
142
143    (
144        path = $path:literal,
145        name = $name:ident $(,)?
146    ) => {
147        $crate::build_font! {
148            path = $path,
149            name = $name,
150            skip_categories = false
151        }
152    };
153}
154
155/// Includes a font file generated by the [`build_font!`] macro
156///
157/// **NOTE:** Due to existing issues with rust-analyzer you may need to restart the RA server (left side of bottom toolbar)
158/// after adding a new font file
159///
160/// This macro will include the generated code for the font's symbols, and provide:
161/// - `FONT_BYTES`: The raw bytes of the font file
162/// - `load_font()`: A function that returns a `font_map::font::Font` instance describing the font and its symbols
163///
164/// # Example
165/// ```ignore
166/// use font_map::include_font;
167///
168/// include_font!(GoogleMaterialSymbols);
169///
170/// const DELETE: GoogleMaterialSymbols = GoogleMaterialSymbols::Delete;
171/// ```
172#[cfg(feature = "macros")]
173#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
174#[macro_export]
175macro_rules! include_font {
176    ($name:ident) => {
177        //
178        // Generated font bindings
179        include!(env!(concat!("FONT_GEN_", stringify!($name))));
180
181        /// Returning a `font_map::Font` instance describing the font and its symbols
182        #[allow(
183            clippy::missing_panics_doc,
184            reason = "The panic message is clear enough"
185        )]
186        #[must_use]
187        pub fn load_font() -> font_map::font::Font {
188            font_map::font::Font::new($name::FONT_BYTES).expect("Bundled font was invalid!")
189        }
190    };
191}
font_map/lib.rs

font_map/
lib.rs
