From 3bbf216491b01a72398c26689c9ea14a5810adfc Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Fri, 20 Jun 2014 17:30:08 -0700
Subject: Add documentation and examples
---
Makefile | 6 ++++-
src/parser.rs | 45 +++++++++++++++++++++++++++++++++++
src/toml.rs | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
3 files changed, 123 insertions(+), 3 deletions(-)
diff --git a/Makefile b/Makefile
index 80eece3..c06948b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
RUSTC := rustc
+RUSTDOC := rustdoc
BUILD := build
LIB := $(BUILD)/$(shell $(RUSTC) --crate-file-name src/toml.rs)
TEST := $(BUILD)/tomltest
@@ -12,11 +13,14 @@ $(LIB): src/toml.rs
@mkdir -p $(@D)
$(RUSTC) -O $< --out-dir $(@D) --dep-info
-check: $(TEST)
+check: $(TEST) doctest
$(TEST)
$(TEST): src/toml.rs
$(RUSTC) $< --test -o $@ --dep-info
+doctest: $(LIB)
+ $(RUSTDOC) --test -L $(BUILD) src/toml.rs
+
clean:
rm -rf $(BUILD)
diff --git a/src/parser.rs b/src/parser.rs
index dac3e28..96048b4 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -5,21 +5,58 @@ use std::str;
use {Array, Table, Value, String, Float, Integer, Boolean, Datetime};
+/// Parser for converting a string to a TOML `Value` instance.
+///
+/// This parser contains the string slice that is being parsed, and exports the
+/// list of errors which have occurred during parsing.
pub struct Parser<'a> {
input: &'a str,
cur: str::CharOffsets<'a>,
tables_defined: HashSet<String>,
+
+ /// A list of all errors which have occurred during parsing.
+ ///
+ /// Not all parse errors are fatal, so this list is added to as much as
+ /// possible without aborting parsing. If `None` is returned by `parse`, it
+ /// is guaranteed that this list is not empty.
pub errors: Vec<Error>,
}
+/// A structure representing a parse error.
+///
+/// The data in this structure can be used to trace back to the original cause
+/// of the error in order to provide diagnostics about parse errors.
#[deriving(Show)]
pub struct Error {
+ /// The low byte at which this error is pointing at.
pub lo: uint,
+ /// One byte beyond the last character at which this error is pointing at.
pub hi: uint,
+ /// A human-readable description explaining what the error is.
pub desc: String,
}
impl<'a> Parser<'a> {
+ /// Creates a new parser for a string.
+ ///
+ /// The parser can be executed by invoking the `parse` method.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// let toml = r#"
+ /// [test]
+ /// foo = "bar"
+ /// "#;
+ ///
+ /// let mut parser = toml::Parser::new(toml);
+ /// match parser.parse() {
+ /// Some(value) => println!("found toml: {}", value),
+ /// None => {
+ /// println!("parse errors: {}", parser.errors);
+ /// }
+ /// }
+ /// ```
pub fn new(s: &'a str) -> Parser<'a> {
Parser {
input: s,
@@ -76,6 +113,14 @@ impl<'a> Parser<'a> {
}
}
+ /// Executes the parser, parsing the string contained within.
+ ///
+ /// This function will return the `Table` instance if parsing is successful,
+ /// or it will return `None` if any parse error or invalid TOML error
+ /// occurs.
+ ///
+ /// If an error occurs, the `errors` field of this parser can be consulted
+ /// to determine the cause of the parse failure.
pub fn parse(&mut self) -> Option<Table> {
let mut ret = HashMap::new();
loop {
diff --git a/src/toml.rs b/src/toml.rs
index cebdb37..74a4d36 100644
--- a/src/toml.rs
+++ b/src/toml.rs
@@ -1,5 +1,29 @@
+//! A TOML-parsing library
+//!
+//! This library is an implementation in Rust of a parser for TOML configuration
+//! files [1]. It is focused around high quality errors including specific spans
+//! and detailed error messages when things go wrong.
+//!
+//! This implementation currently passes the language agnostic [test suite][2].
+//!
+//! # Example
+//!
+//! ```
+//! let toml = r#"
+//! [test]
+//! foo = "bar"
+//! "#;
+//!
+//! let value = toml::Parser::new(toml).parse().unwrap();
+//! println!("{}", value);
+//! ```
+//!
+//! [1]: https://github.com/mojombo/toml
+//! [2]: https://github.com/BurntSushi/toml-test
+
#![crate_type = "lib"]
#![feature(macro_rules)]
+#![deny(warnings, missing_doc)]
use std::collections::HashMap;
@@ -9,6 +33,9 @@ mod parser;
#[cfg(test)]
mod test;
+/// Representation of a TOML value.
+#[deriving(Show, PartialEq, Clone)]
+#[allow(missing_doc)]
pub enum Value {
String(String),
Integer(i64),
@@ -23,7 +50,8 @@ pub type Array = Vec<Value>;
pub type Table = HashMap<String, Value>;
impl Value {
- fn same_type(&self, other: &Value) -> bool {
+ /// Tests whether this and another value have the same type.
+ pub fn same_type(&self, other: &Value) -> bool {
match (self, other) {
(&String(..), &String(..)) |
(&Integer(..), &Integer(..)) |
@@ -37,7 +65,8 @@ impl Value {
}
}
- fn type_str(&self) -> &'static str {
+ /// Returns a human-readable representation of the type of this value.
+ pub fn type_str(&self) -> &'static str {
match *self {
String(..) => "string",
Integer(..) => "integer",
@@ -48,4 +77,46 @@ impl Value {
Table(..) => "table",
}
}
+
+ /// Extracts the string of this value if it is a string.
+ pub fn as_str<'a>(&'a self) -> Option<&'a str> {
+ match *self { String(ref s) => Some(s.as_slice()), _ => None }
+ }
+
+ /// Extracts the integer value if it is an integer.
+ pub fn as_integer(&self) -> Option<i64> {
+ match *self { Integer(i) => Some(i), _ => None }
+ }
+
+ /// Extracts the float value if it is a float.
+ pub fn as_float(&self) -> Option<f64> {
+ match *self { Float(f) => Some(f), _ => None }
+ }
+
+ /// Extracts the boolean value if it is a boolean.
+ pub fn as_bool(&self) -> Option<bool> {
+ match *self { Boolean(b) => Some(b), _ => None }
+ }
+
+ /// Extracts the datetime value if it is a datetime.
+ ///
+ /// Note that a parsed TOML value will only contain ISO 8601 dates. An
+ /// example date is:
+ ///
+ /// ```notrust
+ /// 1979-05-27T07:32:00Z
+ /// ```
+ pub fn as_datetime<'a>(&'a self) -> Option<&'a str> {
+ match *self { Datetime(ref s) => Some(s.as_slice()), _ => None }
+ }
+
+ /// Extracts the array value if it is an array.
+ pub fn as_slice<'a>(&'a self) -> Option<&'a [Value]> {
+ match *self { Array(ref s) => Some(s.as_slice()), _ => None }
+ }
+
+ /// Extracts the table value if it is a table.
+ pub fn as_table<'a>(&'a self) -> Option<&'a Table> {
+ match *self { Table(ref s) => Some(s), _ => None }
+ }
}
--
cgit v1.2.3