structio 0.8.0

//! The traits and constants that do not belong to any one format.
//!
//! A struct's *schema* is format independent: the same field list, in the same
//! order, under the same keys, whether it is going out as JSON text or BEVE
//! binary. That schema is [`Keys`], and the [`object!`](crate::object) macro
//! generates it once per type. A struct declared positionally has no keys to
//! share, only a length: that is [`Elements`], from [`array!`](crate::array).
//! An enum shares its variant names, which is [`Variants`], from
//! [`unit_enum!`](crate::unit_enum) and [`tagged_enum!`](crate::tagged_enum).
//!
//! Everything downstream of the schema is format specific and lives in
//! [`json`](crate::json) and [`beve`](crate::beve): each has its own `Read`,
//! `Write`, `ReadObject`, and `WriteObject`.

use core::marker::PhantomData;

use crate::keymap::KeyMap;
use crate::options::Options;

/// The key schema of a struct, and its compile-time perfect hash.
///
/// Shared by every format, because the keys are a property of the type rather
/// than of the encoding. JSON looks a key up out of a quoted run of document
/// bytes and BEVE out of a length-prefixed one, but both land in the same
/// table and yield the same field index.
pub trait Keys {
    /// Every key the schema answers to: one per field, in declaration order,
    /// and then the aliases.
    ///
    /// Index `i` is what the hash hands back and what each format's
    /// `read_field` dispatches on. Below the field count, which is
    /// `KEYS.len() - ALIASES.len()`, it is field `i`, and `KEYS[i]` is the
    /// key `write_fields` writes that field under. At or above it the key is
    /// an alias, and [`ALIASES`](Keys::ALIASES) says whose.
    const KEYS: &'static [&'static str];

    /// For each alias in [`KEYS`](Keys::KEYS), the field it fills.
    ///
    /// An alias is a further name a document may use for a field that already
    /// has one: read under any of them, written under the declared one. The
    /// aliases follow the fields in [`KEYS`](Keys::KEYS), so `ALIASES[j]` is
    /// the field of key `KEYS[KEYS.len() - ALIASES.len() + j]`.
    ///
    /// Empty by default: every key is then a field's own, and the index the
    /// hash returns is the field index itself.
    ///
    /// Written by [`object!`](crate::object) from the `| "alias"` clauses in a
    /// declaration. A hand-written impl that sets it must put its aliases last
    /// and name no field past the field count: an entry that named one would
    /// credit a member to a field that is not there, and the bit it set could
    /// leave [`REQUIRED`](Keys::REQUIRED) unsatisfiable.
    const ALIASES: &'static [u8] = &[];

    /// The perfect hash over [`Keys::KEYS`], built during const evaluation.
    ///
    /// Over the whole list, aliases included, which is what makes one lookup
    /// enough to find a field under any of its names.
    ///
    /// A reference rather than a value, so the table lives in read-only memory
    /// and is never copied onto the stack at a call site.
    const MAP: &'static KeyMap;

    /// Bit `i` set for each field that a document must supply, in
    /// [`KEYS`](Keys::KEYS) order.
    ///
    /// Where [`Options::ERROR_ON_MISSING_KEYS`] is the reader's answer to "may
    /// a member be left out", this is the type's, and the two are a union: a
    /// field marked here is required under every policy, and
    /// [`RequireKeys`](crate::RequireKeys) requires every field whether or not
    /// any is marked. Absence is otherwise no error, so the default is zero and
    /// a schema that says nothing about it reads exactly as it did before.
    ///
    /// Written by [`object!`](crate::object) from the `#[required]` markers in
    /// a declaration. A hand-written impl may set it directly, and should set
    /// no bit past the end of [`KEYS`](Keys::KEYS): such a bit asks for a field
    /// that cannot be filled, so no reading under the default policy would ever
    /// succeed, while [`RequireKeys`](crate::RequireKeys) would discard it
    /// along with the rest of the mask and accept the same document.
    ///
    /// **A marked field must be one of the first 64 declared.** The mask is a
    /// `u64`, and a field past that has no bit to set. Marking one is a build
    /// error naming the limit, reported when the crate is built rather than by
    /// `cargo check`, the mask being a constant of a generic type.
    ///
    /// The struct itself may be wider: only the fields that are marked need
    /// room here, unlike
    /// [`ERROR_ON_MISSING_KEYS`](Options::ERROR_ON_MISSING_KEYS), which needs a
    /// bit for every one and so caps the whole struct.
    ///
    /// [`Options::ERROR_ON_MISSING_KEYS`]: crate::Options::ERROR_ON_MISSING_KEYS
    const REQUIRED: u64 = 0;
}

