deser_core/

open_enum.rs

//! Support for open enums (`#[deser::open_enum]`).
//!
//! An open enum is a trait whose implementations are its variants.  The
//! trait objects (`Box<dyn Trait>` and `Arc<dyn Trait>`) are serialized and
//! deserialized like enums whose variants are the types that implement the
//! trait with `#[deser::variant]`, which can be in any crate.
//!
//! Serializing only needs the value: the variant knows its name.  To
//! deserialize, the variants are looked up in the [`OpenEnums`] registry
//! of the context, where they are registered explicitly.  The macros only
//! generate the names of the variants, the conversion into the trait object
//! and short forwarding functions, everything else is here (generic over the
//! trait object and the variant).
use alloc::borrow::Cow;
use alloc::boxed::Box;
use alloc::collections::BTreeMap;
use alloc::string::ToString;
use alloc::sync::Arc;
use alloc::vec::Vec;
use core::any::{Any, TypeId, type_name};
use core::fmt;
use core::marker::PhantomData;

use crate::State;
use crate::Text;
use crate::de::enums::{
    AdjacentlyTaggedSink, ArenaVariant, EnumKey, ExternallyTaggedSink, InternallyTaggedSink, Tag,
    UntaggedTry, ValueVariant, VariantBuilder, VariantNames, Variants, no_matching_variant,
    untagged_handle_with,
};
use crate::de::mapped::mapped;
use crate::de::{Deserialize, DeserializeOwned, OwnedSink, Sink, SinkHandle};
use crate::error::{Error, ErrorKind};
use crate::event::{Atom, ContainerShape};
use crate::ser::enums::{EntrySer, FieldsSer, TaggedNewtype};
use crate::ser::{
    Describe, Emit, Serialize, SerializeHandle, SerializeRef, Variant, VariantKind, VariantRepr,
};

/// A trait whose trait objects are open enums.
///
/// This is implemented for the trait object of a trait marked with
/// [`#[deser::open_enum]`](../deser/attr.open_enum.html), the
/// implementations of the trait marked with `#[deser::variant]` are its
/// variants (see [`OpenVariant`]).  Its members are not public API.
pub trait OpenEnum: Send + Sync + 'static {
    /// The configuration of the open enum.
    #[doc(hidden)]
    const INFO: &'static OpenEnumInfo;

    /// Returns the variant of a value.
    #[doc(hidden)]
    fn __private_variant(value: &Self) -> VariantValue<'_>;
}

/// A type that is a variant of the open enum `O` (a trait object).
///
/// This is implemented by `#[deser::variant]` for the types that implement
/// the trait.  Variants are registered in an [`OpenEnums`] registry to be
/// deserialized.  Its members are not public API.
pub trait OpenVariant<O: ?Sized + OpenEnum>: Serialize + DeserializeOwned + 'static {
    /// The names of the variant.
    #[doc(hidden)]
    const ENTRY: &'static VariantEntry;

    /// Converts the value into the trait object.
    ///
    /// This is the only part of the deserialization that depends on the
    /// concrete type and the trait (the unsizing coercion), everything else
    /// is generic.
    #[doc(hidden)]
    fn __private_into_box(self) -> Box<O>;
}

/// Creates the builder of a variant.
///
/// The marker argument implies `'de: 'a` so that functions which are
/// generic over both lifetimes can be converted to this type.
type MakeVariant<O> =
    for<'a, 'de> fn(&mut State, PhantomData<&'a &'de ()>) -> ArenaVariant<'a, 'de, Box<O>>;

/// Creates the builder of the variant `T` of the open enum `O`.
fn make_variant<'a, 'de, O: ?Sized + OpenEnum, T: OpenVariant<O>>(
    state: &mut State,
    _: PhantomData<&'a &'de ()>,
) -> ArenaVariant<'a, 'de, Box<O>> {
    ValueVariant::arena(T::__private_into_box, state)
}

