Enum KeySegment 

pub enum KeySegment {
    Excluded,
    Simple(Arc<str>),
    Object(Arc<str>, Arc<KeySegment>),
    Array(Arc<str>, Identifier, Arc<str>, Arc<KeySegment>),
    InnerObject(Identifier, Arc<str>, Arc<KeySegment>),
    PlainArray(Arc<str>),
}

Describes where a column’s cell value lands in the (possibly nested) output row. Recursive variants wrap their continuation in Arc (not Box) to keep the type’s size finite – same reasoning as Format::Array’s Arc<Format>: Column (and therefore its key: Option<KeySegment>) is cloned repeatedly by resolve_columns() during column resolution, so an O(1) refcount bump matters here the same way it does for Format. Nothing in this tree needs Box’s unique-ownership guarantee.

Variants

Excluded

Column is fully omitted from output.

Simple(Arc<str>)

Flat leaf – today’s only behavior, insert directly under this key.

Object(Arc<str>, Arc<KeySegment>)

Descend into (creating if needed) a plain nested object under this key, then continue the rest of the path inside it.

Array(Arc<str>, Identifier, Arc<str>, Arc<KeySegment>)

Find-or-create an item in the named array whose key_field equals identifier, then continue the rest of the path inside that item. Two columns land in the same item only when their entire chain of Array/InnerObject identifiers agree, not just this one segment – see matching_signature below.

InnerObject(Identifier, Arc<str>, Arc<KeySegment>)

Inline a literal-valued field on the current item (no new nesting level), then continue the rest of the path in the same item. Used to flatten multiple discriminators onto one array item instead of nesting each one.

PlainArray(Arc<str>)

Push the column’s own resolved value directly into the named array, as a bare scalar – no wrapping object, no discriminator, always appended. Distinct from Array, whose items are always objects (at least the key_field is set) – there’s no way to get a plain array of raw values through Array/InnerObject alone. Order is whatever order the matched columns were processed in (column position in the sheet), the same choice already made for the analogous numbered-fields-to-array case at the spread-cli layer.

Implementations

impl KeySegment

pub fn from_json(json: &Value) -> Option<Self>

Parses a KeySegment from JSON – the primary way any client crate (a frontend UI building a JSON payload, a Web API, etc.) reaches the full tree without writing Rust or touching calamine/csv directly. A plain JSON string is shorthand for Simple (matches Column.key’s existing plain-string convention); anything else needs a tagged object with a "type" field selecting the variant:

• "excluded" – no other fields
• "simple" – "key" (string)
• "object" – "key" (string), "next" (nested KeySegment)
• "array" – "container" (string), "identifier" (string or number), "key_field" (string), "next" (nested KeySegment)
• "inner_object" – "identifier" (string or number), "field" (string), "next" (nested KeySegment)
• "plain_array" – "container" (string)

Returns None on anything malformed (unknown type, missing/wrong-typed field) – same sanitize-don’t-guess stance as the rest of this crate’s parsing.

Trait Implementations

impl Clone for KeySegment

fn clone(&self) -> KeySegment

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KeySegment

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for KeySegment

fn fmt(&self, f: &mut Formatter<'_>) -> Result

A flat, single-string fallback for contexts that only ever show one name per column (header/metadata listings) – not a serialization of the whole tree. Shows the outermost field name at this segment; nested detail is only ever realized by insert_key_segment when actually building a row.

impl PartialEq for KeySegment

fn eq(&self, other: &KeySegment) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for KeySegment