Struct Processor 

pub struct Processor {
    pub style: Style,
    pub bibliography: Bibliography,
    pub locale: Locale,
    pub default_config: Config,
    pub hints: HashMap<String, ProcHints>,
    pub compound_sets: IndexMap<String, Vec<String>>,
    pub compound_set_by_ref: HashMap<String, String>,
    pub compound_member_index: HashMap<String, usize>,
    pub show_semantics: bool,
    pub inject_ast_indices: bool,
    pub abbreviation_map: Option<AbbreviationMap>,
}

The Citum processor facade.

Takes a style, bibliography, and locale context, then delegates citation and bibliography work to the processor submodules.

Fields

style: Style

The style definition.

bibliography: Bibliography

The bibliography (references keyed by ID).

locale: Locale

The locale for terms and formatting.

default_config: Config

Default configuration.

hints: HashMap<String, ProcHints>

Pre-calculated processing hints.

compound_sets: IndexMap<String, Vec<String>>

Compound sets keyed by set ID.

compound_set_by_ref: HashMap<String, String>

Reverse lookup for set membership by reference ID.

compound_member_index: HashMap<String, usize>

Position within a set (0-based) for each reference ID.

show_semantics: bool

Whether to output semantic markup (HTML spans, Djot attributes). Defaults to true; set to false to suppress class attributes (e.g. --no-semantics).

inject_ast_indices: bool

Whether to annotate semantic HTML wrappers with source template indices.

abbreviation_map: Option<AbbreviationMap>

Document-level abbreviation map for post-render substitution.

Implementations

impl Processor

pub fn render_grouped_bibliography_with_format<F>( &self, run: &FinalizedRun, ) -> String

where F: OutputFormat<Output = String>,

Render all loaded references with the style’s effective grouping policy.

Enabled manual groups take precedence over automatic partition sections, which in turn take precedence over flat rendering. Group selectors apply to individual references before compound numeric rows are merged, so each rendered group only includes the members that matched its selector.

pub fn render_grouped_bibliography_with_format_and_annotations<F>( &self, annotations: Option<&HashMap<String, String>>, annotation_style: Option<&AnnotationStyle>, run: &FinalizedRun, ) -> String

where F: OutputFormat<Output = String>,

Render the bibliography with grouping and annotations.

pub fn render_grouped_bibliography_with_format_standalone<F>(&self) -> String

where F: OutputFormat<Output = String>,

One-shot convenience for Processor::render_grouped_bibliography_with_format: begins a throwaway run internally.

pub fn render_grouped_bibliography_with_format_and_annotations_standalone<F>( &self, annotations: Option<&HashMap<String, String>>, annotation_style: Option<&AnnotationStyle>, ) -> String

where F: OutputFormat<Output = String>,

One-shot convenience for Processor::render_grouped_bibliography_with_format_and_annotations: begins a throwaway run internally.

impl Processor

pub fn process_references(&self) -> ProcessedReferences

Process all bibliography references and render them.

This is a one-shot convenience wrapper: it begins a throwaway super::run_state::RunState internally, so it has no continuity with any citations processed elsewhere. Use Processor::process_references_with_format with an explicit, shared FinalizedRun to render a bibliography that reflects prior citation registration in the same document.

pub fn process_references_with_format<F>( &self, run: &FinalizedRun, ) -> ProcessedReferences

where F: OutputFormat<Output = String>,

Process all bibliography references using the requested output format.

This preserves format-specific inline markup in per-entry API output. run should reflect all citations already processed for this document (or be a fresh Processor::begin_run for a standalone bibliography with no citations); see Processor::process_references_with_format_standalone for a one-shot convenience.

pub fn process_bibliography_entry( &self, reference: &Reference, entry_number: usize, run: &FinalizedRun, ) -> Option<ProcTemplate>

Process and render a bibliography entry.

pub fn process_bibliography_entry_with_format<F>( &self, reference: &Reference, entry_number: usize, run: &FinalizedRun, ) -> Option<ProcTemplate>

