Move load_from_* functions in Yaml.

This would make more sense in user code:
```rs
Yaml::load_from_str("foo"); // Explicit that we're parsing YAML
load_from_str("foo"); // Too implicit, too generic, may be from another
                         lib
```

Plus, this mirrors `MarkedYaml`'s behavior.

saphyr/README.md

@@ -28,7 +28,7 @@ cargo add saphyr
 Use `saphyr::YamlLoader` to load YAML documents and access them as `Yaml` objects:
 
 ```rust
-use saphyr::{YamlLoader, YamlEmitter};
+use saphyr::{Yaml, YamlEmitter};
 
 fn main() {
     let s =
@@ -40,7 +40,7 @@ bar:
     - 1
     - 2.0
 ";
-    let docs = YamlLoader::load_from_str(s).unwrap();
+    let docs = Yaml::load_from_str(s).unwrap();
 
     // Multi document support, doc is a yaml::Yaml
     let doc = &docs[0];

saphyr/examples/dump_yaml.rs

@@ -1,4 +1,4 @@
-use saphyr::{load_from_str, Yaml};
+use saphyr::Yaml;
 use std::env;
 use std::fs::File;
 use std::io::prelude::*;
@@ -36,7 +36,7 @@ fn main() {
     let mut s = String::new();
     f.read_to_string(&mut s).unwrap();
 
-    let docs = load_from_str(&s).unwrap();
+    let docs = Yaml::load_from_str(&s).unwrap();
     for doc in &docs {
         println!("---");
         dump_node(doc, 0);

saphyr/src/annotated/marked_yaml.rs

@@ -30,32 +30,32 @@ impl MarkedYaml {
     /// # Errors
     /// Returns `ScanError` when loading fails.
     ///
-    /// [`load_from_str`]: `crate::load_from_str`
+    /// [`load_from_str`]: `Yaml::load_from_str`
     pub fn load_from_str(source: &str) -> Result<Vec<Self>, ScanError> {
         Self::load_from_iter(source.chars())
     }
 
     /// Load the contents of the given iterator as an array of YAML documents.
     ///
-    /// See the function [`load_from_iter`] for more details.
+    /// See the function [`load_from_str`] for more details.
     ///
     /// # Errors
     /// Returns `ScanError` when loading fails.
     ///
-    /// [`load_from_iter`]: `crate::load_from_iter`
+    /// [`load_from_str`]: `Yaml::load_from_str`
     pub fn load_from_iter<I: Iterator<Item = char>>(source: I) -> Result<Vec<Self>, ScanError> {
         let mut parser = Parser::new(source);
         Self::load_from_parser(&mut parser)
     }
 
     /// Load the contents from the specified [`Parser`] as an array of YAML documents.
     ///
-    /// See the function [`load_from_parser`] for more details.
+    /// See the function [`load_from_str`] for more details.
     ///
     /// # Errors
     /// Returns `ScanError` when loading fails.
     ///
-    /// [`load_from_parser`]: `crate::load_from_parser`
+    /// [`load_from_str`]: `Yaml::load_from_str`
     pub fn load_from_parser<I: Iterator<Item = char>>(
         parser: &mut Parser<I>,
     ) -> Result<Vec<Self>, ScanError> {

saphyr/src/emitter.rs

@@ -36,9 +36,9 @@ impl From<fmt::Error> for EmitError {
 /// The YAML serializer.
 ///
 /// ```
-/// # use saphyr::{load_from_str, YamlEmitter};
+/// # use saphyr::{Yaml, YamlEmitter};
 /// let input_string = "a: b\nc: d";
-/// let yaml = load_from_str(input_string).unwrap();
+/// let yaml = Yaml::load_from_str(input_string).unwrap();
 ///
 /// let mut output = String::new();
 /// YamlEmitter::new(&mut output).dump(&yaml[0]).unwrap();
