//! Based on a set of rules, validate a token stream and collect the

//! tokens by type.

//!

//! See the "rules" module for definitions of keywords types and

//! per-keyword rules.

//!

//! The key types in this module are SectionRules, which explains how to

//! validate and partition a stream of Item, and Section, which contains

//! a validated set of Item, ready to be interpreted.

//!

//! # Example

//!

//! (This is an internal API, so see the routerdesc.rs source for an

//! example of use.)

use crate::parse::keyword::Keyword;

use crate::parse::rules::*;

use crate::parse::tokenize::*;

use crate::{ParseErrorKind as EK, Result};

/// Describe the rules for one section of a document.

///

/// The rules are represented as a mapping from token index to

/// rules::TokenFmt.

pub(crate) struct SectionRules<T: Keyword> {

    /// A set of rules for decoding a series of tokens into a Section

    /// object.  Each element of this array corresponds to the

    /// token with the corresponding index values.

    ///

    /// When an array element is None, the corresponding keyword is

    /// not allowed in this kind section.  Otherwise, the array

    /// element is a TokenFmt describing how many of the corresponding

    /// token may appear, and what they need to look like.

    rules: Vec<Option<TokenFmt<T>>>,

}

/// The entry or entries for a particular keyword within a document.

enum TokVal<'a, K: Keyword> {

    /// No value has been found.

    None,

    /// A single value has been found; we're storing it in place.

    ///

    /// We use a one-element array here so that we can return a slice

    /// of the array.

    Some([Item<'a, K>; 1]),

    /// Multiple values have been found; they go in a vector.

    Multi(Vec<Item<'a, K>>),

}

impl<'a, K: Keyword> TokVal<'a, K> {

    /// Return the number of Items for this value.

        }

    /// Return the first Item for this value, or None if there wasn't one.

        }

    /// Return the Item for this value, if there is exactly one.

        }

    /// Return all the Items for this value, as a slice.

        }

    /// Return the last Item for this value, if any.

        }

}

/// A Section is the result of sorting a document's entries by keyword.

///

/// TODO: I'd rather have this be pub(crate), but I haven't figured out

/// how to make that work.

pub struct Section<'a, T: Keyword> {

    /// Map from Keyword index to TokVal

    v: Vec<TokVal<'a, T>>,

    /// The keyword that appeared first in this section.  This will

    /// be set if `v` is nonempty.

    first: Option<T>,

    /// The keyword that appeared last in this section.  This will

    /// be set if `v` is nonempty.

    last: Option<T>,

}

impl<'a, T: Keyword> Section<'a, T> {

    /// Make a new empty Section.

    /// Helper: return the tokval for some Keyword.

    /// Return all the Items for some Keyword, as a slice.

    /// Return a single Item for some Keyword, if there is exactly one.

    /// Return a single Item for some Keyword, giving an error if there

    /// is not exactly one.

    ///

    /// It is usually a mistake to use this function on a Keyword that is

    /// not required.

    /// Return a proxy MaybeItem object for some keyword.

    //

    /// A MaybeItem is used to represent an object that might or might

    /// not be there.

    /// Return the first item that was accepted for this section, or None

    /// if no items were accepted for this section.

        }

    /// Return the last item that was accepted for this section, or None

    /// if no items were accepted for this section.

        }

    /// Insert an `item`.

    ///

    /// The `item` must have parsed Keyword `t`.

        };

}

impl<T: Keyword> SectionRules<T> {

    /// Create a new SectionRules with no rules.

    ///

    /// By default, no Keyword is allowed by this SectionRules.

    /// Add a rule to this SectionRules, based on a TokenFmtBuilder.

    ///

    /// Requires that no rule yet exists for the provided keyword.

    /// Parse a stream of tokens into a Section object without (fully)

    /// verifying them.

    ///

    /// Some errors are detected early, but others only show up later

    /// when we validate more carefully.

                // we want this token.

            } else {

                // We don't have a rule for this token.

            }

        }

    /// Check whether the tokens in a section we've parsed conform to

    /// these rules.

        // Iterate over every item, and make sure it matches the

        // corresponding rule.

                None => {

                    // We aren't supposed to have any of these.

                }

                    // The number is right. Check each individual item.

                    }

                }

            }

        }

    /// Check all the base64-encoded objects on a given keyword.

    ///

    /// We use this to validate objects on unrecognized items, since

    /// otherwise nothing would check that they are well-formed.

        }

    /// Parse a stream of tokens into a validated section.

}

#[cfg(test)]

mod test {

    #![allow(clippy::unwrap_used)]

    use super::SectionRules;

    use crate::parse::keyword::Keyword;

    use crate::parse::macros::test::Fruit;

