From 8b71a9a9b9ac9ecf579975327af18f0b6261bbbc Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Sun, 22 Feb 2015 11:45:14 -0800 Subject: [PATCH] Add docs to phf_codegen --- .travis.yml | 1 + phf_codegen/src/lib.rs | 111 +++++++++++++++++++++++++++++++++++++---- 2 files changed, 103 insertions(+), 9 deletions(-) diff --git a/.travis.yml b/.travis.yml index 1c6c428d..ecc6f4b8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,6 +3,7 @@ script: - (cd phf && cargo test) - (cd phf_macros && cargo test) - (cd phf_macros && cargo test --features stats) +- (cd phf_codegen && cargo test) - (cd phf_codegen/test && cargo test) - ./.travis/build_docs.sh after_success: diff --git a/phf_codegen/src/lib.rs b/phf_codegen/src/lib.rs index 62ae052b..bc3ea40d 100644 --- a/phf_codegen/src/lib.rs +++ b/phf_codegen/src/lib.rs @@ -1,22 +1,79 @@ +//! A set of builders to generate Rust source for PHF data structures at +//! compile time. +//! +//! The provided builders are intended to be used in a Cargo build script to +//! generate a Rust source file that will be included in a library at build +//! time. +//! +//! # Examples +//! +//! build.rs +//! +//! ```rust,no_run +//! extern crate phf_codegen; +//! +//! use std::fs::File; +//! use std::io::{BufWriter, Write}; +//! use std::path::AsPath; +//! use std::env; +//! +//! fn main() { +//! let path = env::var_os("OUT_DIR").unwrap().as_path().join("codegen.rs"); +//! let mut file = BufWriter::new(File::create(&path).unwrap()); +//! +//! write!(&mut file, "static KEYWORDS: phf::Map<&'static str, Keyword> = ").unwrap(); +//! phf_codegen::Map::new() +//! .entry("loop", "Keyword::Loop") +//! .entry("continue", "Keyword::Continue") +//! .entry("break", "Keyword::Break") +//! .entry("fn", "Keyword::Fn") +//! .entry("extern", "Keyword::Extern") +//! .build(&mut file) +//! .unwrap(); +//! write!(&mut file, ";\n").unwrap(); +//! } +//! ``` +//! +//! lib.rs +//! +//! ```ignore +//! extern crate phf; +//! +//! #[derive(Clone)] +//! enum Keyword { +//! Loop, +//! Continue, +//! Break, +//! Fn, +//! Extern, +//! } +//! +//! include!(concat!(env!("OUT_DIR"), "/codegen.rs")); +//! +//! pub fn parse_keyword(keyword: &str) -> Option { +//! KEYWORDS.get(keyword).cloned() +//! } +//! ``` #![feature(io)] extern crate phf_shared; extern crate phf_generator; -use std::io; -use std::io::prelude::*; +use phf_shared::PhfHash; use std::collections::HashSet; -use std::hash::Hash; use std::fmt; +use std::hash::Hash; +use std::io; +use std::io::prelude::*; -pub use phf_shared::PhfHash; - -pub struct Map { +/// A builder for the `phf::Map` type. +pub struct Map { keys: Vec, values: Vec, } impl Map { + /// Creates a new `phf::Map` builder. pub fn new() -> Map { Map { keys: vec![], @@ -24,12 +81,20 @@ impl Map { } } + /// Adds an entry to the builder. + /// + /// `value` will be written exactly as provided in the constructed source. pub fn entry(&mut self, key: K, value: &str) -> &mut Map { self.keys.push(key); self.values.push(value.to_string()); self } + /// Constructs a `phf::Map`, outputting Rust source to the provided writer. + /// + /// # Panics + /// + /// Panics if there are any duplicate keys. pub fn build(&self, w: &mut W) -> io::Result<()> { let mut set = HashSet::new(); for key in &self.keys { @@ -52,22 +117,30 @@ impl Map { } } -pub struct Set { +/// A builder for the `phf::Set` type. +pub struct Set { map: Map } impl Set { + /// Constructs a new `phf::Set` builder. pub fn new() -> Set { Set { map: Map::new() } } + /// Adds an entry to the builder. pub fn entry(&mut self, entry: T) -> &mut Set { self.map.entry(entry, "()"); self } + /// Constructs a `phf::Set`, outputting Rust source to the provided writer. + /// + /// # Panics + /// + /// Panics if there are any duplicate entries. pub fn build(&self, w: &mut W) -> io::Result<()> { try!(write!(w, "::phf::Set {{ map: ")); try!(self.map.build(w)); @@ -75,12 +148,14 @@ impl Set { } } -pub struct OrderedMap { +/// A builder for the `phf::OrderedMap` type. +pub struct OrderedMap { keys: Vec, values: Vec, } impl OrderedMap { + /// Constructs a enw `phf::OrderedMap` builder. pub fn new() -> OrderedMap { OrderedMap { keys: vec![], @@ -88,12 +163,21 @@ impl OrderedMap { } } + /// Adds an entry to the builder. + /// + /// `value` will be written exactly as provided in the constructed source. pub fn entry(&mut self, key: K, value: &str) -> &mut OrderedMap { self.keys.push(key); self.values.push(value.to_string()); self } + /// Constructs a `phf::OrderedMap`, outputting Rust source to the provided + /// writer. + /// + /// # Panics + /// + /// Panics if there are any duplicate keys. pub fn build(&self, w: &mut W) -> io::Result<()> { let mut set = HashSet::new(); for key in &self.keys { @@ -120,22 +204,31 @@ impl OrderedMap { } } -pub struct OrderedSet { +/// A builder for the `phf::OrderedSet` type. +pub struct OrderedSet { map: OrderedMap } impl OrderedSet { + /// Constructs a new `phf::OrderedSet` builder. pub fn new() -> OrderedSet { OrderedSet { map: OrderedMap::new() } } + /// Adds an entry to the builder. pub fn entry(&mut self, entry: T) -> &mut OrderedSet { self.map.entry(entry, "()"); self } + /// Constructs a `phf::OrderedSet`, outputting Rust source to the provided + /// writer. + /// + /// # Panics + /// + /// Panics if there are any duplicate entries. pub fn build(&self, w: &mut W) -> io::Result<()> { try!(write!(w, "::phf::OrderedSet {{ map: ")); try!(self.map.build(w));