Skip to main content

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}