Reorganize.

src/lib.rs

@@ -6,6 +6,8 @@
 
 //! # Humanize
 //!
+//! Make your user interface more human friendly!
+//!
 //! This library provides functionality for both formatting values
 //! into human friendly forms as well as parsing human input to get
 //! back likely values.
@@ -21,6 +23,38 @@
 //!
 //! Contributions extending our functionality are welcome, as are
 //! contributions that add support for additional languages.
+//!
+//! # Human-friendly Parsing
+//!
+//! When dealing with humans, you often want them to be able to
+//! input values in a flexible manner. For example, you might want
+//! to be able to input a `bool` using text like `"on"`, `"off"`,
+//! `"yes"`, `"no"` or perhaps even `"nope"`.
+//!
+//! First, you'll want to construct a parser:
+//!
+//! ```
+//! use humanize::HumanizedParser;
+//!
+//! let parser = HumanizedParser::new();
+//! ```
+//!
+//! Then, you can use that parser to examine some input. In the typical
+//! case, you can invoke a type-specific parse method like `parse_boolean`.
+//! You may also limit the matchers run to a specific language. (Here,
+//! we don't limit the languages, so we pass `Default::default()`.)
+//!
+//! ```
+//! # use humanize::HumanizedParser;
+//! #
+//! # let parser = HumanizedParser::new();
+//! let enabled = parser.parse_boolean("on", Default::default()).unwrap_or(false);
+//! assert_eq!(enabled, true);
+//! ```
+//!
+//! The parser stores no state related to an actual parse operation. It
+//! simply stores the matchers which have been registered, so this can
+//! and should be cached and used across multiple parse operations.
 
 #![warn(missing_docs)]
 #![deny(trivial_numeric_casts,
@@ -30,4 +64,7 @@
 #[macro_use]
 extern crate language_tags;
 
-pub mod parse;
+pub mod matchers;
+mod parser;
+
+pub use parser::HumanizedParser;

src/parse/english/boolean.rs → src/matchers/english/boolean.rs

@@ -10,10 +10,11 @@
 // This is just a dummy example for now. It should clearly be
 // much better and actually work correctly. :)
 
-use parse::*;
+use matchers::*;
+use parser::HumanizedParser;
 
 #[allow(missing_docs)]
-pub fn register(parser: &mut Parser) {
+pub fn register(parser: &mut HumanizedParser) {
     parser.register_matcher(Matcher {
         name: "English Booleans",
         language: langtag!(en),

src/parse/english/mod.rs → src/matchers/english/mod.rs

@@ -6,12 +6,12 @@
 
 //! English Humanization
 
-use parse::Parser;
+use parser::HumanizedParser;
 
 pub mod boolean;
 // pub mod ordinal;
 
 /// Register all of the English language matchers.
-pub fn register(parser: &mut Parser) {
+pub fn register(parser: &mut HumanizedParser) {
     boolean::register(parser);
 }

src/matchers/mod.rs

@@ -0,0 +1,70 @@
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! # Register Matchers
+//!
+//! Matchers can be provided to augment the built-in parsing and
+//! recognition capabilities of this library.
+//!
+//! _We will expand upon this in the future once our own infrastructure
+//! for doing matchers well is in place._
+//!
+//! ...
+
+use language_tags::LanguageTag;
+use std::time::{Duration, Instant};
+
+pub mod english;
+
+#[allow(missing_docs)]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ValueType {
+    Boolean,
+    Duration,
+    Instant,
+    Integer,
+    Ordinal,
+}
+
+#[allow(missing_docs)]
+#[derive(Debug, PartialEq)]
+pub enum HumanValue {
+    Boolean(bool),
+    Duration(Duration),
+    Instant(Instant),
+    Integer(i64),
+    Ordinal(i64),
+}
+
+/// A possible match for a value within some text.
+///
+/// A `Match` result is obtained by calling [`parse`] on
+/// some input text. They are created by [`Matcher`]s.
+///
+/// [`parse`]: ../struct.HumanizedParser.html#method.parse
+/// [`Matcher`]: struct.Matcher.html
+#[derive(Debug)]
+pub struct Match {
+    /// The value determined for this match.
+    pub value: HumanValue,
+
+    /// Strength of the match.
+    ///
+    /// This is useful when there is more than one possible match.
+    ///
+    /// TODO: Should be this be a percentage? What is the range?
+    /// Should it be an enum with values like 'Likely', 'Unlikely',
+    /// and 'Certain'?
+    pub weight: i32,
+}
+
+#[allow(missing_docs)]
+pub struct Matcher<'m> {
+    pub name: &'m str,
+    pub language: LanguageTag,
+    pub result_type: ValueType,
+    pub matcher: Box<Fn(&str) -> Option<Match>>,
+}