where F: OutputFormat<Output = String>,

Process a bibliography entry with specific format.

pub fn contributors_match(&self, prev: &Reference, current: &Reference) -> bool

Check whether primary contributors match between two references.

Used for subsequent author substitution in bibliographies.

pub fn render_bibliography_with_format<F>(&self, run: &FinalizedRun) -> String

where F: OutputFormat<Output = String>,

Render the bibliography to a string using a specific format.

pub fn render_bibliography_with_format_and_annotations<F>( &self, annotations: Option<&HashMap<String, String>>, annotation_style: Option<&AnnotationStyle>, run: &FinalizedRun, ) -> String

where F: OutputFormat<Output = String>,

Render the bibliography to a string with annotations.

pub fn render_selected_bibliography_with_format<F, I>( &self, item_ids: I, run: &FinalizedRun, ) -> String

where F: OutputFormat<Output = String>, I: IntoIterator<Item = String>,

Render a selected bibliography subset to a string using a specific format.

pub fn render_selected_bibliography_with_format_and_annotations<F, I>( &self, item_ids: I, annotations: Option<&HashMap<String, String>>, annotation_style: Option<&AnnotationStyle>, run: &FinalizedRun, ) -> String

where F: OutputFormat<Output = String>, I: IntoIterator<Item = String>,

Render a selected bibliography subset to a string with annotations.

Orchestrates the choice between:

1. Custom bibliography groups (selectors and headings).
2. Automatic sort partitioning with sections (headings only).
3. Standard flat rendering.

pub fn render_bibliography(&self) -> String

Render the entire bibliography to a formatted string.

One-shot convenience wrapper: begins a throwaway run internally, so it has no continuity with any citations processed elsewhere. Use Processor::render_bibliography_with_format with an explicit, shared FinalizedRun for a bibliography that reflects prior citation registration.

pub fn process_references_with_format_standalone<F>( &self, ) -> ProcessedReferences

where F: OutputFormat<Output = String>,

One-shot convenience for Processor::process_references_with_format: begins a throwaway run internally.

pub fn process_bibliography_entry_standalone( &self, reference: &Reference, entry_number: usize, ) -> Option<ProcTemplate>

One-shot convenience for Processor::process_bibliography_entry: begins a throwaway run internally.

pub fn process_bibliography_entry_with_format_standalone<F>( &self, reference: &Reference, entry_number: usize, ) -> Option<ProcTemplate>

where F: OutputFormat<Output = String>,

One-shot convenience for Processor::process_bibliography_entry_with_format: begins a throwaway run internally.

pub fn render_bibliography_with_format_standalone<F>(&self) -> String

where F: OutputFormat<Output = String>,

One-shot convenience for Processor::render_bibliography_with_format: begins a throwaway run internally.

pub fn render_bibliography_with_format_and_annotations_standalone<F>( &self, annotations: Option<&HashMap<String, String>>, annotation_style: Option<&AnnotationStyle>, ) -> String

where F: OutputFormat<Output = String>,

One-shot convenience for Processor::render_bibliography_with_format_and_annotations: begins a throwaway run internally.

pub fn render_selected_bibliography_with_format_standalone<F, I>( &self, item_ids: I, ) -> String

where F: OutputFormat<Output = String>, I: IntoIterator<Item = String>,

One-shot convenience for Processor::render_selected_bibliography_with_format: begins a throwaway run internally.

pub fn render_selected_bibliography_with_format_and_annotations_standalone<F, I>( &self, item_ids: I, annotations: Option<&HashMap<String, String>>, annotation_style: Option<&AnnotationStyle>, ) -> String

where F: OutputFormat<Output = String>, I: IntoIterator<Item = String>,

One-shot convenience for Processor::render_selected_bibliography_with_format_and_annotations: begins a throwaway run internally.

impl Processor

pub fn register_nocite_ids( &self, ids: impl IntoIterator<Item = String>, run: &mut RunState, )

Register nocite reference IDs into the cited set.