/// The variant names of an enum, and their compile-time perfect hash.
///
/// The enum counterpart of [`Keys`], and shared by every format for the same
/// reason: which variants there are and what they are called is a property of
/// the type, not of the encoding. A name goes out as a JSON string or as a
/// BEVE one, but both land in the same table and yield the same variant index.
///
/// Generated by [`unit_enum!`](crate::unit_enum) and
/// [`tagged_enum!`](crate::tagged_enum).
pub trait Variants {
    /// Every name the enum answers to: one per variant, in declaration order,
    /// and then the aliases.
    ///
    /// Index `i` is what the hash hands back. Below the variant count, which
    /// is `VARIANTS.len() - ALIASES.len()`, it is variant `i`, and
    /// `VARIANTS[i]` is the name that variant is written under. At or above it
    /// the name is an alias, and [`ALIASES`](Variants::ALIASES) says whose.
    const VARIANTS: &'static [&'static str];

    /// For each alias in [`VARIANTS`](Variants::VARIANTS), the variant it
    /// names.
    ///
    /// [`Keys::ALIASES`] for an enum, and the same in every respect: a further
    /// name a document may use for a variant that already has one, accepted on
    /// read and never written, laid out after the variants so that
    /// `ALIASES[j]` is the variant of
    /// `VARIANTS[VARIANTS.len() - ALIASES.len() + j]`.
    ///
    /// Empty by default, which leaves the index the hash returns the variant
    /// index itself, as [`Keys::ALIASES`] does for a field.
    const ALIASES: &'static [u8] = &[];

    /// The perfect hash over [`Variants::VARIANTS`], built during const
    /// evaluation.
    ///
    /// A reference rather than a value, for [`Keys::MAP`]'s reason: the table
    /// lives in read-only memory and is never copied onto the stack.
    const MAP: &'static KeyMap;
}

/// Put a key index back on the field it fills.
///
/// The hash indexes [`Keys::KEYS`], which holds the fields and then the
/// aliases, so a member written under an alias comes back with an index past
/// the last field. Every reader resolves it here, once, before the generated
/// dispatch sees it. Two things fall out of doing it in one place: the
/// dispatch has an arm per field rather than per key, and the seen mask that
/// [`Keys::REQUIRED`] is checked against gets the field's bit, so a required
/// member supplied under an alias is a member supplied.
///
/// [`ALIASES`](Keys::ALIASES) is empty wherever a schema declares no alias,
/// which is a constant, so this is gone from the reader entirely.
#[inline(always)]
pub(crate) fn resolve_key<T: Keys>(index: usize) -> usize {
    if const { T::ALIASES.is_empty() } {
        return index;
    }
    let fields = T::KEYS.len() - T::ALIASES.len();
    if index < fields {
        index
    } else {
        T::ALIASES[index - fields] as usize
    }
}

/// [`resolve_key`] for an enum's variant names.
#[inline(always)]
pub(crate) fn resolve_variant<T: Variants>(index: usize) -> usize {
    if const { T::ALIASES.is_empty() } {
        return index;
    }
    let variants = T::VARIANTS.len() - T::ALIASES.len();
    if index < variants {
        index
    } else {
        T::ALIASES[index - variants] as usize
    }
}

/// The bookkeeping behind [`Options::ERROR_ON_MISSING_KEYS`] and
/// [`Keys::REQUIRED`], and the one place a struct too wide for the first is
/// refused.
///
/// An object reader sets bit `i` when it fills field `i`; an object that ends
/// holding anything less than [`MASK`](Fields::MASK) left a member out that
/// either the policy or the type insisted on.
pub(crate) struct Fields<O, T>(PhantomData<fn(O, T)>);

impl<O: Options, T: Keys> Fields<O, T> {
    /// How many of [`Keys::KEYS`] are fields rather than aliases, which is
    /// what the mask below has a bit apiece for.
    const FIELDS: usize = T::KEYS.len() - T::ALIASES.len();

