Add YamlLoader::load_from_str_with_markers to provide AST with source markers

fixes chyh1990#103, replaces chyh1990#105

The new function produces an alternative representation for YAML
documents where each YAML node is paired with a `Marker` to indicate the
corresponding line and column in the source markup. The new
representation takes the form of two new types, `Node` and `YamlMarked`.

`Node` is a pair of `YamlMarked` and `Marker`.

`YamlMarked` mimics the existing `Yaml` enum; the difference is that array
elements and hash keys and values are `Node` values instead of `Yaml` or
`YamlMarked` values. I created a new enum because I did not know of a way
to switch child nodes in `Yaml` between `Yaml` and `Node` types without
backward-incompatible changes to the `Yaml` enum.

The the behavior of the existing `load_from_str` function and `Yaml`
enum are unchanged, so pattern matching on results from `load_from_str`
will work as before.

To ensure consistent behavior for the `Node` and `Yaml` I moved methods
from the `impl Yaml` block to a new trait called `YamlNode` which is
implemented by `Yaml`, `Node`, and `YamlMarked`. This is a breaking
change since it means that consumers will have to import `YamlNode` to
use methods like `.as_str()` and `.is_array()`.

I want to present this pull request as one proposal. I think there is also
an argument for changing the existing `Yaml` type to incorporate source
location markers instead of maintaining two parallel enums.

While making changes I split up `yaml.rs` into three nested modules.
I can put it back the way it was if that is preferable.

Author: Jesse Hallett

Cargo.toml

@@ -10,7 +10,9 @@ repository = "https://github.com/chyh1990/yaml-rust"
 readme = "README.md"
 
 [dependencies]
+derivative = "1"
 linked-hash-map = ">=0.0.9, <0.6"
 
 [dev-dependencies]
+indoc = "0.3"
 quickcheck = "0.7"

src/lib.rs

@@ -24,7 +24,7 @@
 //! # Examples
 //!
 //! ```
-//! use yaml_rust::{YamlLoader, YamlEmitter};
+//! use yaml_rust::{YamlLoader, YamlEmitter, YamlNode};
 //!
 //! let docs = YamlLoader::load_from_str("[1, 2, 3]").unwrap();
 //! let doc = &docs[0]; // select the first document
@@ -44,6 +44,7 @@
     allow(match_same_arms, should_implement_trait)
 )]
 
+extern crate derivative;
 extern crate linked_hash_map;
 
 pub mod emitter;
@@ -54,8 +55,8 @@ pub mod yaml;
 // reexport key APIs
 pub use emitter::{EmitError, YamlEmitter};
 pub use parser::Event;
-pub use scanner::ScanError;
-pub use yaml::{Yaml, YamlLoader};
+pub use scanner::{Marker, ScanError};
+pub use yaml::{Node, Yaml, YamlLoader, YamlMarked, YamlNode};
 
 #[cfg(test)]
 mod tests {

src/scanner.rs

@@ -18,7 +18,7 @@ pub enum TScalarStyle {
     Foled,
 }
 
-#[derive(Clone, Copy, PartialEq, Debug, Eq)]
+#[derive(Clone, Copy, PartialEq, PartialOrd, Debug, Eq, Ord, Hash)]
 pub struct Marker {
     index: usize,
     line: usize,