/// Tries the variant of an untagged open enum.
type TryVariant<O> = for<'t, 'de> fn(&mut UntaggedTry<'t, 'de, Box<O>>);

/// Tries the variant `T` of the untagged open enum `O`.
fn try_variant<O: ?Sized + OpenEnum, T: OpenVariant<O>>(attempt: &mut UntaggedTry<'_, '_, Box<O>>) {
    attempt.variant::<T>(T::__private_into_box);
}

/// The number of name styles of [`VariantEntry::styled`].
const STYLES: usize = 8;

/// The names of a variant of an open enum (generated by
/// `#[deser::variant]`).
#[doc(hidden)]
pub struct VariantEntry {
    /// The name of the type in all styles of `rename_all`.
    ///
    /// The first one is the name of the type unchanged (the default), the
    /// order of the others is the one of `RenameAll` in deser-derive.
    pub styled: &'static [&'static str; STYLES],
    /// The name given with `rename`.
    pub rename: Option<Tag<'static>>,
    /// The aliases given with `alias`.
    pub aliases: &'static [Tag<'static>],
}

/// How the variants of an open enum are represented.
#[doc(hidden)]
#[derive(Clone, Copy)]
pub enum OpenRepr {
    /// Externally tagged (a map with the name as key).
    External,
    /// Internally tagged (the name in a field of the content).
    Internal {
        /// The key of the tag.
        tag: EnumKey,
    },
    /// Adjacently tagged (the name and the content in two fields).
    Adjacent {
        /// The key of the tag.
        tag: EnumKey,
        /// The key of the content.
        content: EnumKey,
        /// If keys other than the tag and the content are errors.
        deny_unknown_fields: bool,
    },
    /// Untagged (the content alone, the variants are tried in the order
    /// they are registered).
    Untagged,
}

/// The configuration of an open enum (from `#[deser::open_enum]`).
#[doc(hidden)]
pub struct OpenEnumInfo {
    /// The name of the trait (for errors and descriptions).
    pub name: &'static str,
    /// How the variants are represented.
    pub repr: OpenRepr,
    /// The style of the names of the variants (an index into
    /// [`VariantEntry::styled`]).
    pub rename_all: usize,
    /// The styles in which the names of variants are accepted as well
    /// (`alias_all`).
    pub alias_all: &'static [usize],
}

/// The variant of a value and the value to serialize as its content.
///
/// This is returned by the hidden method that `#[deser::open_enum]` adds to
/// the trait (and `#[deser::variant]` implements).
#[doc(hidden)]
pub struct VariantValue<'a> {
    entry: &'static VariantEntry,
    content: SerializeRef<'a>,
}

impl<'a> VariantValue<'a> {
    /// Creates the variant of a value.
    #[inline]
    pub fn new<T: Serialize>(entry: &'static VariantEntry, value: &'a T) -> VariantValue<'a> {
        VariantValue {
            entry,
            content: SerializeRef::new(value),
        }
    }
}

