//! Multiplicity of fields (Items and Arguments)

//!

//! This module supports type-based handling of multiplicity,

//! of Items (within Documents) and Arguments (in Item keyword lines).

//!

//! It is **for use by macros**, rather than directly.

//!

//! See also `encode::multiplicity` which is the corresponding module for encoding.

//!

//! # Explanation

//!

//! We use autoref specialisation to allow macros to dispatch to

//! trait impls for `Vec<T: ItemValueParseable>`, `Option<T>` etc.

//! as well as simply unadorned `T`.

//!

//! We implement traits on a helper type `struct `[`MultiplicitySelector<Field>`].

//!

//! For Items we have `trait `[`ItemSetMethods`].

//!

//! `ItemSetMethods` is implemented for `MultiplicitySelector<Field>`

//! for each supported `Field`.

//! So, for `MultiplicitySelector<T>`, `MultiplicitySelector<Option<T>>`, and `MultiplicitySelector<Vec<T>>`.

//! *But*, for just `T`, the impl is on `&MultiplicitySelector<T>`.

//!

//! When methods on `MultiplicitySelector` are called, the compiler finds

//! the specific implementation for `MultiplicitySelector<Option<_>>` or `..Vec<_>`,

//! or, failing that, derefs and finds the blanket impl on `&MultiplicitySelector<T>`.

//!

//! For Arguments we have [`ArgumentSetMethods`],

//! and for Objects, [`ObjectSetMethods`],

//! which work similarly.

//!

//! (We need separate traits for each of the kinds of netdoc element,

//! for good support of inference in the derive macro.

//! Type inference is particularly difficult during parsing, since we need the type

//! information to flow from the field type, which is the *destination*

//!  to which a value is going to be stored.)

use super::*;

use crate::types::RetainedOrderVec;

#[cfg(doc)]

use crate::encode;

/// Helper type that allows us to select an impl of `ItemSetMethods` etc.

///

/// **For use by macros**.

///

/// See the [module-level docs](multiplicity).

///

/// This is distinct from `encode::MultiplicitySelector`,

/// principally because it has the opposite variance.

#[derive(Educe)]

#[educe(Clone, Copy, Default)]

pub struct MultiplicitySelector<Field>(PhantomData<fn() -> Field>);

/// Helper type that allows us to implement Debug

///

/// Returned by [`ItemSetMethods::item_set_debug`] etc.,

/// using information from [`ItemSetMethods::debug_core`] etc.

#[derive(derive_more::Debug)]

#[debug("{}={}", self.0, self.1)]

#[allow(dead_code)] // yes, they are only read by the Debug impl - that's what they're for!

struct DebugHelper(

    /// scope, eg `items`

    &'static str,

    /// multiplicity type pattern, eg `Vec<_>` or `1`

    &'static str,

);

/// Methods for handling some multiplicity of Items, during parsing

///

/// **For use by macros**.

///

/// During parsing, we accumulate into a value of type `Option<Self::Field>`.

/// The semantics of this are item-set-implementation-dependent;

/// using a type which is generic over the field type in a simple way

/// allows the partially-parsed accumulation state for a whole netdoc to have a concrete type.

///

/// See the [module-level docs](multiplicity), and

/// [Field type in `NetdocParseable`](derive_deftly_template_NetdocParseable#field-type).

///

/// # Example

///

/// The code in the (derive) macro output is roughly like this:

///

/// ```

/// use tor_netdoc::parse2::multiplicity::{MultiplicitySelector, ItemSetMethods as _};

///

/// let selector = MultiplicitySelector::<Vec<i32>>::default();

/// let mut accum = None;

/// selector.accumulate(&mut accum, 12).unwrap();

/// let out = selector.finish(accum, "item-set").unwrap();

///

/// assert_eq!(out, [12]);

/// ```

//

// When implementing this, update the documentation in the `NetdocParseable` derive.

pub trait ItemSetMethods: Copy + Sized {

    /// The value for each Item.

    ///

    /// Should match the corresponding

    /// [`encode::MultiplicityMethods::Each`].

    /// (See docs there for rationale.)

    type Each: Sized;

    /// The output type: the type of the field in the netdoc struct.

    type Field: Sized;

    /// Can we accumulate another item ?

    ///

    /// Can be used to help predict whether `accumulate` will throw.

    fn can_accumulate(self, acc: &Option<Self::Field>) -> Result<(), EP>;

