nf-icons 0.1.0

Compile-time Nerd Font glyph lookup proc-macro.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# `nf-icons`: Compile-time [Nerd Font](https://www.nerdfonts.com) glyph resolver

This crate provides the `nf!` procedural macro that resolves a glyph name as a string literal at compile time.

## Usage

Run `cargo add nf-icons` or add the following to your `Cargo.toml`. MSRV is `1.85` (Rust edition 2024):

```toml
[dependencies]
nf-icons = "0.1"
```

`nf-icons 0.1` bundles Nerd Fonts `v3.4.0` glyph data. Each new Nerd Fonts release
ships as a new breaking-change version of this crate.

Use the `nf!` macro to resolve glyph names:

```rust
use nf_icons::nf;

println!("{} close", nf!("nf-fa-xmark"));
println!("{} folder", nf!("nf-fa-folder"));
println!("{} rust", nf!("nf-dev-rust"));
```

To discover available glyphs and their names, visit the
[Nerd Fonts cheat sheet](https://www.nerdfonts.com/cheat-sheet). Once you find
a glyph, click **Copy Class Name** — the string it copies (for example,
`nf-fa-xmark`) is exactly the key `nf!` expects. The `nf-` prefix is required
so the cheat-sheet output works without editing.

Because `nf!(...)` expands to a `&'static str`, it works anywhere a string
literal does — including `const` and `static` items:

```rust
# use nf_icons::nf;

const TAB_ICONS: &[(&str, &str)] = &[
    ("files",  nf!("nf-cod-files")),
    ("search", nf!("nf-cod-search")),
    ("git",    nf!("nf-cod-source_control")),
];
```

Unknown glyph names produce a `compile_error!` that looks like:

```text
error: Unknown Nerd Font glyph `nf-fa-xmarkk`. Did you mean one of: `nf-fa-xmark`, `nf-md-marker`, `nf-oct-x_mark`?
 --> src/main.rs:4:24
  |
4 |     let close = nf!("nf-fa-xmarkk");
  |                        ^^^^^^^^^^^^^
```

**Note:** This crate does not ship any font. You need a Nerd Font installed
and selected in whatever renders the output (terminal, editor, GUI toolkit).

## Why a procedural macro?

The glyph table — roughly 10k entries from the current Nerd Fonts release —
is baked into a perfect hash map (`phf`) when `nf-icons` itself is compiled.
At your crate's compile time the macro performs an `O(1)` lookup and expands
to a plain string literal, so there is no runtime cost, no embedded table in
your binary beyond the glyphs you actually reference, and no risk of mistyping
a glyph name and only discovering it after shipping.

## How to update glyph data

Glyph names and codepoints are generated from the upstream
[`glyphnames.json`](https://github.com/ryanoasis/nerd-fonts/blob/master/glyphnames.json)
shipped with each Nerd Fonts release. To refresh against a newer release,
update `include/glyphs.json` (the `.justfile` has an `update-glyphs` recipe
that fetches the latest copy) and rebuild — `build.rs` will regenerate the
perfect hash map.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)

at your option.