Struct FlatBuilder 

pub struct FlatBuilder { /* private fields */ }

Collects what to parse, then hands over the model.

Carries no configuration about what the language accepts — that is a property of the language, not of the call site. What it carries is what to parse: feed the inputs, then build once.

Reading a source directory

A build script’s whole job, in one expression — the Source step included. Pass <source_crate>::PREBINDGEN_OUT_DIR:

use prebindgen_flat::Flat;

let flat = Flat::builder().source("source_ffi").build()?;
assert!(flat.function("test_function").is_some());
assert!(flat.declared_type("TestStruct").is_some());

Reading a stream

Self::items takes any (syn::Item, SourceLocation) iterator, so everything a Source can express still composes — a group selection, a renamed dependency, several sources at once. The feeders accumulate, so mix them freely:

use prebindgen::Source;
use prebindgen_flat::Flat;

// A dependency renamed in Cargo.toml needs the name THIS crate uses, so it
// is configured rather than named by directory.
let helpers = Source::builder("source_ffi").crate_name("helpers").build();
let flat = Flat::builder()
    .items(helpers.items_in_groups(&["functions"]))
    .build()?;
assert_eq!(flat.functions().count(), 1);

Why accumulate, rather than parse each input

The rules that make a parse fail are whole-stream rules: one flat namespace across every ingested crate, one const index an array length may reach into, one set of source modules to normalize paths against, and every type reference resolving against every declaration. None can be decided per input, so every input is in hand before any of it is classified.

Implementations

impl FlatBuilder

pub fn source<P: AsRef<Path>>(self, dir: P) -> Self

Every #[prebindgen] item captured in dir.

Sugar for Self::items over Source::items_all, which is the whole of what a build script normally needs — pass <source_crate>::PREBINDGEN_OUT_DIR. Reach for a Source directly, and feed it through Self::items, only when it needs configuring.

Panics the way Source::new does if dir is not readable prebindgen output: a build script has nothing to recover with.

use prebindgen_flat::Flat;

let flat = Flat::builder().source("source_ffi").build()?;
assert!(flat.function("test_function").is_some());
assert!(flat.declared_type("TestStruct").is_some());

pub fn source_named<P: AsRef<Path>>( self, dir: P, crate_name: impl Into<String>, ) -> Self

The same, for a dependency this crate renames in Cargo.toml.

The origin recorded at capture time is the dependency’s real package name, which will not resolve from a crate that refers to it by another name. crate_name is the name this crate uses.

Per directory, deliberately: an override on the whole parse could only fix one module, and a flat API may layer several sources.

pub fn items<I>(self, items: I) -> Self

where I: IntoIterator<Item = (Item, SourceLocation)>,

Add a captured item stream.

The general feeder: any (syn::Item, SourceLocation) iterator, so item-level selection and multi-source composition stay upstream where they already are. Call it as often as needed; the streams accumulate.

use prebindgen::Source;
use prebindgen_flat::Flat;

let source = Source::new("source_ffi");
let flat = Flat::builder()
    .items(source.items_in_groups(&["structs"]))
    .build()?;
assert_eq!(flat.types().count(), 1);

pub fn build(self) -> Result<Flat, ParseError>

Parse everything collected so far into the model.

Transactional: an Err yields no model at all, so a refused stream cannot leave a half-built one behind.

Order-independent: source modules are gathered, consts indexed, and every item lowered before any reference is resolved — so a type reference, an array length and a cross-source mention may each name something declared later, in this input or another.

Trait Implementations

impl Clone for FlatBuilder

fn clone(&self) -> FlatBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FlatBuilder

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

Formats the value using the given formatter.

impl Default for FlatBuilder

fn default() -> FlatBuilder

Returns the “default value” for a type.