Source Inspection

lc_plugin::inspect lets a format plugin extract lightweight metadata from a source file before a full import. LinkCAD uses this metadata to populate dynamic options dialog lists such as available steps, layers, units, or variants.

Dynamic list widgets are declared in DialogSpec. Python plugins use the same dialog list concepts through linkcad.v1.plugin.DialogSpec.

Key Public Items

Item	Purpose
SourceInspector	Trait implemented by metadata inspectors.
SourceMeta	Container for named lists of metadata items.
MetaItem	One value/display/description item in a metadata list.

MetaItem

pub struct MetaItem {
    pub value: String,
    pub display: String,
    pub description: Option<String>,
}

Constructor	Description
MetaItem::simple(value: &str) -> MetaItem	Uses the same string for value and display.
MetaItem::with_display(value: &str, display: &str) -> MetaItem	Uses separate stored value and display text.
MetaItem::full(value: &str, display: &str, description: &str) -> MetaItem	Adds a tooltip/description.

SourceMeta

pub struct SourceMeta {
    pub lists: Vec<(String, Vec<MetaItem>)>,
}

Method	Description
SourceMeta::new() -> SourceMeta	Create empty metadata.
add_items(key: &str, items: &[&str])	Add a list of simple items.
add_meta_items(key: &str, items: Vec<MetaItem>)	Add a list of full metadata items.
get(key: &str) -> Option<&[MetaItem]>	Return items for a key.
to_json() -> String	Serialize metadata for the host dialog refresh API.

The JSON shape is a lists array. Each list has a key and an items array containing value, display, and optional description fields.

SourceInspector

pub trait SourceInspector: Send + Sync {
    fn inspect(&self, path: &Path) -> Result<SourceMeta, String>;
}

The inspector should read only enough of the source to populate option metadata. Return Err(String) for an inspection failure; the host receives no metadata for that refresh.

Example

use lc_plugin::inspect::{MetaItem, SourceInspector, SourceMeta};
use std::path::Path;

struct ExampleInspector;

impl SourceInspector for ExampleInspector {
    fn inspect(&self, _path: &Path) -> Result<SourceMeta, String> {
        let mut meta = SourceMeta::new();
        meta.add_items("steps", &["pcb", "panel"]);
        meta.add_meta_items(
            "layers",
            vec![
                MetaItem::with_display("top", "Top Copper"),
                MetaItem::with_display("bottom", "Bottom Copper"),
            ],
        );
        Ok(meta)
    }
}

Register the inspector with the register_format! macro:

lc_plugin::register_format! {
    name: "Example Format",
    extensions: "*.exa",
    license: 0,
    plugin_name: "Example Plugin",
    description: "Example native Rust plugin",
    reader: || Box::new(ExampleReader::default()),
    writer: || Box::new(ExampleWriter::default()),
    import_dialog: import_dialog_spec(),
    export_dialog: export_dialog_spec(),
    source_inspector: || Box::new(ExampleInspector),
}

Dialog Integration

The dialog inspection_key must match a SourceMeta list key:

DialogSpec::new("Import Options")
    .group("Source")
    .single_select_list("ExampleInStep", "Step", &[], Some("steps"))
    .multi_select_list("ExampleInLayers", "Layers", &[], Some("layers"), ',')

When the dialog refreshes, LinkCAD asks the inspector for metadata and fills the matching widgets from the named lists.