@@ -159,10 +159,10 @@ impl<'a> YamlEmitter<'a> {
     /// # Examples
     ///
     /// ```rust
-    /// use saphyr::{Yaml, YamlEmitter, load_from_str};
+    /// use saphyr::{Yaml, YamlEmitter};
     ///
     /// let input = r#"{foo: "bar!\nbar!", baz: 42}"#;
-    /// let parsed = load_from_str(input).unwrap();
+    /// let parsed = Yaml::load_from_str(input).unwrap();
     /// eprintln!("{:?}", parsed);
     ///
     /// let mut output = String::new();
@@ -409,12 +409,14 @@ fn need_quotes(string: &str) -> bool {
 
 #[cfg(test)]
 mod test {
+    use crate::Yaml;
+
     use super::YamlEmitter;
 
     #[test]
     fn test_multiline_string() {
         let input = r#"{foo: "bar!\nbar!", baz: 42}"#;
-        let parsed = crate::load_from_str(input).unwrap();
+        let parsed = Yaml::load_from_str(input).unwrap();
         let mut output = String::new();
         let mut emitter = YamlEmitter::new(&mut output);
         emitter.multiline_strings(true);

saphyr/src/encoding.rs

@@ -102,7 +102,7 @@ impl<T: std::io::Read> YamlDecoder<T> {
         // Decode the input buffer.
         decode_loop(&buffer, &mut output, &mut decoder, self.trap)?;
 
-        crate::load_from_str(&output).map_err(LoadError::Scan)
+        Yaml::load_from_str(&output).map_err(LoadError::Scan)
     }
 }
 

saphyr/src/lib.rs

@@ -21,9 +21,9 @@
 //! Parse a string into `Vec<Yaml>` and then serialize it as a YAML string.
 //!
 //! ```
-//! use saphyr::{load_from_str, YamlEmitter};
+//! use saphyr::{Yaml, YamlEmitter};
 //!
-//! let docs = load_from_str("[1, 2, 3]").unwrap();
+//! let docs = Yaml::load_from_str("[1, 2, 3]").unwrap();
 //! let doc = &docs[0]; // select the first YAML document
 //! assert_eq!(doc[0].as_i64().unwrap(), 1); // access elements by index
 //!
@@ -56,9 +56,7 @@ pub use crate::annotated::{
     marked_yaml::MarkedYaml, AnnotatedArray, AnnotatedHash, AnnotatedYamlIter, YamlData,
 };
 pub use crate::emitter::YamlEmitter;
-pub use crate::loader::{
-    load_from_iter, load_from_parser, load_from_str, LoadableYamlNode, YamlLoader,
-};
+pub use crate::loader::{LoadableYamlNode, YamlLoader};
 pub use crate::yaml::{Array, Hash, Yaml, YamlIter};
 
 #[cfg(feature = "encoding")]

saphyr/src/loader.rs

@@ -3,67 +3,10 @@
 use std::collections::BTreeMap;
 
 use hashlink::LinkedHashMap;
-use saphyr_parser::{Event, MarkedEventReceiver, Marker, Parser, ScanError, TScalarStyle, Tag};
+use saphyr_parser::{Event, MarkedEventReceiver, Marker, ScanError, TScalarStyle, Tag};
 
 use crate::{Hash, Yaml};
 
-/// Load the given string as an array of YAML documents.
-///
-/// The `source` is interpreted as YAML documents and is parsed. Parsing succeeds if and only
-/// if all documents are parsed successfully. An error in a latter document prevents the former
-/// from being returned.
-///
-/// Most often, only one document is loaded in a YAML string. In this case, only the first element
-/// of the returned `Vec` will be used. Otherwise, each element in the `Vec` is a document:
-///
-/// ```
-/// use saphyr::{load_from_str, Yaml};
-///
-/// let docs = load_from_str(r#"
-/// First document
-/// ---
-/// - Second document
-/// "#).unwrap();
-/// let first_document = &docs[0]; // Select the first YAML document
-/// // The document is a string containing "First document".
-/// assert_eq!(*first_document, Yaml::String("First document".to_owned()));
-///
-/// let second_document = &docs[1]; // Select the second YAML document
-/// // The document is an array containing a single string, "Second document".
-/// assert_eq!(second_document[0], Yaml::String("Second document".to_owned()));
-/// ```
-///
-/// # Errors
-/// Returns `ScanError` when loading fails.
-pub fn load_from_str(source: &str) -> Result<Vec<Yaml>, ScanError> {
-    load_from_iter(source.chars())
-}
-
-/// Load the contents of the given iterator as an array of YAML documents.
-///
-/// See [`load_from_str`] for details.
-///
-/// # Errors
-/// Returns `ScanError` when loading fails.
-pub fn load_from_iter<I: Iterator<Item = char>>(source: I) -> Result<Vec<Yaml>, ScanError> {
-    let mut parser = Parser::new(source);
-    load_from_parser(&mut parser)
-}
-
-/// Load the contents from the specified [`Parser`] as an array of YAML documents.
-///
-/// See [`load_from_str`] for details.
-///
-/// # Errors
-/// Returns `ScanError` when loading fails.
-pub fn load_from_parser<I: Iterator<Item = char>>(
-    parser: &mut Parser<I>,
-) -> Result<Vec<Yaml>, ScanError> {
-    let mut loader = YamlLoader::default();
-    parser.load(&mut loader, true)?;
-    Ok(loader.docs)
-}
-
 /// Main structure for parsing YAML.
 ///
 /// The `YamlLoader` may load raw YAML documents or add metadata if needed. The type of the `Node`

saphyr/src/yaml.rs

@@ -5,8 +5,9 @@
 use std::{convert::TryFrom, ops::Index, ops::IndexMut};
 
 use hashlink::LinkedHashMap;
+use saphyr_parser::{Parser, ScanError};
 
-use crate::loader::parse_f64;
+use crate::{loader::parse_f64, YamlLoader};
 
 /// A YAML node is stored as this `Yaml` enumeration, which provides an easy way to
 /// access your YAML document.
@@ -57,6 +58,63 @@ pub type Array = Vec<Yaml>;
 pub type Hash = LinkedHashMap<Yaml, Yaml>;
 
 impl Yaml {
+    /// Load the given string as an array of YAML documents.
+    ///
+    /// The `source` is interpreted as YAML documents and is parsed. Parsing succeeds if and only
+    /// if all documents are parsed successfully. An error in a latter document prevents the former
+    /// from being returned.
+    ///
+    /// Most often, only one document is loaded in a YAML string. In this case, only the first element
+    /// of the returned `Vec` will be used. Otherwise, each element in the `Vec` is a document:
+    ///
+    /// ```
+    /// use saphyr::Yaml;
+    ///
+    /// let docs = Yaml::load_from_str(r#"
+    /// First document
+    /// ---
+    /// - Second document
+    /// "#).unwrap();
+    /// let first_document = &docs[0]; // Select the first YAML document
+    /// // The document is a string containing "First document".
+    /// assert_eq!(*first_document, Yaml::String("First document".to_owned()));
+    ///
+    /// let second_document = &docs[1]; // Select the second YAML document
+    /// // The document is an array containing a single string, "Second document".
+    /// assert_eq!(second_document[0], Yaml::String("Second document".to_owned()));
+    /// ```
+    ///
+    /// # Errors
+    /// Returns `ScanError` when loading fails.
+    pub fn load_from_str(source: &str) -> Result<Vec<Self>, ScanError> {
+        Self::load_from_iter(source.chars())
+    }
+
+    /// Load the contents of the given iterator as an array of YAML documents.
+    ///
+    /// See [`Self::load_from_str`] for details.
+    ///
+    /// # Errors
+    /// Returns `ScanError` when loading fails.
+    pub fn load_from_iter<I: Iterator<Item = char>>(source: I) -> Result<Vec<Yaml>, ScanError> {
+        let mut parser = Parser::new(source);
+        Self::load_from_parser(&mut parser)
+    }
+
+    /// Load the contents from the specified [`Parser`] as an array of YAML documents.
+    ///
+    /// See [`Self::load_from_str`] for details.
+    ///
+    /// # Errors
+    /// Returns `ScanError` when loading fails.
+    pub fn load_from_parser<I: Iterator<Item = char>>(
+        parser: &mut Parser<I>,
+    ) -> Result<Vec<Yaml>, ScanError> {
+        let mut loader = YamlLoader::default();
+        parser.load(&mut loader, true)?;
+        Ok(loader.into_documents())
+    }
+
     define_as!(as_bool, bool, Boolean);
     define_as!(as_i64, i64, Integer);
 

saphyr/tests/basic.rs

@@ -1,7 +1,7 @@
 #![allow(clippy::bool_assert_comparison)]
 #![allow(clippy::float_cmp)]
 
-use saphyr::{load_from_str, Yaml, YamlEmitter};
+use saphyr::{Yaml, YamlEmitter};
 
 #[test]
 fn test_api() {
@@ -29,7 +29,7 @@ fn test_api() {
     - name: Staff
       damage: 3
 ";
-    let docs = load_from_str(s).unwrap();
+    let docs = Yaml::load_from_str(s).unwrap();
     let doc = &docs[0];
 
     assert_eq!(doc[0]["name"].as_str().unwrap(), "Ogre");
@@ -50,7 +50,7 @@ a: 1
 b: 2.2
 c: [1, 2]
 ";
-    let out = load_from_str(s).unwrap();
+    let out = Yaml::load_from_str(s).unwrap();
     let doc = &out[0];
     assert_eq!(doc["a"].as_i64().unwrap(), 1i64);
     assert_eq!(doc["b"].as_f64().unwrap(), 2.2f64);
@@ -66,7 +66,7 @@ a1: &DEFAULT
     b2: d
 a2: *DEFAULT
 ";
-    let out = load_from_str(s).unwrap();
+    let out = Yaml::load_from_str(s).unwrap();
     let doc = &out[0];
     assert_eq!(doc["a2"]["b1"].as_i64().unwrap(), 4);
 }
@@ -78,7 +78,7 @@ a1: &DEFAULT
     b1: 4
     b2: *DEFAULT
 ";
-    let out = load_from_str(s).unwrap();
+    let out = Yaml::load_from_str(s).unwrap();
     let doc = &out[0];
     assert_eq!(doc["a1"]["b2"], Yaml::BadValue);
 }
@@ -114,7 +114,7 @@ fn test_plain_datatype() {
 - +12345
 - [ true, false ]
 ";
-    let out = load_from_str(s).unwrap();
+    let out = Yaml::load_from_str(s).unwrap();
     let doc = &out[0];
 
     assert_eq!(doc[0].as_str().unwrap(), "string");
@@ -171,7 +171,7 @@ fn test_plain_datatype_with_into_methods() {
 - .NAN
 - !!float .INF
 ";
-    let mut out = load_from_str(s).unwrap().into_iter();
+    let mut out = Yaml::load_from_str(s).unwrap().into_iter();
     let mut doc = out.next().unwrap().into_iter();
 
     assert_eq!(doc.next().unwrap().into_string().unwrap(), "string");
@@ -203,7 +203,7 @@ b: ~
 a: ~
 c: ~
 ";
-    let out = load_from_str(s).unwrap();
+    let out = Yaml::load_from_str(s).unwrap();
     let first = out.into_iter().next().unwrap();
     let mut iter = first.into_hash().unwrap().into_iter();
     assert_eq!(
@@ -229,7 +229,7 @@ fn test_integer_key() {
 1:
     important: false
 ";
-    let out = load_from_str(s).unwrap();
+    let out = Yaml::load_from_str(s).unwrap();
     let first = out.into_iter().next().unwrap();
     assert_eq!(first[0]["important"].as_bool().unwrap(), true);
 }