WIP: various unescape strategies.

Author: danielparks

Cargo.lock

@@ -21,7 +21,10 @@ rustdoc-args = ["--cfg", "docsrs"]
 default = []
 unescape = ["_unescape_either", "dep:hashify", "dep:serde_json"]
 unescape_fast = ["_unescape_either", "dep:matchgen", "dep:serde_json"]
+unescape_phf = ["_unescape_either", "entities"]
+unescape_quick = ["_unescape_either", "entities_quick"]
 entities = ["dep:phf", "dep:phf_codegen", "dep:serde_json"]
+entities_quick = ["dep:quickphf", "dep:quickphf_codegen", "dep:serde_json"]
 # Enable iai benchmarks
 iai = []
 # Make internal functions like unescape_fast public for benchmarks.
@@ -33,13 +36,15 @@ _unescape_either = []
 matchgen = { version = "0.4.0", optional = true }
 phf = { version = "0.11.1", default-features = false, optional = true }
 phf_codegen = { version = "0.11.1", optional = true }
+quickphf_codegen = { git = "https://github.com/AlexTMjugador/quickphf.git", branch = "feat/support-array-key-vals", optional = true }
 serde_json = { version = "1.0", optional = true }
 
 [dependencies]
 hashify = { version = "0.2.6", optional = true }
 memchr = "2.5.0"
 pastey = "0.1.0"
 phf = { version = "0.11.1", default-features = false, optional = true }
+quickphf = { git = "https://github.com/AlexTMjugador/quickphf.git", branch = "feat/support-array-key-vals", optional = true }
 
 [dev-dependencies]
 assert2 = "0.3.7"

Cargo.toml

@@ -43,10 +43,28 @@ fn benchmarks(c: &mut Criterion) {
         let input = util::inputs::make_sample(128, entity, "a");
 
         #[cfg(feature = "unescape")]
+        util::benchmark_name!(
+            group,
+            "hashify",
+            (Map::<Hashify>::default(), ContextGeneral),
+            &name,
+            &input
+        );
+
+        #[cfg(feature = "unescape_phf")]
         util::benchmark_name!(
             group,
             "phf",
-            (Phf, ContextGeneral),
+            (Map::<PhfMap>::default(), ContextGeneral),
+            &name,
+            &input
+        );
+
+        #[cfg(feature = "unescape_quick")]
+        util::benchmark_name!(
+            group,
+            "quickphf",
+            (Map::<QuickPhf>::default(), ContextGeneral),
             &name,
             &input
         );
@@ -67,10 +85,28 @@ fn benchmarks(c: &mut Criterion) {
         let input = util::inputs::make_sample(128, entity, "a");
 
         #[cfg(feature = "unescape")]
+        util::benchmark_name!(
+            group,
+            "hashify",
+            (Map::<Hashify>::default(), ContextAttribute),
+            &name,
+            &input
+        );
+
+        #[cfg(feature = "unescape_phf")]
         util::benchmark_name!(
             group,
             "phf",
-            (Phf, ContextAttribute),
+            (Map::<PhfMap>::default(), ContextAttribute),
+            &name,
+            &input
+        );
+
+        #[cfg(feature = "unescape_quick")]
+        util::benchmark_name!(
+            group,
+            "quickphf",
+            (Map::<QuickPhf>::default(), ContextAttribute),
             &name,
             &input
         );

benches/unescape.rs

@@ -16,12 +16,12 @@ macro_rules! iai_benchmarks {
             $(
                 #[cfg(feature = "unescape")]
                 fn [<iai_slow_unescape_ $name>]() -> Cow<'static, str> {
-                    unescape_in((Phf, ContextGeneral), black_box($input))
+                    unescape_in((Map::<PhfMap>::default(), ContextGeneral), black_box($input))
                 }
 
                 #[cfg(feature = "unescape")]
                 fn [<iai_slow_unescape_attribute_ $name>]() -> Cow<'static, str> {
-                    unescape_in((Phf, ContextAttribute), black_box($input))
+                    unescape_in((Map::<PhfMap>::default(), ContextAttribute), black_box($input))
                 }
 
                 #[cfg(feature = "unescape_fast")]

benches/unescape_iai.rs

@@ -14,7 +14,8 @@ fn main() {
     #[cfg(any(
         feature = "unescape_fast",
         feature = "unescape",
-        feature = "entities"
+        feature = "entities",
+        feature = "entities_quick"
     ))]
     let entities = load_entities("entities.json");
 