/// The names of a variant depend on the configuration of the open enum
/// (`info`, for `rename_all` and `alias_all`).
impl VariantEntry {
    /// Returns the name of the variant.
    #[inline]
    fn name(&'static self, info: &OpenEnumInfo) -> Tag<'static> {
        match self.rename {
            Some(name) => name,
            None => Tag::Str(self.styled[info.rename_all]),
        }
    }

    /// Returns a handle to the name of the variant.
    ///
    /// The name is borrowed from the static entry.
    #[inline]
    fn name_handle(&'static self, info: &OpenEnumInfo) -> SerializeHandle<'static> {
        match self.rename {
            Some(Tag::Str(ref name)) => SerializeHandle::to(name),
            Some(ref name) => SerializeHandle::to(name),
            None => SerializeHandle::to(&self.styled[info.rename_all]),
        }
    }

    /// Returns the name of the variant as string (if it is one).
    #[inline]
    fn name_str(&'static self, info: &OpenEnumInfo) -> Option<&'static str> {
        match self.name(info) {
            Tag::Str(name) => Some(name),
            _ => None,
        }
    }

    /// Returns the names the variant is deserialized from.
    fn tags(&'static self, info: &OpenEnumInfo) -> Vec<Tag<'static>> {
        let name = self.name(info);
        let mut tags = Vec::from([name]);
        let mut push = |tag: Tag<'static>| {
            if !tags.contains(&tag) {
                tags.push(tag);
            }
        };
        for &alias in self.aliases {
            push(alias);
        }
        // the names in the styles of `alias_all`
        for &style in info.alias_all {
            push(Tag::Str(self.styled[style]));
        }
        tags
    }

    /// Returns the name for messages.
    fn display_name(&self, info: &OpenEnumInfo) -> Cow<'static, str> {
        match self.rename {
            Some(tag) => tag_display(tag),
            None => Cow::Borrowed(self.styled[info.rename_all]),
        }
    }
}

/// Returns a tag for messages.
fn tag_display(tag: Tag<'static>) -> Cow<'static, str> {
    match tag {
        Tag::Str(name) => Cow::Borrowed(name),
        Tag::U64(value) => Cow::Owned(value.to_string()),
        Tag::I64(value) => Cow::Owned(value.to_string()),
        Tag::Bool(value) => Cow::Borrowed(if value { "true" } else { "false" }),
    }
}

/// The registry of the variants of open enums.
///
/// Open enums (see [`#[deser::open_enum]`](../deser/attr.open_enum.html))
/// are deserialized with the variants registered here, the registry is
/// given to the deserialization in the [`Context`](crate::Context).  A
/// registry holds the variants of any number of open enums.  Types are
/// variants of an open enum if they implement the trait with
/// `#[deser::variant]`, which [`register`](Self::register) checks:
///
/// ```
/// use deser::{Context, Deserialize, OpenEnums, Serialize};
///
/// #[deser::open_enum(tag = "type")]
/// pub trait Shape: Send + Sync {}
///
/// #[derive(Serialize, Deserialize)]
/// pub struct Circle {
///     radius: u32,
/// }
///
/// #[deser::variant]
/// impl Shape for Circle {}
///
/// let mut variants = OpenEnums::new();
/// variants.register::<dyn Shape, Circle>().unwrap();
/// let context = Context::with(variants);
/// ```
///
/// Libraries that provide variants usually provide a function that
/// registers them.  Only the registered variants can be deserialized,
/// which is also a way to restrict what input can create.  Serializing
/// does not need the registry.  The variants of untagged open enums are
/// tried in the order they are registered.
#[derive(Default)]
pub struct OpenEnums {
    enums: BTreeMap<TypeId, Registered>,
}

/// The variants of an open enum.
struct Registered {
    // the name of the open enum
    name: &'static str,
    // the names of the variants (sorted, for errors and `Debug`)
    names: Vec<Cow<'static, str>>,
    // the `Table<O>` of the open enum
    table: Box<dyn Any + Send + Sync>,
}

/// The variants of an open enum by their tags.
struct Table<O: ?Sized + 'static> {
    // the registered variants (in the order they were registered, which is
    // the order in which the variants of untagged open enums are tried)
    variants: Vec<Registration<O>>,
    // the tags with the index of their variant (sorted by tag, empty for
    // untagged open enums)
    tags: Vec<(Tag<'static>, usize)>,
}

/// A registered variant of an open enum.
struct Registration<O: ?Sized + 'static> {
    // the type of the variant
    ty: TypeId,
    // the name of the type in Rust (for errors)
    type_name: &'static str,
    // creates the builder of the variant
    make: MakeVariant<O>,
    // tries the variant (for untagged open enums)
    try_untagged: TryVariant<O>,
}

impl OpenEnums {
    /// Creates an empty registry.
    pub fn new() -> OpenEnums {
        OpenEnums::default()
    }

    /// Registers the type `T` as variant of the open enum `O`.
    ///
    /// `O` is the trait object (`dyn Trait`).  Registering a type again
    /// does nothing.  Fails if the name of the variant (or one of its
    /// aliases) is the one of another variant (with
    /// [`ErrorKind::Configuration`]), unless the open enum is untagged
    /// (where the names are only used in descriptions and errors).
    pub fn register<O: ?Sized + OpenEnum, T: OpenVariant<O>>(
        &mut self,
    ) -> Result<&mut OpenEnums, Error> {
        let entry = T::ENTRY;
        let info = O::INFO;
        let ty = TypeId::of::<T>();
        let registered = self
            .enums
            .entry(TypeId::of::<O>())
            .or_insert_with(|| Registered {
                name: info.name,
                names: Vec::new(),
                table: Box::new(Table::<O> {
                    variants: Vec::new(),
                    tags: Vec::new(),
                }),
            });
        let table = registered
            .table
            .downcast_mut::<Table<O>>()
            .expect("the table of an open enum has the type of the open enum");
        if table.variants.iter().any(|variant| variant.ty == ty) {
            return Ok(self);
        }
        let tags = match info.repr {
            OpenRepr::Untagged => Vec::new(),
            _ => entry.tags(info),
        };
        for tag in &tags {
            if let Ok(index) = table.tags.binary_search_by(|(other, _)| other.cmp(tag)) {
                return Err(Error::new(
                    ErrorKind::Configuration,
                    alloc::format!(
                        "duplicate variant `{}` of {}: `{}` and `{}`",
                        tag_display(*tag),
                        info.name,
                        table.variants[table.tags[index].1].type_name,
                        type_name::<T>(),
                    ),
                ));
            }
        }
        let variant = table.variants.len();
        table.variants.push(Registration {
            ty,
            type_name: type_name::<T>(),
            make: make_variant::<O, T>,
            try_untagged: try_variant::<O, T>,
        });
        for tag in tags {
            let index = table
                .tags
                .binary_search_by(|(other, _)| other.cmp(&tag))
                .unwrap_err();
            table.tags.insert(index, (tag, variant));
        }
        let name = entry.display_name(info);
        let index = registered.names.binary_search(&name).unwrap_or_else(|x| x);
        registered.names.insert(index, name);
        Ok(self)
    }

    /// Returns the variants of an open enum.
    #[inline]
    fn get<O: ?Sized + OpenEnum>(&self) -> Option<&Registered> {
        self.enums.get(&TypeId::of::<O>())
    }

    /// Looks up the variant of an open enum by tag.
    #[inline]
    fn lookup<O: ?Sized + OpenEnum>(&self, tag: Tag<'_>) -> Option<MakeVariant<O>> {
        let table = self.get::<O>()?.table.downcast_ref::<Table<O>>()?;
        let index = table
            .tags
            .binary_search_by(|(other, _)| other.cmp(&tag))
            .ok()?;
        Some(table.variants[table.tags[index].1].make)
    }

    /// Returns the variant of an untagged open enum with the given index.
    #[inline]
    fn untagged<O: ?Sized + OpenEnum>(&self, index: usize) -> Option<TryVariant<O>> {
        let table = self.get::<O>()?.table.downcast_ref::<Table<O>>()?;
        Some(table.variants.get(index)?.try_untagged)
    }
}

impl fmt::Debug for OpenEnums {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_map()
            .entries(
                self.enums
                    .values()
                    .map(|registered| (registered.name, &registered.names)),
            )
            .finish()
    }
}

impl Serialize for Tag<'_> {
    fn serialize<'a>(value: &'a Self, _state: &mut State) -> Result<Emit<'a>, Error> {
        Ok(Emit::Atom(match *value {
            Tag::Str(name) => Atom::Str(Text::borrowed(name)),
            Tag::U64(value) => Atom::U64(value),
            Tag::I64(value) => Atom::I64(value),
            Tag::Bool(value) => Atom::Bool(value),
        }))
    }
}