    /// Accumulate one value into the accumulator.

    fn accumulate(self, acc: &mut Option<Self::Field>, one: Self::Each) -> Result<(), EP>;

    /// Multiplicity representation for `#[deftly(netdoc(debug))]` output, core

    ///

    /// Should generally be in a form like `Vec<_>`.

    ///

    /// See also [`ItemSetMethods::item_set_debug`], which is what the derives call.

    //

    // This can't be a `Debug` supertrait, because that won't work

    // with the `&'_ MultiplicitySelector<T>` impl.

    fn debug_core(self) -> &'static str;

    /// Multiplicity representation for `#[deftly(netdoc(debug))]` output

    ///

    /// This adds a bit framing and type-fu that allows the derive macro's

    /// call to be as simple as possible.

    ///

    /// See also [`ItemSetMethods::debug_core`], which is what each multiplicity implements.

    //

    // dtrace!, which we use for debugging in the parser macros, doesn't print variable names,

    // thinking things are probably obvious enough.  But for the elector here we want to

    // include `items=`.

    /// Resolve the accumulator into the output.

    fn finish(

        self,

        acc: Option<Self::Field>,

        item_keyword: &'static str,

    ) -> Result<Self::Field, EP>;

    /// If the contained type is a sub-document, call its `is_intro_item_keyword`.