    /// The bits an object has to end up holding: every field under a policy
    /// that requires them all, and otherwise the ones the type marked.
    ///
    /// Zero when neither asks for anything, which makes the comparison against
    /// it `0 != 0` and takes the whole check out of the reader.
    ///
    /// The assertion is the 64-field cap, and it sits inside the branch that
    /// needs it rather than in front of both. Const evaluation follows the
    /// control flow, so a struct too wide for a bit per field stays perfectly
    /// legal for every reading that does not ask for one -- which is every
    /// reading under the default policy, whatever the type marks.
    ///
    /// Being a constant of a generic type, it is refused when the crate is
    /// built rather than by `cargo check`.
    pub(crate) const MASK: u64 = if O::ERROR_ON_MISSING_KEYS {
        let n = Self::FIELDS;
        assert!(
            n <= 64,
            "ERROR_ON_MISSING_KEYS tracks one bit per field in a u64, \
             so it cannot read a struct of more than 64 fields"
        );
        if n == 64 { u64::MAX } else { (1u64 << n) - 1 }
    } else {
        T::REQUIRED
    };

    /// Whether a filled field is worth recording. False leaves `seen` a
    /// constant zero and the `|=` in the read loop unreachable.
    pub(crate) const TRACK: bool = Self::MASK != 0;

    /// Whether every field has a bit, which is every struct the 64-field cap
    /// admits.
    const NARROW: bool = Self::FIELDS <= 64;

    /// The first key the mask asked for that `seen` does not hold.
    ///
    /// Which of several absent members it names is the declaration order,
    /// which is stable and is where a person reading the schema would look.
    ///
    /// `get` rather than an index, and so `None` rather than a panic, because
    /// [`Keys`] is a public trait and a hand-written impl may set a
    /// [`REQUIRED`](Keys::REQUIRED) bit past the end of its own
    /// [`KEYS`](Keys::KEYS): an unsatisfiable schema, which its own
    /// documentation allows, but not a reason for a diagnostic to panic.
    pub(crate) fn missing(seen: u64) -> Option<&'static str> {
        let i = (Self::MASK & !seen).trailing_zeros() as usize;
        T::KEYS.get(i).copied()
    }

    /// Bit `index` of the seen mask, or nothing for a field the mask has no
    /// room for.
    ///
    /// `index` is a field, [`resolve_key`] having already
    /// put an alias back on the field it fills, so a member the schema
    /// requires is supplied under any of its names.
    ///
    /// The comparison is live only for a struct of more than 64 fields that
    /// marks one of its first 64 required, [`MASK`](Fields::MASK) having
    /// refused every other wide reading. Anywhere else `NARROW` is a constant
    /// `true` and this is the shift alone.
    #[inline(always)]
    pub(crate) const fn seen(index: usize) -> u64 {
        if Self::NARROW || index < 64 {
            1u64 << index
        } else {
            0
        }
    }
}

/// Convenience bound for generic containers: readable and writable in every
/// format this crate supports, from any input.
///
/// [`object!`](crate::object) generates impls for all formats at once, so a
/// generic struct's type parameter needs all of them. This is the bound to
/// write:
///
/// ```
/// #[derive(Default)]
/// struct Page<T> {
///     items: Vec<T>,
///     cursor: Option<String>,
/// }
/// structio::object!([T: structio::ReadWrite + Default] Page<T> { items, cursor });
/// ```
///
/// `Default` is separate because [`ReadWrite`] does not imply it: reading
/// *into* a `Page<T>` constructs nothing, but reading one builds a `T` per
/// element of `items`. Where a bound has to produce the value rather than fill
/// it, [`ReadOwned`] folds the two together.
///
/// Types that borrow from the input do not satisfy this, exactly as they do
/// not satisfy an "owned" bound elsewhere in the ecosystem. For a struct that
/// is only ever used with one format, the narrower [`json::ReadWrite`] or
/// [`beve::ReadWrite`] will do.
///
/// [`json::ReadWrite`]: crate::json::ReadWrite
/// [`beve::ReadWrite`]: crate::beve::ReadWrite
#[diagnostic::on_unimplemented(
    note = "this is `Read` and `Write` in both formats at once, the bound a \
            declaration appends to every type parameter; one \
            `structio::object!` or `#[derive(Structio)]` declaration covers \
            both halves",
    note = "a `write_only` declaration appends `structio::Write` instead, \
            which is this without the read half"
)]
pub trait ReadWrite: crate::json::ReadWrite + crate::beve::ReadWrite {}
impl<T> ReadWrite for T where T: crate::json::ReadWrite + crate::beve::ReadWrite {}

