Struct RawCandidate 

pub struct RawCandidate {
    pub text: String,
    pub insert_text: Option<String>,
    pub display: String,
    pub kind: CandidateKind,
    pub data: CandidateData,
    pub source: Option<SourceId>,
    pub accept_action: Option<Box<AcceptAction>>,
    pub annotations: Vec<Annotation>,
    pub display_spans: Vec<DisplaySpan>,
}

Output of a generator. The pipeline passes these through the matcher next.

Fields

text: String

Text the matcher scores the query against, and — unless insert_text overrides it — the text inserted when the user accepts.

insert_text: Option<String>

OR.7: what to insert on accept, when that differs from what the user matched against. None ⇒ insert text.

Two sources already needed this and each grew its own escape hatch: LSP carries insert_text inside its extension payload and do_completion_accept special-cases it, snippets do the same with a body. A third case — org-roam completing a node title but inserting an [[id:…][…]] link — made the pattern worth having generically, because a plugin source cannot reach either existing hatch: both are keyed to a host-owned kind_id.

Folding text and insertion together is what forced those hatches in the first place. A candidate matched on text and inserted verbatim is the common case, not the only one.

display: String

What appears in the popup before annotators run. May be text verbatim or a richer form (e.g. "~/Documents" for a File whose text is the absolute path).

kind: CandidateKind

data: CandidateData

source: Option<SourceId>

Source that produced this candidate. None for legacy / non-insert callers (cmdline pickers, plain test fixtures); insert-mode generators tag themselves so the per-source-priority ranker (Phase 4.2.g.5) can resolve the right priority bucket. The string is the same id surfaced in :set completion.source.<id>.priority=… and in :help completion-sources.

accept_action: Option<Box<AcceptAction>>

What the host should do if the user accepts this candidate. Slice 3c.unify.picker-generator-trait-unify (7b.0): adds a typed accept payload to the candidate so AcceptHandler impls can be stateless — the default handler (source_registration::DefaultAcceptHandler) just clones this field. None ⇒ default behaviour: cmdline replaces cmdline[replace_start..] with text; picker echoes “no accept_action set” via the default handler. Surfaces that need typed dispatch set this at candidate-build time.

Boxed (slice 8): AcceptAction is a tagged enum carrying PathBuf / String / Args among its variants — its inline size dominates RawCandidate. Boxing keeps Option<Box<AcceptAction>> at 8 bytes (None = null pointer) so cmdline-completion + insert-completion candidates (which leave it unset) don’t pay the cost. Picker candidates pay one heap alloc per row at construction, recovered ~10× over by smaller per- candidate memcpy during pipeline matcher/ranker passes (picker::refilter/n=5000 measured 2× faster than the inline shape — see benchmarks.md).

#[serde(skip)] because the Custom variant carries Arc<dyn Any> which isn’t serializable; the rest of the candidate (text + display + data) round-trips through the cache, but the accept action is recomputed at the callsite when needed.

annotations: Vec<Annotation>

MARG §8: source-supplied marginalia. A picker source that knows its rows’ metadata (the file/dir picker’s perms / size / mtime) attaches typed Annotations here at build time; the pipeline copies them onto the RenderedCandidate so the renderer color-codes them. Empty for sources that contribute no marginalia (the common case). #[serde(skip)]: annotations are render-time data resolved against the live theme, never cached.

display_spans: Vec<DisplaySpan>

PH.1: optional syntax-highlight overlay for the display run (the matchable text itself, NOT a trailing column — that’s annotations). Each span carries a semantic Style, resolved to a theme color only at the render seam (resolve_syntax_style), so :colorscheme recolors picker previews live. Byte offsets into display. Empty ⇒ today’s plain single-color preview. Producer contract (PH.2): spans are sorted by range.start, non-overlapping, and aligned to char boundaries; the renderer composes them under match_ranges (fuzzy-match highlight wins on overlap). #[serde(skip)] to match annotations — render-time overlay, not cached. See docs/dev/architecture/picker-preview-highlight.md.

Implementations

impl RawCandidate

pub fn plain(text: impl Into<String>, kind: CandidateKind) -> Self

Convenience for plain text candidates with no metadata. Leaves source + accept_action unset; insert-mode producers chain Self::with_source to tag themselves; picker generators set accept_action per row.

pub fn with_source(self, source: SourceId) -> Self

Tag the candidate with its producing source. Used by insert-mode generators so the ranker can apply per-source priority (Phase 4.2.g.5 (2/3)). Picker generators leave the field unset – their pipeline doesn’t apply per-source priority.

Trait Implementations

impl Clone for RawCandidate

fn clone(&self) -> RawCandidate

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RawCandidate

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RawCandidate

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for RawCandidate

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for RawCandidate

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for RawCandidate