/// Returns how a variant is described.
fn variant_repr(repr: OpenRepr) -> VariantRepr<'static> {
    match repr {
        OpenRepr::External => VariantRepr::External,
        OpenRepr::Internal { tag } => VariantRepr::Internal { tag: tag.name },
        OpenRepr::Adjacent { tag, content, .. } => VariantRepr::Adjacent {
            tag: tag.name,
            content: content.name,
        },
        OpenRepr::Untagged => VariantRepr::Untagged,
    }
}

/// Serializes the trait object of an open enum.
pub fn serialize<'a, O: ?Sized + OpenEnum>(
    value: &'a O,
    state: &mut State,
) -> Result<Emit<'a>, Error> {
    let VariantValue { entry, content } = O::__private_variant(value);
    let info = O::INFO;
    Ok(match info.repr {
        OpenRepr::External => match entry.name_str(info) {
            Some(name) => {
                FieldsSer(Vec::from([(name, SerializeHandle::from(content))])).into_emit(state)
            }
            None => EntrySer::new(entry.name_handle(info), SerializeHandle::from(content))
                .into_emit(state),
        },
        OpenRepr::Internal { tag } => {
            TaggedNewtype::new(tag.name, entry.name_handle(info), content).into_emit(state)
        }
        OpenRepr::Adjacent {
            tag,
            content: content_key,
            ..
        } => FieldsSer(Vec::from([
            (tag.name, entry.name_handle(info)),
            (content_key.name, SerializeHandle::from(content)),
        ]))
        .into_emit(state),
        OpenRepr::Untagged => Emit::Forward(SerializeHandle::from(content)),
    })
}