/// Convenience bound for generic containers that are only ever written:
/// writable in every format this crate supports.
///
/// The write-only counterpart of [`ReadWrite`]. A declaration that leads with
/// `write_only` generates no read impls, so a generic one bounds its type
/// parameters by this instead, and a type parameter of such a declaration
/// needs no `Default` either: nothing constructs a value it would have to fill.
///
/// ```
/// struct Sample<T> {
///     value: T,
/// }
/// structio::object!(write_only [T: structio::Write] Sample<T> { value });
/// ```
///
/// For a type that is only ever written in one format, the narrower
/// [`json::Write`] or [`beve::Write`] will do.
///
/// Unlike [`ReadWrite`] this does not require `Sized`: `str` and `[u8]` are
/// writable, and it is reading that has to have somewhere to put the value.
///
/// There is no bare `Read` counterpart at this level. The direction axis
/// narrows only to the write half, because a read bound has to say which
/// lifetime it reads at; [`ReadOwned`] is the read-side bound, for the case
/// where the answer is "any".
///
/// [`json::Write`]: crate::json::Write
/// [`beve::Write`]: crate::beve::Write
#[diagnostic::on_unimplemented(
    note = "this is `Write` in both formats at once, the bound a `write_only` \
            declaration appends to every type parameter; one \
            `structio::object!(write_only ..)` or `#[structio(write_only)]` \
            declaration covers it"
)]
pub trait Write: crate::json::Write + crate::beve::Write {}
impl<T: ?Sized> Write for T where T: crate::json::Write + crate::beve::Write {}

/// Convenience bound for a function that parses a `T` out of a document it
/// owns: readable in every format this crate supports, from any input, and
/// constructible.
///
/// The read-side counterpart of [`ReadWrite`], and the bound for a generic that
/// does not learn until run time which format it was handed:
///
/// ```
/// fn decode<T: structio::ReadOwned>(json: bool, body: &[u8]) -> structio::Result<T> {
///     if json {
///         structio::json::from_slice(body)
///     } else {
///         structio::beve::from_slice(body)
///     }
/// }
/// ```
///
/// That is the shape worth spending both halves on. A generic that reads one
/// format should take the narrower [`json::ReadOwned`] or [`beve::ReadOwned`]
/// rather than demand an impl it never uses.
///
/// [`json::ReadOwned`] carries the full account of why the read half is
/// higher-ranked and why [`Default`] is part of the bound.
///
/// [`json::ReadOwned`]: crate::json::ReadOwned
/// [`beve::ReadOwned`]: crate::beve::ReadOwned
#[diagnostic::on_unimplemented(
    note = "this is `Read` in both formats from a document of any lifetime, \
            plus `Default`: the bound for a function that hands back a value \
            parsed out of a buffer it owns",
    note = "for one format only, `structio::json::ReadOwned` or \
            `structio::beve::ReadOwned` is the narrower bound"
)]
pub trait ReadOwned: crate::json::ReadOwned + crate::beve::ReadOwned {}
impl<T> ReadOwned for T where T: crate::json::ReadOwned + crate::beve::ReadOwned {}

/// The length of a struct encoded as a positional array.
///
/// The array counterpart of [`Keys`], and shared by every format for the same
/// reason: which fields there are and what order they come in is a property of
/// the type, not of the encoding. JSON writes them between brackets and BEVE
/// behind a generic-array header, but both write the same values in the same
/// order, and both refuse a document that holds a different number of them.
///
/// Generated by [`array!`](crate::array), which unlike [`object!`](crate::object)
/// emits no key list and no hash table: an element is found by counting, so
/// there is nothing to look up.
pub trait Elements {
    /// How many elements the encoded array has. Always the field count.
    const LEN: usize;
}

macro_rules! impl_tuple_elements {
    ($n:expr; $($name:ident),+) => {
        impl<$($name),+> Elements for ($($name,)+) {
            const LEN: usize = $n;
        }
    };
}

// A tuple is an array-encoded struct whose fields happen to have no names, so
// it reaches the same drivers through the same trait.
impl_tuple_elements!(1; A);
impl_tuple_elements!(2; A, B);
impl_tuple_elements!(3; A, B, C);
impl_tuple_elements!(4; A, B, C, D);
impl_tuple_elements!(5; A, B, C, D, E);
impl_tuple_elements!(6; A, B, C, D, E, F);
impl_tuple_elements!(7; A, B, C, D, E, F, G);
impl_tuple_elements!(8; A, B, C, D, E, F, G, H);
impl_tuple_elements!(9; A, B, C, D, E, F, G, H, I);
impl_tuple_elements!(10; A, B, C, D, E, F, G, H, I, J);
impl_tuple_elements!(11; A, B, C, D, E, F, G, H, I, J, K);
impl_tuple_elements!(12; A, B, C, D, E, F, G, H, I, J, K, L);

