Struct Flat 

pub struct Flat { /* private fields */ }

The flat API: every #[prebindgen] item from every ingested source, parsed, indexed by name, and with every type reference resolved.

Direct access, not a stream

Names are unique across the whole model — a duplicate is a ParseError::DuplicateName — so a name is a complete address, and the model answers by it. That is what every later stage needs: an adapter asks what a declared name is, rather than scanning a list for it.

References are already resolved

Every TypeKind::Named in a surviving element denotes a Type this model holds, and Self::resolve hands it over. An item that named something the flat API does not declare is Element::Unsupported with ItemError::UnresolvedType, exactly like every other refusal — carried here, raised by Registry ingestion.

Resolving here rather than in the adapters is the point of #211: a dangling name used to surface much later as an unresolved-converter error, from whichever adapter happened to look first.

Implementations

impl Flat

pub fn builder() -> FlatBuilder

Start collecting what to parse.

pub fn elements(&self) -> impl Iterator<Item = &Element>

Every element, in the order the sources were fed.

pub fn element<N>(&self, name: &N) -> Option<&Element>

where N: Name + ?Sized,

The element with this name, whatever kind it is — including an Element::Unsupported, which still holds its name against the namespace.

pub fn function<N>(&self, name: &N) -> Option<&Function>

where N: Name + ?Sized,

pub fn declared_type<N>(&self, name: &N) -> Option<&Type>

where N: Name + ?Sized,

The type declared under this name.

Named declared_type because type is a keyword; it is the accessor a resolved TypeKind::Named reference leads to, and Self::resolve is the same lookup taking a TypeId.

pub fn constant<N>(&self, name: &N) -> Option<&Constant>

where N: Name + ?Sized,

pub fn functions(&self) -> impl Iterator<Item = &Function>

pub fn types(&self) -> impl Iterator<Item = &Type>

pub fn constants(&self) -> impl Iterator<Item = &Constant>

pub fn struct_type<N>(&self, name: &N) -> Option<&Struct>

where N: Name + ?Sized,

The struct declared under this name, or None for any other shape.

A tuple struct is an Extern rather than a Struct, so this answers only for a product of fields that cross the boundary.

pub fn enum_item<N>(&self, name: &N) -> Option<&ItemEnum>

where N: Name + ?Sized,

The syn::ItemEnum behind either enum shape.

A sum and a C-style enum are different elements — numbered differently and consumed as different constructs — but both were spelled enum in Rust and both keep that item. A consumer re-emitting the source wants the item without caring which shape it is; one that acts on the distinction reaches for Self::declared_type.

pub fn source_modules(&self) -> &[String]

Module name of every captured source, in first-seen order.

The first entry is the default module for a reference with no recorded origin. Empty for a hand-built stream that carried no crate stamps.

pub fn guards(&self) -> impl Iterator<Item = &Guard>

Every anonymous const, in stream order — zero or more.

Not part of the flat API — see Guard — but ingested with it, and a consumer that re-emits the source must re-emit these too.

pub fn type_ref(&self, ty: &Type) -> Option<&TypeRef>

This module’s reading of ty, if the flat API mentions that type.

None means no captured item and no binding-local fn writes this type — it is one the binding invented, and there is nothing for the frontend to have decided about it.

The argument is normalized the way TypeKey does before lookup, so an adapter-authored spelling finds the same entry a captured one does.

pub fn classify(&self, ty: &Type) -> Result<TypeRef, UnsupportedType>

This module’s reading of ty — the index’s if the source wrote it, freshly lowered if not.

Answers without remembering, and that is deliberate. The model is what the source said, and stays that way: Self::type_ref’s index means every type the API mentions, so growing it with a spelling no source wrote would destroy the one thing it is good for. This is the grammar being consulted, not the model being extended.

It is therefore not the peer of Self::add_local_function, which does extend the model — a binding-local sig!(..) is an API item, a function the binding declares as if it had been marked. A composed type is not an API item; it is an intermediate in some binding’s crossing graph, and it belongs in the table that tracks crossings.

The scan’s entry point, and nowhere else’s. A caller holding an element already has the reading — Function::ret, Param::ty, Field::ty are TypeRefs computed at parse time — and re-deriving one from spell() is reasoning from the spelling, which is what origin is not for. This exists for the one case with no element behind it: a type a build script declared, or one expansion composed. ensure_entry is its only caller in the registry pipeline.

Whoever asks is expected to keep the answer. The registry does: a reading is taken once when a type-table cell is born, and lives in that cell — and Registry::reading (in the registry layer above) hands back only what is in one, so a second source of readings cannot reappear here (#266).

Err means the spelling is outside the accepted grammar — a real diagnosis about a type the binding built, not a cache miss.

pub, not pub(crate). The registry pipeline that is this method’s sole legitimate caller now lives in the separate prebindgen-registry crate, so a module-path seal can no longer express “the pipeline, and nothing else” — there is no path inside this crate for it to name. The seal is now a documented convention (this doc comment) rather than a compiler-enforced one; #280’s intent (an adapter must not mint a TypeRef from tokens of its own) is no longer structurally guaranteed and would need a real API (e.g. a sealed trait token minted only by prebindgen-registry) to restore.

pub fn unsupported(&self) -> impl Iterator<Item = &Unsupported>

Every item the language could not express, with its diagnosis.

Present in the model so a consumer can inspect what a source crate marked — building a Registry from a model holding any of these fails, and reports all of them. See the module docs on where acceptance is enforced.

pub fn lower_signature(&self, f: &ItemFn) -> Result<Function, ItemError>

Lower a function signature written outside the captured stream.

For the one input that does not come through this module: a binding’s local_functions, whose signatures are written by hand in a build script and inserted straight into the registry. Everything else was already lowered here, so this exists to keep the grammar decided in one place rather than re-checked at the far end.

Grammar only, and it validates by lowering: an Err is a shape the language cannot express, an Ok is the element to admit. Whether the types it names are declared is a whole-model question, settled when the model is built, and a binding-local fn may legitimately name types the source crate never did.

pub fn add_local_function(&mut self, f: Function, crate_name: String)

Admit a binding-local function: one a build script wrote via sig!(..) rather than one a source crate marked.

The model is the pipeline’s only index, so a function nothing captured still has to live here or nothing downstream can find it. crate_name is the module its generated call qualifies against, stamped onto the element’s location where Element::location already looks for it.

Deliberately does not extend Self::source_modules: see that field’s docs.

pub: its caller (RegistryBuilder::fun, on a binding-local fun! path) now lives in the separate prebindgen-registry crate.

pub fn resolve(&self, id: &TypeId) -> Option<&Type>

The declaration a reference denotes.

Infallible in practice for any reference reached from a surviving element: FlatBuilder::build made unresolvable references into ItemError::UnresolvedType, so what is left resolves.

Trait Implementations

impl Debug for Flat

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

Formats the value using the given formatter.

impl Default for Flat

fn default() -> Flat

Returns the “default value” for a type.