Lines
87.5 %
Functions
45.81 %
Branches
100 %
//! Multiplicity for encoding netdoc elements, via ad-hoc deref specialisation.
//!
//! 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 `parse2::multiplicity` which is the corresponding module for parsing.
//! # Explanation
//! We use autoref specialisation to allow macros to dispatch to
//! trait impls for `Vec<T>`, `Option<T>` etc. as well as simply unadorned `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 Objects, where only `T` and `Option<T>` are allowed,
//! we use `OptionalityMethods`.
//! We implement traits on helper types `struct `[`MultiplicitySelector<Field>`],
//! [`DeterminedMultiplicitySelector`] and [`SingletonMultiplicitySelector`].
//! The three selector types allow us to force the compiler to nail down the multiplicity,
//! during type inference, before considering whether the "each" type implements the
//! required trait.
//! This is done by calling the `.selector()` method:
//! deref specialisation and inherent method vs trait method priority selects
//! the appropriate `.selector()` method, giving *another* selector,
//! so that the compiler only considers other selector's `MultiplicityMethods`,
//! when `.check_...` methods are used.
//! Otherwise, when a field has type (say) `Vec<NotItemValueParseable>`,
//! a call to `.check_item_value_encodable` could be resolved by autoref
//! so the compiler reports that **`Vec<..>`** doesn't implement the needed trait.
//! We prevent this by having
//! [`MultiplicitySelector::<Vec<_>>::default().selector()`](MultiplicitySelector::<Vec<T>>::selector)
//! be an inherent method returning [`DeterminedMultiplicitySelector`].
//! `SingletonMultiplicitySelector` is used explicitly in the derive when we
//! know that we want to encode exactly one element:
//! for example, a document's intro item cannot be repeated or omitted.
use super::*;
use crate::types::RetainedOrderVec;
#[cfg(doc)]
use crate::parse2;
/// Helper type that allows us to select an impl of `MultiplicityMethods`
///
/// **For use by macros**.
/// This is distinct from `parse2::MultiplicitySelector`,
/// principally because it has the opposite variance.
#[derive(Educe)]
#[educe(Clone, Copy, Default)]
pub struct MultiplicitySelector<Field>(PhantomData<fn(Field)>);
/// Helper type implementing `MultiplicityMethods`, after the multiplicity is determined
pub struct DeterminedMultiplicitySelector<Field>(PhantomData<fn(Field)>);
/// Helper type implementing `MultiplicityMethods`, when a field is statically a singleton
pub struct SingletonMultiplicitySelector<Field>(PhantomData<fn(Field)>);
/// Methods for handling some multiplicity of netdoc elements, during encoding
/// Each multiplicity impl allows us to iterate over the element(s).
/// Methods are also provided for typechecking, which are used by the derive macro to
/// produce reasonable error messages when a trait impl is missing.
//
// When adding features here, for example by implementing this trait,
// update the documentation in the `NetdocEncodable` and `ItemValueEncodable` derives.
pub trait MultiplicityMethods<'f>: Copy + Sized {
/// The value for each thing.
/// Should match the corresponding
/// [`parse2::multiplicity::ItemSetMethods::Each`],
/// [`parse2::multiplicity::ArgumentSetMethods::Each`],
/// for consistency, and for the benefit of `with =` attributes referring to type names.
// For example, if these Each types don't match, then if you want to say
// `with = ns_type( Each, SomethingSpecial, ... )`
// so that the plain consensus just uses the normal parsing, it doesn't
// work, because `Each` has to match both `parse2::multiplicity::ItemSetSelector::Each`
// and `encode::MultiplicityMethods::Each`, or the derived parsing code gets type errors.
// Having them different is anomalous, anyway.
type Each: Sized + 'f;
/// The input type: the type of the field in the netdoc or item struct.
type Field: Sized;
/// Return the appropriate implementor of `MultiplicityMethods`
fn selector(self) -> Self {
self
}
/// Yield the items, in a stable order
fn iter_ordered(self, f: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> + 'f;
/// Cause a compiler error if the element is not `NetdocEncodable`
fn check_netdoc_encodable(self)
where
Self::Each: NetdocEncodable,
{
/// Cause a compiler error if the element is not `ItemValueEncodable`
fn check_item_value_encodable(self)
Self::Each: ItemValueEncodable,
/// Cause a compiler error if the element is not `ItemArgument`
fn check_item_argument_encodable(self)
Self::Each: ItemArgument,
/// Cause a compiler error if the element is not `ItemObjectEncodable`
fn check_item_object_encodable(self)
Self::Each: ItemObjectEncodable,
impl<T> MultiplicitySelector<Vec<T>> {
/// This is an inherent method so that it doesn't need the `EncodeOrd` bounds:
/// that way if `EncodeOrd` is not implemented, we get a message about that,
/// rather than a complaint that `ItemValueEncodable` isn't impl for `Vec<T>`.
pub fn selector(self) -> DeterminedMultiplicitySelector<Vec<T>> {
DeterminedMultiplicitySelector::default()
impl<'f, T: EncodeOrd + 'f> MultiplicityMethods<'f> for DeterminedMultiplicitySelector<Vec<T>> {
type Each = T;
type Field = Vec<T>;
fn iter_ordered(self, f: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> {
let mut v = f.iter().collect_vec();
v.sort_by(|a, b| a.encode_cmp(*b));
v.into_iter()
impl<'f, T: 'f> MultiplicityMethods<'f> for MultiplicitySelector<RetainedOrderVec<T>> {
type Field = RetainedOrderVec<T>;
f.0.iter()
impl<'f, T: 'f> MultiplicityMethods<'f> for MultiplicitySelector<BTreeSet<T>> {
type Field = BTreeSet<T>;
f.iter()
impl<'f, T: 'f> MultiplicityMethods<'f> for MultiplicitySelector<Option<T>> {
type Field = Option<T>;
fn iter_ordered(self, f: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> + 'f {
impl<'f, T: 'f> MultiplicityMethods<'f> for &'_ MultiplicitySelector<T> {
type Field = T;
iter::once(f)
impl<'f, T: 'f> MultiplicityMethods<'f> for SingletonMultiplicitySelector<T> {
/// Methods for handling optionality of a netdoc Object, during encoding
// This could be used for things other than Object, if there were any thing
// that supported Option but not Vec.
/// Each impl allows us to visit an optional element.
pub trait OptionalityMethods: Copy + Sized {
/// The possibly-present element.
/// [`parse2::multiplicity::ObjectSetMethods::Each`].
/// (See [`MultiplicityMethods::Each`] for rationale.)
type Each: Sized + 'static;
/// The input type: the type of the field in the item struct.
/// Yield the element, if there is one
fn as_option<'f>(self, f: &'f Self::Field) -> Option<&'f Self::Each>;
impl<T: 'static> OptionalityMethods for MultiplicitySelector<Option<T>> {
fn as_option<'f>(self, f: &'f Self::Field) -> Option<&'f Self::Each> {
f.as_ref()
impl<T: 'static> OptionalityMethods for &'_ MultiplicitySelector<T> {
Some(f)