diff --git a/phf/src/lib.rs b/phf/src/lib.rs index b7ebd4cc..d9c9a527 100644 --- a/phf/src/lib.rs +++ b/phf/src/lib.rs @@ -1,38 +1,8 @@ //! Compile time optimized maps and sets. //! -//! Keys can be string literals, byte string literals, byte literals, char -//! literals, or any of the fixed-size isizeegral types. -//! -//! # Examples -//! -//! ```rust -//! #![feature(plugin)] -//! #![plugin(phf_macros)] -//! -//! extern crate phf; -//! -//! #[derive(Clone)] -//! pub enum Keyword { -//! Loop, -//! Continue, -//! Break, -//! Fn, -//! Extern, -//! } -//! -//! static KEYWORDS: phf::Map<&'static str, Keyword> = phf_map! { -//! "loop" => Keyword::Loop, -//! "continue" => Keyword::Continue, -//! "break" => Keyword::Break, -//! "fn" => Keyword::Fn, -//! "extern" => Keyword::Extern, -//! }; -//! -//! pub fn parse_keyword(keyword: &str) -> Option { -//! KEYWORDS.get(keyword).cloned() -//! } -//! # fn main() {} -//! ``` +//! PHF data structures can be generated via the syntax extensions in the +//! `phf_macros` crate or via code generation in the `phf_codegen` crate. See +//! the documentation of those crates for more details. #![doc(html_root_url="https://sfackler.github.io/rust-phf/doc")] #![feature(core, no_std)] #![warn(missing_docs)] diff --git a/phf/src/map.rs b/phf/src/map.rs index 43963ddb..2bdd8dbd 100644 --- a/phf/src/map.rs +++ b/phf/src/map.rs @@ -10,27 +10,11 @@ use phf_shared; /// An immutable map constructed at compile time. /// -/// `Map`s may be created with the `phf_map` macro: -/// -/// ```rust -/// #![feature(plugin)] -/// #![plugin(phf_macros)] -/// -/// extern crate phf; -/// -/// static MY_MAP: phf::Map<&'static str, isize> = phf_map! { -/// "hello" => 10, -/// "world" => 11, -/// }; -/// -/// # fn main() {} -/// ``` -/// /// ## Note /// /// The fields of this struct are public so that they may be initialized by the -/// `phf_map` macro. They are subject to change at any time and should never -/// be accessed directly. +/// `phf_map!` macro and code generation. They are subject to change at any +/// time and should never be accessed directly. pub struct Map { #[doc(hidden)] pub key: u64, diff --git a/phf/src/ordered_map.rs b/phf/src/ordered_map.rs index 1fd3d94c..450923ef 100644 --- a/phf/src/ordered_map.rs +++ b/phf/src/ordered_map.rs @@ -14,27 +14,11 @@ use phf_shared; /// Unlike a `Map`, iteration order is guaranteed to match the definition /// order. /// -/// `OrderedMap`s may be created with the `phf_ordered_map` macro: -/// -/// ```rust -/// #![feature(plugin)] -/// #![plugin(phf_macros)] -/// -/// extern crate phf; -/// -/// static MY_MAP: phf::OrderedMap<&'static str, isize> = phf_ordered_map! { -/// "hello" => 10, -/// "world" => 11, -/// }; -/// -/// # fn main() {} -/// ``` -/// /// ## Note /// /// The fields of this struct are public so that they may be initialized by the -/// `phf_ordered_map` macro. They are subject to change at any time and should -/// never be accessed directly. +/// `phf_ordered_map!` macro and code generation. They are subject to change at +/// any time and should never be accessed directly. pub struct OrderedMap { #[doc(hidden)] pub key: u64, diff --git a/phf/src/ordered_set.rs b/phf/src/ordered_set.rs index 3b83b7e0..0d538a2b 100644 --- a/phf/src/ordered_set.rs +++ b/phf/src/ordered_set.rs @@ -11,27 +11,11 @@ use {PhfHash, OrderedMap}; /// Unlike a `Set`, iteration order is guaranteed to match the definition /// order. /// -/// `OrderedSet`s may be created with the `phf_ordered_set` macro: -/// -/// ```rust -/// #![feature(plugin)] -/// #![plugin(phf_macros)] -/// -/// extern crate phf; -/// -/// static MY_SET: phf::OrderedSet<&'static str> = phf_ordered_set! { -/// "hello", -/// "world", -/// }; -/// -/// # fn main() {} -/// ``` -/// /// ## Note /// /// The fields of this struct are public so that they may be initialized by the -/// `phf_ordered_set` macro. They are subject to change at any time and should -/// never be accessed directly. +/// `phf_ordered_set!` macro and code generation. They are subject to change at +/// any time and should never be accessed directly. pub struct OrderedSet { #[doc(hidden)] pub map: OrderedMap, diff --git a/phf/src/set.rs b/phf/src/set.rs index 0cb26ede..ecd8cda5 100644 --- a/phf/src/set.rs +++ b/phf/src/set.rs @@ -10,27 +10,11 @@ use Map; /// An immutable set constructed at compile time. /// -/// `Set`s may be created with the `phf_set` macro: -/// -/// ```rust -/// #![feature(plugin)] -/// #![plugin(phf_macros)] -/// -/// extern crate phf; -/// -/// static MY_SET: phf::Set<&'static str> = phf_set! { -/// "hello", -/// "world", -/// }; -/// -/// # fn main() {} -/// ``` -/// /// ## Note /// /// The fields of this struct are public so that they may be initialized by the -/// `phf_set` macro. They are subject to change at any time and should never be -/// accessed directly. +/// `phf_set!` macro and code generation. They are subject to change at any +/// time and should never be accessed directly. pub struct Set { #[doc(hidden)] pub map: Map diff --git a/phf_macros/src/lib.rs b/phf_macros/src/lib.rs index 519f6400..c65801f7 100644 --- a/phf_macros/src/lib.rs +++ b/phf_macros/src/lib.rs @@ -1,6 +1,35 @@ -//! Compiler plugin for Rust-PHF +//! Compiler plugin defining macros that create PHF data structures. //! -//! See the documentation for the `phf` crate for more details. +//! # Example +//! +//! ```rust +//! #![feature(plugin)] +//! #![plugin(phf_macros)] +//! +//! extern crate phf; +//! +//! #[derive(Clone)] +//! pub enum Keyword { +//! Loop, +//! Continue, +//! Break, +//! Fn, +//! Extern, +//! } +//! +//! static KEYWORDS: phf::Map<&'static str, Keyword> = phf_map! { +//! "loop" => Keyword::Loop, +//! "continue" => Keyword::Continue, +//! "break" => Keyword::Break, +//! "fn" => Keyword::Fn, +//! "extern" => Keyword::Extern, +//! }; +//! +//! pub fn parse_keyword(keyword: &str) -> Option { +//! KEYWORDS.get(keyword).cloned() +//! } +//! # fn main() {} +//! ``` #![doc(html_root_url="http://sfackler.github.io/rust-phf/doc")] #![feature(plugin_registrar, quote, rustc_private, env, std_misc)] @@ -30,6 +59,7 @@ use util::{Entry, Key}; use util::{create_map, create_set, create_ordered_map, create_ordered_set}; pub mod util; +mod macros; #[plugin_registrar] #[doc(hidden)] diff --git a/phf_macros/src/macros.rs b/phf_macros/src/macros.rs new file mode 100644 index 00000000..83ca31f4 --- /dev/null +++ b/phf_macros/src/macros.rs @@ -0,0 +1,87 @@ +/// Constructs a `phf::Map` at compile time. +/// +/// # Examples +/// +/// ```rust +/// #![feature(plugin)] +/// #![plugin(phf_macros)] +/// +/// extern crate phf; +/// +/// static MY_MAP: phf::Map<&'static str, i32> = phf_map! { +/// "hello" => 10, +/// "world" => 11, +/// }; +/// +/// # fn main() {} +/// ``` +#[macro_export] +macro_rules! phf_map { + ($($key:expr => $value:expr),*) => {/* ... */} +} + +/// Constructs a `phf::Set` at compile time. +/// +/// # Examples +/// +/// ```rust +/// #![feature(plugin)] +/// #![plugin(phf_macros)] +/// +/// extern crate phf; +/// +/// static MY_SET: phf::Set<&'static str> = phf_set! { +/// "hello", +/// "world", +/// }; +/// +/// # fn main() {} +/// ``` +#[macro_export] +macro_rules! phf_set { + ($($entry:expr),*) => {/* ... */} +} + +/// Constructs a `phf::OrderedMap` at compile time. +/// +/// # Examples +/// +/// ```rust +/// #![feature(plugin)] +/// #![plugin(phf_macros)] +/// +/// extern crate phf; +/// +/// static MY_MAP: phf::OrderedMap<&'static str, i32> = phf_ordered_map! { +/// "hello" => 10, +/// "world" => 11, +/// }; +/// +/// # fn main() {} +/// ``` +#[macro_export] +macro_rules! phf_ordered_map { + ($($key:expr => $value:expr),*) => {/* ... */} +} + +/// Constructs a `phf::OrderedSet` at compile time. +/// +/// # Examples +/// +/// ```rust +/// #![feature(plugin)] +/// #![plugin(phf_macros)] +/// +/// extern crate phf; +/// +/// static MY_SET: phf::OrderedSet<&'static str> = phf_ordered_set! { +/// "hello", +/// "world", +/// }; +/// +/// # fn main() {} +/// ``` +#[macro_export] +macro_rules! phf_ordered_set { + ($($entry:expr),*) => {/* ... */} +}