@@ -29,6 +30,9 @@ fn main() {
 
     #[cfg(feature = "entities")]
     generate_entities_rs(&entities);
+
+    #[cfg(feature = "entities_quick")]
+    generate_entities_quick_rs(&entities);
 }
 
 /// Generate entities.rs file containing all valid HTML entities in a
@@ -94,6 +98,72 @@ fn generate_entities_rs(entities: &[(String, String)]) {
     .unwrap();
 }
 
+/// Generate `entities_quick.rs` file containing all valid HTML entities in a
+/// [`quickphf::PhfMap`]. It also generates documentation with a table of all
+/// the entities and their expansions.
+#[cfg(feature = "entities_quick")]
+fn generate_entities_quick_rs(entities: &[(String, String)]) {
+    use std::env;
+    use std::fs::File;
+    use std::io::{BufWriter, Write};
+    use std::path::Path;
+
+    let out_path =
+        Path::new(&env::var("OUT_DIR").unwrap()).join("entities_quick.rs");
+    let mut out = BufWriter::new(File::create(out_path).unwrap());
+
+    writeln!(out, "\
+        /// A map of all valid HTML entities to their expansions.\n\
+        ///\n\
+        /// The keys of the map are full entity byte strings, e.g. `b\"©\"`, and the\n\
+        /// values are their expansions, e.g. `b\"©\"`.\n\
+        ///\n\
+        /// See the [WHATWG HTML spec][spec] for the canonical list of entities with\n\
+        /// their codepoints and glyphs. The [entities.json][] file linked there is\n\
+        /// used to generate this constant.\n\
+        ///\n\
+        /// [spec]: https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references\n\
+        /// [entities.json]: https://html.spec.whatwg.org/entities.json\n\
+        ///\n\
+        /// Entity                         | Codepoints         | Glyph\n\
+        /// -------------------------------|--------------------|------").unwrap();
+
+    let (keys, values): (Vec<_>, Vec<_>) = entities
+        .iter()
+        .inspect(|(name, glyph)| {
+            // `{:28}` would pad the output inside the backticks.
+            let name = format!("`{name}`");
+
+            let codepoints = glyph
+                .chars()
+                .map(|c| format!("U+{:06X}", u32::from(c)))
+                .collect::<Vec<_>>()
+                .join(", ");
+
+            // Suppress a few inconvenient glyphs. Newline adds an extra line, and
+            // tab causes a clippy warning. Backticks are actually fine, but it’s
+            // correct to escape them.
+            let glyph = match glyph.as_str() {
+                "\n" | "\t" => "",
+                "`" => "\\`",
+                v => v,
+            };
+
+            writeln!(out, "/// {name:30} | {codepoints:18} | {glyph}",)
+                .unwrap();
+        })
+        .map(|(name, glyph)| (name.as_bytes(), glyph.as_bytes()))
+        .unzip();
+
+    writeln!(out, "#[allow(clippy::unreadable_literal)]").unwrap();
+    writeln!(
+        out,
+        "pub static ENTITIES_QUICK: quickphf::PhfMap<&[u8], &[u8]> = {};",
+        quickphf_codegen::build_map(&keys, &values),
+    )
+    .unwrap();
+}
+
 /// Generate `entities_length.rs` file containing constants with the minimum
 /// and maximum entity lengths.
 #[cfg(any(feature = "unescape", feature = "entities"))]
@@ -152,7 +222,7 @@ fn generate_unescape_entity_rs(entities: &[(String, String)]) {
         /// Get expansion or `None` for a candidate HTML entity byte string.\n\
         #[must_use]\n\
         #[allow(clippy::too_many_lines)]\n\
-        fn expand_entity(candidate: &[u8]) -> Option<&[u8]> {{\n\
+        fn expand_entity(candidate: &[u8]) -> Option<&'static [u8]> {{\n\
             hashify::map! {{\n\
                 candidate,\n\
                 &[u8],"

build.rs

@@ -153,3 +153,13 @@ feature! {
     }
     pub use entities::*;
 }
+
+feature! {
+    #![feature = "entities_quick"]
+
+    /// For some reason `rustdoc` doesn’t show the feature flags without `mod`.
+    mod entities_quick {
+        include!(concat!(env!("OUT_DIR"), "/entities_quick.rs"));
+    }
+    pub use entities_quick::*;
+}