    use crate::parse::tokenize::{Item, NetDocReader};

    use crate::{Error, ParseErrorKind as EK, Result};

    use once_cell::sync::Lazy;

    /// Rules for parsing a set of router annotations.

    static FRUIT_SALAD: Lazy<SectionRules<Fruit>> = Lazy::new(|| {

        use Fruit::*;

        let mut rules = SectionRules::new();

        rules.add(ANN_TASTY.rule().required().args(1..=1));

        rules.add(ORANGE.rule().args(1..));

        rules.add(STONEFRUIT.rule().may_repeat());

        rules.add(GUAVA.rule().obj_optional());

        rules.add(LEMON.rule().no_args().obj_required());

        rules

    });

    #[test]

    fn parse_section() -> Result<()> {

        use Fruit::*;

        let s = "\

@tasty yes

orange soda

cherry cobbler

cherry pie

plum compote

guava fresh from 7 trees

-----BEGIN GUAVA MANIFESTO-----

VGhlIGd1YXZhIGVtb2ppIGlzIG5vdCBjdXJyZW50bHkgc3VwcG9ydGVkIGluI

HVuaWNvZGUgMTMuMC4gTGV0J3MgZmlnaHQgYWdhaW5zdCBhbnRpLWd1YXZhIG

JpYXMu

-----END GUAVA MANIFESTO-----

lemon

-----BEGIN LEMON-----

8J+Niw==

-----END LEMON-----

";

        let mut r: NetDocReader<'_, Fruit> = NetDocReader::new(s);

        let sec = FRUIT_SALAD.parse(&mut r.iter()).unwrap();

        assert_eq!(sec.required(ANN_TASTY)?.arg(0), Some("yes"));

        assert!(sec.get(ORANGE).is_some());

        assert_eq!(sec.get(ORANGE).unwrap().args_as_str(), "soda");

        let stonefruit_slice = sec.slice(STONEFRUIT);

        assert_eq!(stonefruit_slice.len(), 3);

        let kwds: Vec<&str> = stonefruit_slice.iter().map(Item::kwd_str).collect();

        assert_eq!(kwds, &["cherry", "cherry", "plum"]);

        assert_eq!(sec.maybe(GUAVA).args_as_str(), Some("fresh from 7 trees"));

        assert_eq!(sec.maybe(GUAVA).parse_arg::<u32>(2).unwrap(), Some(7));

        assert!(sec.maybe(GUAVA).parse_arg::<u32>(1).is_err());

        assert_eq!(sec.get(GUAVA).unwrap().obj("GUAVA MANIFESTO").unwrap(),

                   &b"The guava emoji is not currently supported in unicode 13.0. Let's fight against anti-guava bias."[..]);

        assert_eq!(

            sec.get(ANN_TASTY).unwrap() as *const Item<'_, _>,

            sec.first_item().unwrap() as *const Item<'_, _>

        );

        assert_eq!(

            sec.get(LEMON).unwrap() as *const Item<'_, _>,

            sec.last_item().unwrap() as *const Item<'_, _>

        );

        Ok(())

    }

    #[test]

    fn rejected() {

        use crate::Pos;

        fn check(s: &str, e: &Error) {

            let mut r: NetDocReader<'_, Fruit> = NetDocReader::new(s);

            let res = FRUIT_SALAD.parse(&mut r.iter());

            assert!(res.is_err());

            assert_eq!(&res.err().unwrap().within(s), e);

        }

        // unrecognized tokens aren't allowed here

        check(

            "orange foo\nfoobar x\n@tasty yes\n",

            &EK::UnexpectedToken

                .with_msg("<unrecognized>")

                .at_pos(Pos::from_line(2, 1)),

        );

        // Only one orange per customer.

        check(

            "@tasty yes\norange foo\norange bar\n",

            &EK::DuplicateToken

                .with_msg("orange")

                .at_pos(Pos::from_line(3, 1)),

        );

        // There needs to be a declaration of tastiness.

        check("orange foo\n", &EK::MissingToken.with_msg("@tasty"));

        // You can't have an orange without an argument.

        check(

            "@tasty nope\norange\n",

            &EK::TooFewArguments

                .with_msg("orange")

                .at_pos(Pos::from_line(2, 1)),

        );

        // You can't have an more than one argument on "tasty".

        check(

            "@tasty yup indeed\norange normal\n",

            &EK::TooManyArguments

                .with_msg("@tasty")

                .at_pos(Pos::from_line(1, 1)),

        );

        // Every lemon needs an object

        check(

            "@tasty yes\nlemon\norange no\n",

            &EK::MissingObject

                .with_msg("lemon")

                .at_pos(Pos::from_line(2, 1)),

        );

    }

}