Add documentation and examples

This commit is contained in:
Alex Crichton 2014-06-20 17:30:08 -07:00
parent 019cd4122b
commit 3bbf216491
3 changed files with 123 additions and 3 deletions

View file

@ -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)

View file

@ -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 {

View file

@ -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 }
}
}