    {

    /// If the contained type is a sub-document, call its `is_structural_keyword`.

    {

    /// `finish` for if the contained type is a wsub-document

    ///

    /// Obtain the sub-document's intro keyword from its `doctype_for_error`.

    {

    /// Check that the element type is an Item

    ///

    /// For providing better error messages when struct fields don't implement the right trait.

    /// See `derive.rs`, and search for this method name.

    {

    /// Check that the element type is a Signature

    {

    /// Check that the element type is a sub-document

    {

    /// Check that the element type is an argument

    {

}

impl<T> ItemSetMethods for MultiplicitySelector<Vec<T>> {

    type Each = T;

    type Field = Vec<T>;

    // We always have None, or Some(nonempty)

}

impl<T> ItemSetMethods for MultiplicitySelector<RetainedOrderVec<T>> {

    type Each = T;

    type Field = RetainedOrderVec<T>;

    // We always have None, or Some(nonempty)

}

impl<T: Ord> ItemSetMethods for MultiplicitySelector<BTreeSet<T>> {

    type Each = T;

    type Field = BTreeSet<T>;

    // We always have None, or Some(nonempty)

}

impl<T> ItemSetMethods for MultiplicitySelector<Option<T>> {

    type Each = T;

    type Field = Option<T>;

    // We always have None, or Some(Some(_))

    // We always have None, or Some(Some(_))

}

impl<T> ItemSetMethods for &'_ MultiplicitySelector<T> {

    type Each = T;

    type Field = T;

        // This appears in #[deftly(netdoc(debug))] output for singleton fields.

        // We probably don't want the macros' users to have to think about our

        // autoref-specialisation.  So we don't write anything about `&` here.

}

/// Method for handling some multiplicity of Arguments

///

/// **For use by macros**.

///

/// See the [module-level docs](multiplicity), and

/// [Field type in `ItemValueParseable`](derive_deftly_template_ItemValueParseable#field-type).

///

/// # Example

///

/// The code in the (derive) macro output is roughly like this:

///

/// ```

/// use tor_netdoc::parse2::multiplicity::{MultiplicitySelector, ArgumentSetMethods as _};

/// use tor_netdoc::parse2::{ItemArgumentParseable, ItemStream, ParseInput};

/// let doc = "intro-item 12 66\n";

/// let input = ParseInput::new(doc, "<literal>");

/// let mut items = ItemStream::new(&input);

/// let mut item = items.next().unwrap().unwrap();

///

/// let args = MultiplicitySelector::<Vec<i32>>::default()

///     .parse_with(item.args_mut(), ItemArgumentParseable::from_args)

///     .unwrap();

/// assert_eq!(args, [12, 66]);

/// ```

//

// When implementing this, update the documentation in the `ItemValueParseable` derive.

pub trait ArgumentSetMethods: Copy + Sized {

    /// The value for each Item.

    ///

    /// Should match the corresponding

    /// [`encode::MultiplicityMethods::Each`].

    /// (See docs there for rationale.)

    type Each: Sized;

    /// The output type: the type of the field in the Item struct.

    ///

    /// This is *not* the type of an individual netdoc argument;

    /// that is not explicitly represented in the trait.

    type Field: Sized;

    /// Parse zero or more argument(s) into `Self::Field`.

    fn parse_with<P>(self, args: &mut ArgumentStream<'_>, parser: P) -> Result<Self::Field, AE>

    where

        P: for<'s> Fn(&mut ArgumentStream<'s>) -> Result<Self::Each, AE>;

    /// Multiplicity representation for `#[deftly(netdoc(debug))]` output, core

    ///

    /// Should generally be in a form like `Vec<_>`.

    ///

    /// See [`ItemSetMethods::debug_core`] and [`ArgumentSetMethods::argument_set_debug`].

    fn debug_core(self) -> &'static str;

    /// Multiplicity representation for `#[deftly(netdoc(debug))]` output

    ///

    /// See [`ItemSetMethods::item_set_debug`] and [`ArgumentSetMethods::debug_core`].

    /// Check that the element type is an Argument

    ///

    /// For providing better error messages when struct fields don't implement the right trait.

    /// See `derive.rs`, and search for this method name.

    {

}

impl<T> ArgumentSetMethods for MultiplicitySelector<Vec<T>> {

    type Each = T;

    type Field = Vec<T>;

    {

        }

}

impl<T: Ord> ArgumentSetMethods for MultiplicitySelector<BTreeSet<T>> {

    type Each = T;

    type Field = BTreeSet<T>;

    {

        }

}

impl<T> ArgumentSetMethods for MultiplicitySelector<Option<T>> {

    type Each = T;

    type Field = Option<T>;

    {

}

impl<T> ArgumentSetMethods for &MultiplicitySelector<T> {

    type Each = T;

    type Field = T;

    {

}

/// Method for handling some multiplicity of Objects

///

/// **For use by macros**.

///

/// See the [module-level docs](multiplicity), and

/// [Field type in `ItemValueParseable`](derive_deftly_template_ItemValueParseable#field-type).

///

/// # Example

///

/// The code in the (derive) macro output is roughly like this:

///

/// ```

/// use tor_netdoc::parse2::multiplicity::{MultiplicitySelector, ObjectSetMethods as _};

/// use tor_netdoc::parse2::{ItemStream, ParseInput};

/// let doc = "intro-item\n-----BEGIN OBJECT-----\naGVsbG8=\n-----END OBJECT-----\n";

/// let input = ParseInput::new(doc, "<literal>");

/// let mut items = ItemStream::new(&input);

/// let mut item = items.next().unwrap().unwrap();

///

/// let selector = MultiplicitySelector::<Option<String>>::default();

/// let obj = item.object().map(|obj| {

///     let data = obj.decode_data().unwrap();

///     String::from_utf8(data)

/// }).transpose().unwrap();

/// let obj = selector.resolve_option(obj).unwrap();

/// assert_eq!(obj, Some("hello".to_owned()));

/// ```

pub trait ObjectSetMethods: Copy + Sized {

    /// The value for each Item.

    ///

    /// Should match the corresponding

    /// [`encode::OptionalityMethods::Each`].

    /// (See [`encode::MultiplicityMethods::Each`] for rationale.)

    type Each: Sized;

    /// The output type: the type of the field in the Item struct.

    type Field: Sized;

    /// Parse zero or more argument(s) into `Self::Field`.

    fn resolve_option(self, found: Option<Self::Each>) -> Result<Self::Field, EP>;

    /// Multiplicity representation for `#[deftly(netdoc(debug))]` output, core

    ///

    /// Should generally be in a form like `Option<_>`.

    ///

    /// See [`ItemSetMethods::debug_core`] and [`ObjectSetMethods::object_set_debug`].

    fn debug_core(self) -> &'static str;

    /// Multiplicity representation for `#[deftly(netdoc(debug))]` output

    ///

    /// See [`ItemSetMethods::item_set_debug`] and [`ObjectSetMethods::debug_core`].

    /// If the contained type is `ItemObjectParseable`, call its `check_label`

    {

    /// Check that the contained type can be parsed as an object

    {

}

impl<T> ObjectSetMethods for MultiplicitySelector<Option<T>> {

    type Field = Option<T>;

    type Each = T;

}

impl<T> ObjectSetMethods for &MultiplicitySelector<T> {

    type Field = T;

    type Each = T;

}