/// Describes the trait object of an open enum.
pub fn describe<O: ?Sized + OpenEnum>(value: &O, d: &mut dyn Describe) {
    let VariantValue { entry, content } = O::__private_variant(value);
    let name = entry.display_name(O::INFO);
    let repr = O::INFO.repr;
    d.variant(&Variant::new(
        O::INFO.name,
        &name,
        VariantKind::Newtype,
        variant_repr(repr),
    ));
    // the fields of the content are merged with the tag, like for newtype
    // variants of internally tagged enums, untagged variants are their
    // content
    if let OpenRepr::Internal { .. } | OpenRepr::Untagged = repr {
        content.describe(d);
    }
}

/// Returns the shape of the trait object of an open enum.
pub fn container_shape<O: ?Sized + OpenEnum>() -> ContainerShape {
    match O::INFO.repr {
        OpenRepr::External => ContainerShape::with_len(1),
        OpenRepr::Internal { .. } => ContainerShape::new(),
        OpenRepr::Adjacent { .. } => ContainerShape::with_len(2),
        // the content provides its own shape (the value forwards to it)
        OpenRepr::Untagged => ContainerShape::new(),
    }
}

/// Looks up the variant of an open enum by its tag.
fn lookup<'a, 'de: 'a, O: ?Sized + OpenEnum>(
    tag: Tag<'_>,
    state: &mut State,
) -> Option<ArenaVariant<'a, 'de, Box<O>>> {
    let make = match state.get::<OpenEnums>() {
        Some(registry) if registry.get::<O>().is_some() => registry.lookup::<O>(tag)?,
        _ => return Some(ArenaVariant::new(Unregistered::<O>::new(), state)),
    };
    Some(make(state, PhantomData))
}

/// Tries the variant of an untagged open enum with the given index.
///
/// Returns `false` if there is no such variant.
fn untagged_variants<'de, O: ?Sized + OpenEnum>(
    index: usize,
    attempt: &mut UntaggedTry<'_, 'de, Box<O>>,
) -> bool {
    let try_variant = match attempt.state().get::<OpenEnums>() {
        Some(registry) => registry.untagged::<O>(index),
        None => None,
    };
    match try_variant {
        Some(try_variant) => {
            try_variant(attempt);
            true
        }
        None => false,
    }
}

