pub struct KeyPath {

pub (crate) struct KeyPath {

    pub(crate) fn from_str(s: &str) -> Self {

    pub (crate) fn from_str(s: &str) -> Self {

    /// Returns the key name of the top token.
    pub fn name(&self) -> String {
        self.tokens[0].key().to_string()
    }

    pub fn siblings(&self, index: usize) -> Vec<usize> {

    pub (crate) fn siblings(&self, index: usize) -> Vec<usize> {

    pub fn key_into<T>(self) -> Result<T>

    pub (crate) fn key_into<T>(self) -> Result<T>

    pub fn keyvalue_into<T>(&self) -> Result<T>

    pub (crate) fn keyvalue_into<T>(&self) -> Result<T>

    /// Returns a `Some<KeyTree>` if the path exists or `None` otherwise.

    /// Returns a `KeyTree`.

    /// Returns a `T: FromStr` where `T` is the receiver type.
    /// ```
    /// use std::convert::TryInto;
    /// use keytree::{KeyTree, KeyTreeRef};
    /// use keytree::Error;
    /// 
    /// static TEMP: &'static str = r#"example:
    ///     temp: -15.3"#;
    /// 
    /// struct Temperature(f32);
    ///
    /// impl FromStr for Temperature {
    ///     let Err = std::num::ParseFloatError;
    ///
    ///     fn from_str(s: &str) -> Result<Self, Self::Err> {
    ///         self.parse(s)
    ///     }
    /// }
    /// 
    /// impl<'a> TryInto<Temperature> for KeyTreeRef<'a> {
    ///     type Error = Error;
    /// 
    ///     fn try_into(self) -> Result<Hobbit, Error> {
    ///         Ok(Temperature(self.value("example::temp")?))
    ///     }
    /// }
    /// 
    /// fn main() {
    ///     let kt = KeyTree::parse(TEMP).unwrap();
    ///     let temp: Temperature = kt.to_ref().try_into().unwrap();
    /// }
    /// ```

    /// Returns an `Option<T: FromStr>` where `Option<T>` is the receiver type. Returns `None` if
    /// the path does not exist.

    /// Returns a `Vec<T: FromStr>` where `Vec<T>` is the receiver type. Expects at least one
    /// key-value. Use `opt_vec_value` if an empty `Vec` is permissible.

    where
        T: FromStr,
    {
        let path = KeyPath::from_str(key_path);
        let kts = self.resolve_path(&path)?;
        let mut v = Vec::new();
        for kt in kts {
            v.push(kt.keyvalue_into()?)
        }
        if v.is_empty() {
            return Err(expected_non_empty_collection(
                file!(),
                line!(),
                key_path
            ))
        };
        Ok(v)
    }
    /// Returns a `Vec<T: FromStr>` where `Vec<T>` is the receiver type. The `Vec` can be empty.
    pub fn opt_vec_value<T>(&self, key_path: &str) -> Result<Vec<T>>

    /// Returns a `Vec<T>` where `T` can be coerced from a KeyTree. Fails if the path does not
    /// exist.

    /// Returns a `Vec<T>` where `T` can be coerced from a KeyTree. If the path does not exist
    /// returns an empty `Vec`.

    pub fn resolve_path(self, key_path: &KeyPath) -> Result<Vec<Self>> {

    pub (crate) fn resolve_path(self, key_path: &KeyPath) -> Result<Vec<Self>> {

                friends:    self.vec_at("hobbit::friends::hobbit")?,

                friends:    self.opt_vec_at("hobbit::friends::hobbit")?,