//! 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::{NetdocErrorKind as EK, Result};

use educe::Educe;

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

///

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

/// rules::TokenFmt.

#[derive(Clone)]

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.

#[educe(Default)]

struct TokVal<'a, K: Keyword>(Vec<Item<'a, K>>);

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

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

    /// 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`.

}

/// A builder for a set of section rules.

#[derive(Clone)]

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

    /// Have we been told, explicitly, to reject unrecognized tokens?

    strict: bool,

    /// The rules we're building.

    rules: SectionRules<T>,

}

impl<T: Keyword> SectionRulesBuilder<T> {

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

    ///

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

    /// Explicitly reject any unrecognized tokens.

    ///

    /// To avoid errors, you must either explicitly reject unrecognized tokens,

    /// or you must define how they are handled.

    /// Construct the SectionRules from this builder.

    ///

    /// # Panics

    ///

    /// Panics if you did not specify the behavior for unrecognized tokens,

    /// using either `reject_unrecognized` or `add(UNRECOGNIZED.rule()...)`

        );

}

impl<T: Keyword> SectionRules<T> {

    /// Create a new builder for a SectionRules with no rules.

    ///

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

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

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_duration_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::SectionRules;

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

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

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

    use crate::{Error, NetdocErrorKind 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::builder();

        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.reject_unrecognized();

        rules.build()

    });

    #[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 r: NetDocReader<'_, Fruit> = NetDocReader::new(s).unwrap();

        let sec = FRUIT_SALAD.parse(r).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());

        // Try the `obj` accessor.

        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!(matches!(

            sec.get(ORANGE)

                .unwrap()

                .obj("ORANGE MANIFESTO")

                .unwrap_err()

                .netdoc_error_kind(),

            EK::MissingObject // orange you glad there isn't a manifesto?

        ));

        // Try `maybe_item` a bit.

        let maybe_banana = sec.maybe(BANANA);

        assert!(maybe_banana.parse_arg::<u32>(3).unwrap().is_none()); // yes! we have none.

        let maybe_guava = sec.maybe(GUAVA);

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

        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 r: NetDocReader<'_, Fruit> = NetDocReader::new(s).unwrap();

            let res = FRUIT_SALAD.parse(r);

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

        );

        // oranges don't take an object.

        check(

            "@tasty yes\norange no\n-----BEGIN ORANGE-----\naaa\n-----END ORANGE-----\n",

            &EK::UnexpectedObject

                .with_msg("orange")

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

        );

    }

}