/// Returns the error for a value that no variant of an untagged open enum
/// accepted.
///
/// Without registered variants no variant is tried, which is an error of
/// the configuration (like for tagged open enums).
#[cold]
fn untagged_no_match<O: ?Sized + OpenEnum>(name: &str, state: &State) -> Error {
    let registered = state
        .get::<OpenEnums>()
        .is_some_and(|registry| registry.get::<O>().is_some());
    if !registered {
        return Unregistered::<O>::new().error();
    }
    no_matching_variant(name, state)
}

/// Returns the names of the variants of an open enum for errors.
fn names<O: ?Sized + OpenEnum>(state: &State) -> Vec<&str> {
    match state
        .get::<OpenEnums>()
        .and_then(|registry| registry.get::<O>())
    {
        Some(registered) => registered.names.iter().map(|name| &**name).collect(),
        None => Vec::new(),
    }
}

/// No variant is a unit variant (the variants are given as a tag receive a
/// null as content).
fn no_unit<E>(_tag: Tag<'_>) -> Option<E> {
    None
}

/// Deserializes the trait object of an open enum in a box.
pub fn deserialize_box<'out, 'de, O: ?Sized + OpenEnum>(
    out: &'out mut Option<Box<O>>,
    state: &mut State,
) -> SinkHandle<'out, 'de> {
    let name = O::INFO.name;
    if let OpenRepr::Untagged = O::INFO.repr {
        return untagged_handle_with(
            out,
            name,
            untagged_variants::<O>,
            untagged_no_match::<O>,
            state,
        );
    }
    let variants = Variants {
        lookup: lookup::<O>,
        other: None,
        default: None,
        names: VariantNames::Dynamic(names::<O>),
    };
    match O::INFO.repr {
        OpenRepr::External => ExternallyTaggedSink::handle(out, name, variants, no_unit, state),
        OpenRepr::Internal { tag } => InternallyTaggedSink::handle(out, tag, name, variants, state),
        OpenRepr::Adjacent {
            tag,
            content,
            deny_unknown_fields,
        } => AdjacentlyTaggedSink::handle(
            out,
            tag,
            content,
            name,
            variants,
            deny_unknown_fields,
            state,
        ),
        OpenRepr::Untagged => unreachable!("untagged open enums are handled above"),
    }
}

/// Deserializes the trait object of an open enum in an `Arc`.
pub fn deserialize_arc<'out, 'de, O: ?Sized + OpenEnum>(
    out: &'out mut Option<Arc<O>>,
    state: &mut State,
) -> SinkHandle<'out, 'de>
where
    Box<O>: Deserialize<'de>,
{
    mapped(
        out,
        OwnedSink::<Box<O>>::deserialize(state),
        |value| Ok(Arc::from(value)),
        state,
    )
}

/// The builder of the variants of an open enum which has no registered
/// variants: the registry is missing from the context.
struct Unregistered<O: ?Sized>(PhantomData<fn() -> Box<O>>);

impl<O: ?Sized + OpenEnum> Unregistered<O> {
    fn new() -> Self {
        Unregistered(PhantomData)
    }

    fn error(&self) -> Error {
        Error::new(
            ErrorKind::Configuration,
            alloc::format!(
                "no variants of {} are registered (register them in a deser::OpenEnums \
                 that is given in the context)",
                O::INFO.name
            ),
        )
    }
}

impl<'de, O: ?Sized + OpenEnum> VariantBuilder<'de, Box<O>> for Unregistered<O> {
    fn sink(&mut self) -> &mut dyn Sink<'de> {
        self
    }

    fn build(&mut self) -> Option<Box<O>> {
        None
    }
}

impl<'de, O: ?Sized + OpenEnum> Sink<'de> for Unregistered<O> {
    fn atom(&mut self, _atom: Atom, _state: &mut State) -> Result<(), Error> {
        Err(self.error())
    }

    fn map(&mut self, _state: &mut State) -> Result<(), Error> {
        Err(self.error())
    }

    fn seq(&mut self, _state: &mut State) -> Result<(), Error> {
        Err(self.error())
    }

    fn finish(&mut self, _state: &mut State) -> Result<(), Error> {
        Err(self.error())
    }
}