Struct Processor 

pub struct Processor {

    pub style: Style,
    pub bibliography: Bibliography,
    pub locale: Locale,
    pub default_config: Config,
    pub hints: HashMap<String, ProcHints>,
    pub citation_numbers: RefCell<HashMap<String, usize>>,
    pub cited_ids: RefCell<HashSet<String>>,
    pub compound_sets: IndexMap<String, Vec<String>>,
    pub compound_set_by_ref: HashMap<String, String>,
    pub compound_member_index: HashMap<String, usize>,
    pub compound_groups: RefCell<IndexMap<usize, Vec<String>>>,
    pub dynamic_compound_set_by_ref: RefCell<HashMap<String, String>>,
    pub dynamic_compound_member_index: RefCell<HashMap<String, usize>>,
    pub dynamic_compound_sets: RefCell<IndexMap<String, Vec<String>>>,
    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.

citation_numbers: RefCell<HashMap<String, usize>>

Citation numbers assigned to references (for numeric styles).

cited_ids: RefCell<HashSet<String>>

IDs of items that were cited in a visible way.

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.

compound_groups: RefCell<IndexMap<usize, Vec<String>>>

Compound numeric groups: citation number → ordered ref IDs in the group.

dynamic_compound_set_by_ref: RefCell<HashMap<String, String>>

Dynamic equivalent of compound_set_by_ref for cite-time groups.

Maps each dynamic group member (head and tails) to the head’s ref ID, which acts as the set identifier. Merged with static data at render time.

dynamic_compound_member_index: RefCell<HashMap<String, usize>>

Dynamic equivalent of compound_member_index for cite-time groups.

Maps each dynamic group member to its 0-based position within the group. Merged with static data at render time.

dynamic_compound_sets: RefCell<IndexMap<String, Vec<String>>>

Dynamic equivalent of compound_sets for cite-time groups.

Maps each dynamic group’s head ref ID to the ordered list of all members. Merged with static compound_sets at render time so sub-label lookup works.

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) -> String

where F: OutputFormat<Output = String>,

Render the bibliography with grouping for uncited (nocite) items.

If style.bibliography.groups is defined, uses configurable grouping with per-group sorting. Group selectors apply to individual references before compound numeric rows are merged, so each rendered group only includes the members that matched its selector. Otherwise, falls back to hardcoded cited/uncited grouping for backward compatibility.

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

where F: OutputFormat<Output = String>,

Render the bibliography with grouping and annotations.

impl Processor

pub fn process_references(&self) -> ProcessedReferences

Process all bibliography references and render them.

Returns sorted and formatted bibliography entries. For numeric styles, citations must have been processed first to assign citation numbers.

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

Process and render a bibliography entry.

pub fn process_bibliography_entry_with_format<F>( &self, reference: &Reference, entry_number: usize, ) -> 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 apply_author_substitution( &self, proc: &mut ProcTemplate, substitute: &str, )

Replace the primary contributor with a substitution string.

Used for subsequent author substitution (e.g., “———”).

pub fn render_bibliography_with_format<F>(&self) -> 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>, ) -> 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, ) -> 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>, ) -> 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.

impl Processor

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

Render a single citation to plain text.

This is the primary entry point for citation processing. It handles:

1. Looking up references in the bibliography.
2. Annotating positions (ibid, subsequent, etc.).
3. Resolving disambiguation (name expansion, year suffixes).
4. Applying the style’s citation template.

Returns the formatted citation string or an error if processing fails.

Errors

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

pub fn process_citation_with_format<F>( &self, citation: &Citation, ) -> 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.

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.

Errors

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

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

where F: OutputFormat<Output = String>,

Render multiple citations with a custom output format.

Errors

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

impl Processor

pub fn normalize_note_context(&self, citations: &[Citation]) -> 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.

impl Processor

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.

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.

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, ) -> String

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.

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.