Nocite IDs are treated as cited for bibliography-selection purposes (they appear in bibliography.entries alongside normally cited refs and are matched by CitedStatus::Visible selectors), but no formatted_citations entry is produced for them. This matches standard citeproc / Pandoc nocite semantics.

IDs that are absent from self.bibliography are silently ignored here; callers are responsible for emitting nocite_missing_ref warnings first.

pub fn process_citation( &self, citation: &Citation, ) -> Result<String, ProcessorError>

Render a single citation to plain text.

This is a one-shot convenience wrapper: it begins a throwaway RunState internally, so it has no continuity with any other call. Use Processor::process_citations (or the run-threaded _with_format variants with an explicit, shared RunState) to render multiple citations from one document with correct cumulative numbering, cite-order tracking, and dynamic compound grouping.

Errors

Returns an error when referenced items are missing or rendering fails.

pub fn process_citation_with_format<F>( &self, citation: &Citation, run: &mut RunState, ) -> Result<String, ProcessorError>

where F: OutputFormat<Output = String>,

Render a citation to a string using a specific output format.

This resolves the effective citation spec for the citation’s mode and position, renders the citation body, and applies input and style affixes. run accumulates cite-order state (citation numbers, cited IDs, dynamic compound groups) across calls; pass the same RunState for every citation in one document to get correct cumulative behavior, or a fresh one (via Processor::begin_run) for an isolated, one-off render.

Errors

Returns an error when referenced items are missing or rendering fails.

pub fn process_citations( &self, citations: &[Citation], ) -> Result<Vec<String>, ProcessorError>

Render multiple citations in document order.

For note-based styles, normalizes context and assigns citation positions. This is a one-shot convenience wrapper: it begins a throwaway RunState internally, shared across all citations in citations (so cumulative numbering/grouping within this call is correct) but not shared with any other call.

Errors

Returns an error when any citation in the sequence fails to render.

pub fn process_citations_with_format<F>( &self, citations: &[Citation], run: &mut RunState, ) -> Result<Vec<String>, ProcessorError>

where F: OutputFormat<Output = String>,

Render multiple citations with a custom output format.

run is threaded through every citation in citations, in order, so numbering/cite-order/dynamic-grouping state accumulates correctly across the whole batch. Pass the same run on to bibliography rendering (after RunState::finalize) to render a consistent document.

Errors

Returns an error when any citation in the sequence fails to render.

impl Processor

pub fn normalize_note_context( &self, citations: &[Citation], run: &mut RunState, ) -> Vec<Citation>

Normalize citation note context for note styles.

Document/plugin layers should provide explicit note_number values. When missing, this method assigns sequential note numbers in citation order and records each reference’s first-occurrence note number into run.

impl Processor

pub fn begin_run(&self) -> RunState

Begin a new render run.

Allocates fresh per-run state (citation numbers, cite-order tracking, dynamic compound groups, first-note tracking) and performs numeric citation-number pre-initialization from the processor’s immutable bibliography/style data. Registration methods (&self, &mut RunState) populate the returned RunState in citation-processing order; call RunState::finalize before rendering. See docs/specs/EXPLICIT_RENDER_RUN_STATE.md.

pub fn new(style: Style, bibliography: Bibliography) -> Self

Create a new processor with default English locale (en-US).

pub fn try_with_compound_sets( style: Style, bibliography: Bibliography, compound_sets: IndexMap<String, Vec<String>>, ) -> Result<Self, ProcessorError>

Create a new processor with explicit compound sets, returning an error for invalid sets.

Errors

Returns an error when any compound set references unknown bibliography entries or reuses the same member more than once.

pub fn with_compound_sets( style: Style, bibliography: Bibliography, compound_sets: IndexMap<String, Vec<String>>, ) -> Self

Create a new processor with explicit compound sets.

If compound_sets is invalid, this constructor ignores the supplied sets and falls back to a processor without compound sets.

pub fn with_locale( style: Style, bibliography: Bibliography, locale: Locale, ) -> Self

Create a new processor with a specified locale.

The locale determines term translations and locale-specific formatting behavior.