/// The identity adapter: read and write this position the way the type itself
/// would.
///
/// Adapters compose as types do, so a container adapter needs something to
/// name at a position that wants no adapting. `Vec<Same>` reads a `Vec<T>`
/// element for element as `Vec<T>`'s own impl does, and
/// `HashMap<Same, Millis>` adapts only a map's values, leaving its keys to
/// [`FromJsonKey`](crate::json::FromJsonKey) and
/// [`FromBeveKey`](crate::beve::FromBeveKey).
///
/// One type rather than one per format, because a declaration names a single
/// adapter and the macro emits it against [`json::ReadAs`](crate::json::ReadAs),
/// [`json::WriteAs`](crate::json::WriteAs),
/// [`beve::ReadAs`](crate::beve::ReadAs) and
/// [`beve::WriteAs`](crate::beve::WriteAs) alike. A per-format `Same` could
/// not be written at a field at all.
///
/// It is an identity on the bytes too, not only on the values, and in both
/// directions: `Same` forwards BEVE's
/// [`Write::ARRAY`](crate::beve::Write::ARRAY), so a `Vec<Same>` over a
/// `Vec<f64>` is still one typed array rather than a value per element, and it
/// forwards [`Read::read_bulk`](crate::beve::Read::read_bulk), so reading that
/// array back is still the single `memcpy` the unadapted field would have got.
///
/// Neither is true of an adapter in general, and neither should be. An adapter
/// with a conversion to do has no block to copy, so it leaves both alone and
/// gets a generic array and an element-by-element read. What `Same` shows is
/// that the ceiling is the adapter's, not the mechanism's: an adapter over a
/// type whose memory is already a payload can reach the same two paths, which
/// is what [`NumericBytes`](crate::beve::NumericBytes) is implementable for.
pub struct Same;

/// Refuse an internally tagged declaration whose tag is also a field of the
/// variant's payload.
///
/// The two share one object, so a collision writes the name twice:
/// `{"kind":"Config","kind":"debug"}`. This crate reads that back, taking the
/// first member as the tag, and a last-wins parser does not: it resolves the
/// name to the payload's value and the variant is gone. The field is
/// unreadable here as well, the tag having been consumed before the payload's
/// members are reached, so the configuration is dead in both directions rather
/// than merely unwise.
///
/// `ctor` is never called. A tuple variant's constructor is a value of type
/// `fn(P) -> E`, so naming it is what tells this function what `P` is: the
/// payload's type is deliberately absent from the declaration, and the
/// constructor is the one place the macro can reach it without asking for it
/// twice. `tag` is an ordinary argument rather than an associated constant
/// because the call sites are const contexts holding the literal, which is
/// what keeps this free of any trait the enum would have to implement.
///
/// [`tagged_enum!`](crate::tagged_enum) calls it, for a declaration carrying a
/// tag clause, from an item-level `const`, so with no generics it is evaluated
/// by `cargo check`. A generic one has no keys until it is instantiated, and
/// is checked from the write path's own `const` block instead, which is
/// [`Keys::REQUIRED`]'s tier: reported when the crate is built.
///
/// Comparing bytes rather than `==`, `str` equality not being callable in a
/// const context on this crate's minimum compiler.
pub const fn assert_tag_not_a_field<P: Keys, E>(tag: &str, _ctor: fn(P) -> E) {
    let keys = <P as Keys>::KEYS;
    let tag = tag.as_bytes();
    let mut i = 0;
    while i < keys.len() {
        let key = keys[i].as_bytes();
        if key.len() == tag.len() {
            let mut j = 0;
            while j < key.len() && key[j] == tag[j] {
                j += 1;
            }
            if j == key.len() {
                ::core::panic!(
                    "structio: the tag of an internally tagged enum is also a field of this \
                     variant's payload, or an alias of one. The two share one object, so the \
                     name would be written twice and a last-wins parser would keep the field \
                     and lose the variant. Rename the field, or choose another tag."
                );
            }
        }
        i += 1;
    }
}