third_party/rust/phf_codegen/README.md

   1 # Rust-PHF
   2
   3 [![CI](https://github.com/rust-phf/rust-phf/actions/workflows/ci.yml/badge.svg)](https://github.com/rust-phf/rust-phf/actions/workflows/ci.yml) [![Latest Version](https://img.shields.io/crates/v/phf.svg)](https://crates.io/crates/phf)
   4
   5 [Documentation](https://docs.rs/phf)
   6
   7 Rust-PHF is a library to generate efficient lookup tables at compile time using
   8 [perfect hash functions](http://en.wikipedia.org/wiki/Perfect_hash_function).
   9
  10 It currently uses the
  11 [CHD algorithm](http://cmph.sourceforge.net/papers/esa09.pdf) and can generate
  12 a 100,000 entry map in roughly .4 seconds.
  13
  14 MSRV (minimum supported rust version) is Rust 1.60.
  15
  16 ## Usage
  17
  18 PHF data structures can be constructed via either the procedural
  19 macros in the `phf_macros` crate or code generation supported by the
  20 `phf_codegen` crate.
  21
  22 To compile the `phf` crate with a dependency on
  23 libcore instead of libstd, enabling use in environments where libstd
  24 will not work, set `default-features = false` for the dependency:
  25
  26 ```toml
  27 [dependencies]
  28 # to use `phf` in `no_std` environments
  29 phf = { version = "0.11", default-features = false }
  30 ```
  31
  32 ### phf_macros
  33
  34 ```rust
  35 use phf::phf_map;
  36
  37 #[derive(Clone)]
  38 pub enum Keyword {
  39     Loop,
  40     Continue,
  41     Break,
  42     Fn,
  43     Extern,
  44 }
  45
  46 static KEYWORDS: phf::Map<&'static str, Keyword> = phf_map! {
  47     "loop" => Keyword::Loop,
  48     "continue" => Keyword::Continue,
  49     "break" => Keyword::Break,
  50     "fn" => Keyword::Fn,
  51     "extern" => Keyword::Extern,
  52 };
  53
  54 pub fn parse_keyword(keyword: &str) -> Option<Keyword> {
  55     KEYWORDS.get(keyword).cloned()
  56 }
  57 ```
  58
  59 ```toml
  60 [dependencies]
  61 phf = { version = "0.11", features = ["macros"] }
  62 ```
  63
  64 #### Note
  65
  66 Currently, the macro syntax has some limitations and may not
  67 work as you want. See [#183] or [#196] for example.
  68
  69 [#183]: https://github.com/rust-phf/rust-phf/issues/183
  70 [#196]: https://github.com/rust-phf/rust-phf/issues/196
  71
  72 ### phf_codegen
  73
  74 To use `phf_codegen` on build.rs, you have to add dependencies under `[build-dependencies]`:
  75
  76 ```toml
  77 [build-dependencies]
  78 phf = { version = "0.11.1", default-features = false }
  79 phf_codegen = "0.11.1"
  80 ```
  81
  82 Then put code on build.rs:
  83
  84 ```rust
  85 use std::env;
  86 use std::fs::File;
  87 use std::io::{BufWriter, Write};
  88 use std::path::Path;
  89
  90 fn main() {
  91     let path = Path::new(&env::var("OUT_DIR").unwrap()).join("codegen.rs");
  92     let mut file = BufWriter::new(File::create(&path).unwrap());
  93
  94     write!(
  95         &mut file,
  96         "static KEYWORDS: phf::Map<&'static str, Keyword> = {}",
  97         phf_codegen::Map::new()
  98             .entry("loop", "Keyword::Loop")
  99             .entry("continue", "Keyword::Continue")
 100             .entry("break", "Keyword::Break")
 101             .entry("fn", "Keyword::Fn")
 102             .entry("extern", "Keyword::Extern")
 103             .build()
 104     )
 105     .unwrap();
 106     write!(&mut file, ";\n").unwrap();
 107 }
 108 ```
 109
 110 and lib.rs:
 111
 112 ```rust
 113 #[derive(Clone)]
 114 enum Keyword {
 115     Loop,
 116     Continue,
 117     Break,
 118     Fn,
 119     Extern,
 120 }
 121
 122 include!(concat!(env!("OUT_DIR"), "/codegen.rs"));
 123
 124 pub fn parse_keyword(keyword: &str) -> Option<Keyword> {
 125     KEYWORDS.get(keyword).cloned()
 126 }
 127 ```