pub fn try_with_locale_and_compound_sets( style: Style, bibliography: Bibliography, locale: Locale, compound_sets: IndexMap<String, Vec<String>>, ) -> Result<Self, ProcessorError>

Create a new processor with explicit locale and compound sets, returning an error for invalid sets.

Errors

Returns an error when any compound set references unknown bibliography entries or reuses the same member more than once.

pub fn with_locale_and_compound_sets( style: Style, bibliography: Bibliography, locale: Locale, compound_sets: IndexMap<String, Vec<String>>, ) -> Self

Create a new processor with a specified locale and explicit compound sets.

The locale determines term translations and locale-specific formatting behavior.

If compound_sets is invalid, this constructor ignores the supplied sets and falls back to a processor without compound sets.

pub fn with_style_locale( style: Style, bibliography: Bibliography, locales_dir: &Path, ) -> Self

Create a new processor, loading the locale from disk.

Loads the locale specified in the style’s default_locale field from the given directory, falling back to en-US if not found or not specified.

pub fn with_inject_ast_indices(self, inject_ast_indices: bool) -> Self

Return a copy of the processor that injects source template indices into semantic HTML.

pub fn set_inject_ast_indices(&mut self, inject_ast_indices: bool)

Enable or disable source template index injection for semantic HTML output.

pub fn get_config(&self) -> &Config

Return the global style configuration.

pub fn get_citation_config(&self) -> Cow<'_, Config>

Return merged config for citation rendering.

Combines global style options with citation-specific overrides, borrowing the global configuration when no merge or locale resolution is required.

pub fn get_bibliography_config(&self) -> Cow<'_, Config>

Return merged shared config for bibliography rendering.

Combines global shared style options with bibliography-local shared overrides, borrowing the global configuration when no merge or locale resolution is required.

pub fn get_bibliography_options(&self) -> Cow<'_, BibliographyConfig>

Return effective bibliography-only configuration.

pub fn sort_references<'a>( &self, references: Vec<&'a Reference>, ) -> Vec<&'a Reference>

Sort references according to the style’s bibliography sort specification.

Uses style-specified sort keys (author, title, issued, etc.) and sort order.

pub fn sort_citation_items( &self, items: Vec<CitationItem>, spec: &CitationSpec, ) -> Vec<CitationItem>

Sort citation items according to the style’s citation sort specification.

pub fn calculate_hints(&self) -> HashMap<String, ProcHints>

Calculate disambiguation hints needed for the style.

Analyzes the bibliography to determine which items need disambiguation (year suffixes, etc.) and calculates hints for efficient rendering.

impl Processor

pub fn process_document<P, F>( &self, content: &str, parser: &P, format: DocumentFormat, ) -> Result<String, ProcessorError>

where P: CitationParser, F: OutputFormat<Output = String>,

Process citations in a document and append a bibliography.

This is the primary document-level entry point. It:

1. Parses the source document using the provided adapter.
2. Resolves frontmatter overrides (integral-name policy, bibliography options).
3. Chooses a bibliography orchestration path based on frontmatter and document blocks.

Errors

Returns ProcessorError::FrontmatterParse when the document’s frontmatter fails to parse.

pub fn process_document_with_caller_blocks<P, F>( &self, content: &str, blocks: &[BibliographyGroup], parser: &P, format: DocumentFormat, ) -> String

where P: CitationParser, F: OutputFormat<Output = String>,

Process a document with bibliography groups supplied by the caller.

Unlike the fenced-div path, the caller provides an ordered slice of citum_schema::grouping::BibliographyGroups (e.g. from --bibliography-blocks on the CLI or a session-level block list) rather than :::bibliography{...} markers embedded in the document. Citations are processed exactly as in process_document; the trailing bibliography is replaced by one rendered section per supplied group using the shared render_document_bibliography_blocks primitive.

Trait Implementations

impl Debug for Processor

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

Formats the value using the given formatter.

impl Default for Processor

fn default() -> Self

Returns the “default value” for a type.