hl_lite/lib.rs
1//! A tiny, dependency-free syntax highlighter.
2//!
3//! `hl-lite` turns a source string into a flat list of [`Span`]s, each tagged
4//! with a [`Kind`] that maps to a CSS class (`hl-keyword`, `hl-string`, …).
5//! It is built for documentation sites: twelve hand-written byte-level lexers,
6//! no regex engine, no C, no dependencies, and a few tens of kilobytes of
7//! WebAssembly instead of the megabytes a tree-sitter grammar set costs.
8//!
9//! The lexers are *lexical*, not scope-aware — the same level of fidelity
10//! [highlight.js](https://highlightjs.org) or Prism give you, not a parse
11//! tree. See the crate README for the per-language table of known gaps.
12//!
13//! # Example
14//!
15//! ```
16//! use hl_lite::{highlight, Kind, Lang};
17//!
18//! let lang = Lang::from_slug("rs").unwrap();
19//! let spans = highlight(lang, "let x = 1;");
20//!
21//! assert_eq!(spans[0].kind, Kind::Keyword);
22//! assert_eq!(spans[0].text, "let");
23//! assert_eq!(spans[0].kind.class(), "keyword");
24//!
25//! // The spans always reconstruct the input exactly.
26//! let joined: String = spans.iter().map(|s| s.text).collect();
27//! assert_eq!(joined, "let x = 1;");
28//! ```
29//!
30//! # Guarantees
31//!
32//! * Concatenating every [`Span::text`] reproduces the input byte for byte.
33//! * Spans never split a `char`, so non-ASCII input cannot panic.
34//! * Unterminated strings, comments, heredocs and templates run to the end of
35//! the input instead of panicking or looping.
36//! * Every lexer is a single forward pass: highlighting is O(input length).
37
38#![forbid(unsafe_code)]
39#![deny(missing_docs)]
40
41mod bash;
42mod css;
43mod dockerfile;
44mod emit;
45mod html;
46mod js;
47mod json;
48mod markdown;
49mod python;
50mod rust;
51mod toml;
52mod util;
53mod yaml;
54
55/// A language `hl-lite` can highlight.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
57pub enum Lang {
58 /// Rust.
59 Rust,
60 /// Bash / sh / shell sessions.
61 Bash,
62 /// CSS.
63 Css,
64 /// Dockerfile.
65 Dockerfile,
66 /// HTML (also used for XML and SVG).
67 Html,
68 /// JavaScript.
69 JavaScript,
70 /// JSON (tolerates JSONC comments).
71 Json,
72 /// Markdown.
73 Markdown,
74 /// Python.
75 Python,
76 /// TOML.
77 Toml,
78 /// TypeScript.
79 TypeScript,
80 /// YAML.
81 Yaml,
82}
83
84/// Fence slug (and alias) to language. Matched case-insensitively, in order.
85const SLUGS: &[(&str, Lang)] = &[
86 ("rust", Lang::Rust),
87 ("rs", Lang::Rust),
88 ("bash", Lang::Bash),
89 ("sh", Lang::Bash),
90 ("shell", Lang::Bash),
91 ("zsh", Lang::Bash),
92 ("console", Lang::Bash),
93 ("terminal", Lang::Bash),
94 ("css", Lang::Css),
95 ("dockerfile", Lang::Dockerfile),
96 ("docker", Lang::Dockerfile),
97 ("containerfile", Lang::Dockerfile),
98 ("html", Lang::Html),
99 ("htm", Lang::Html),
100 ("xml", Lang::Html),
101 ("svg", Lang::Html),
102 ("javascript", Lang::JavaScript),
103 ("js", Lang::JavaScript),
104 ("jsx", Lang::JavaScript),
105 ("mjs", Lang::JavaScript),
106 ("cjs", Lang::JavaScript),
107 ("json", Lang::Json),
108 ("jsonc", Lang::Json),
109 ("json5", Lang::Json),
110 ("markdown", Lang::Markdown),
111 ("md", Lang::Markdown),
112 ("mdx", Lang::Markdown),
113 ("python", Lang::Python),
114 ("py", Lang::Python),
115 ("py3", Lang::Python),
116 ("toml", Lang::Toml),
117 ("typescript", Lang::TypeScript),
118 ("ts", Lang::TypeScript),
119 ("tsx", Lang::TypeScript),
120 ("yaml", Lang::Yaml),
121 ("yml", Lang::Yaml),
122];
123
124impl Lang {
125 /// Resolve a fence slug or common alias, case-insensitively.
126 ///
127 /// Returns `None` for anything unknown, so callers can fall back to
128 /// rendering the block as plain text.
129 ///
130 /// ```
131 /// # use hl_lite::Lang;
132 /// assert_eq!(Lang::from_slug("TSX"), Some(Lang::TypeScript));
133 /// assert_eq!(Lang::from_slug("brainfuck"), None);
134 /// ```
135 #[must_use]
136 pub fn from_slug(slug: &str) -> Option<Lang> {
137 SLUGS
138 .iter()
139 .find(|(name, _)| name.eq_ignore_ascii_case(slug))
140 .map(|&(_, lang)| lang)
141 }
142
143 /// Guess the language of a file name or path.
144 ///
145 /// Uses the extension, falling back to the base name for the files that
146 /// carry their language there rather than in a suffix.
147 ///
148 /// ```
149 /// # use hl_lite::Lang;
150 /// assert_eq!(Lang::from_path("src/main.rs"), Some(Lang::Rust));
151 /// assert_eq!(Lang::from_path("Dockerfile"), Some(Lang::Dockerfile));
152 /// assert_eq!(Lang::from_path("LICENSE"), None);
153 /// ```
154 #[must_use]
155 pub fn from_path(path: &str) -> Option<Lang> {
156 let name = path
157 .rsplit(['/', '\\'])
158 .next()
159 .unwrap_or(path)
160 .trim_end_matches(['.', ' ']);
161
162 if let Some((_, ext)) = name.rsplit_once('.')
163 && let Some(lang) = Lang::from_slug(ext)
164 {
165 return Some(lang);
166 }
167 // `Dockerfile`, `Containerfile`, and variants like `Dockerfile.ci`.
168 let stem = name.split('.').next().unwrap_or(name);
169 (stem.eq_ignore_ascii_case("dockerfile") || stem.eq_ignore_ascii_case("containerfile"))
170 .then_some(Lang::Dockerfile)
171 }
172
173 /// The canonical slug for this language.
174 #[must_use]
175 pub fn slug(self) -> &'static str {
176 match self {
177 Lang::Rust => "rust",
178 Lang::Bash => "bash",
179 Lang::Css => "css",
180 Lang::Dockerfile => "dockerfile",
181 Lang::Html => "html",
182 Lang::JavaScript => "javascript",
183 Lang::Json => "json",
184 Lang::Markdown => "markdown",
185 Lang::Python => "python",
186 Lang::Toml => "toml",
187 Lang::TypeScript => "typescript",
188 Lang::Yaml => "yaml",
189 }
190 }
191}
192
193/// What a [`Span`] of source is.
194///
195/// The variants are deliberately generic: they are render targets, not a
196/// grammar. Each language maps its own constructs onto the closest one.
197#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
198pub enum Kind {
199 /// Anything unclassified: whitespace, plain identifiers, prose.
200 Plain,
201 /// Language keyword (`fn`, `if`, `@media`, `FROM`).
202 Keyword,
203 /// String, character and regex literal; also fenced code in Markdown.
204 String,
205 /// Comment.
206 Comment,
207 /// Numeric literal (and TOML/YAML dates).
208 Number,
209 /// Type name.
210 Type,
211 /// Function or macro name at a call or definition site.
212 Function,
213 /// Attribute / annotation / decorator (`#[derive]`, `@app.route`, HTML
214 /// attribute names, shell flags).
215 Attribute,
216 /// Key of a key/value pair (CSS property, JSON/TOML/YAML key).
217 Property,
218 /// Markup tag name, TOML table header, CSS selector.
219 Tag,
220 /// Operator.
221 Operator,
222 /// Bracket, comma, separator, list marker.
223 Punctuation,
224 /// Literal constant (`true`, `null`, `#fff`, Rust lifetimes).
225 Constant,
226 /// Variable reference (`$PATH`, `var(--x)`, YAML anchors).
227 Variable,
228}
229
230impl Kind {
231 /// The CSS class suffix for this kind, e.g. `Keyword` → `"keyword"`.
232 ///
233 /// Renderers use it as `hl-{class}`.
234 #[must_use]
235 pub fn class(self) -> &'static str {
236 match self {
237 Kind::Plain => "plain",
238 Kind::Keyword => "keyword",
239 Kind::String => "string",
240 Kind::Comment => "comment",
241 Kind::Number => "number",
242 Kind::Type => "type",
243 Kind::Function => "function",
244 Kind::Attribute => "attribute",
245 Kind::Property => "property",
246 Kind::Tag => "tag",
247 Kind::Operator => "operator",
248 Kind::Punctuation => "punctuation",
249 Kind::Constant => "constant",
250 Kind::Variable => "variable",
251 }
252 }
253}
254
255/// A classified slice of the input.
256#[derive(Debug, Clone, Copy, PartialEq, Eq)]
257pub struct Span<'a> {
258 /// What the slice is.
259 pub kind: Kind,
260 /// The slice itself, borrowed from the input.
261 pub text: &'a str,
262}
263
264/// Highlight `src` as `lang`.
265///
266/// Adjacent spans of the same kind are merged, and the concatenation of every
267/// [`Span::text`] is exactly `src`.
268#[must_use]
269pub fn highlight(lang: Lang, src: &str) -> Vec<Span<'_>> {
270 let mut out = emit::Emit::new(src);
271 match lang {
272 Lang::Rust => rust::lex(&mut out),
273 Lang::Bash => bash::lex(&mut out),
274 Lang::Css => css::lex(&mut out),
275 Lang::Dockerfile => dockerfile::lex(&mut out),
276 Lang::Html => html::lex(&mut out),
277 Lang::JavaScript => js::lex(&mut out, false),
278 Lang::TypeScript => js::lex(&mut out, true),
279 Lang::Json => json::lex(&mut out),
280 Lang::Markdown => markdown::lex(&mut out),
281 Lang::Python => python::lex(&mut out),
282 Lang::Toml => toml::lex(&mut out),
283 Lang::Yaml => yaml::lex(&mut out),
284 }
285 out.finish()
286}