Crate citum_engine

Expand description

Citum Processor

This crate provides the core citation and bibliography processing functionality for the Citum project. It takes style definitions, bibliographic data, and citation information and produces formatted output.

The processor is designed to be pluggable with different renderers and supports advanced features like disambiguation, sorting, and localization.

For document-level integrations, use format_document with a FormatDocumentRequest. The request carries a StyleInput and RefsInput, so callers can pass local style paths, inline style YAML, local bibliography paths, inline bibliography YAML, or inline JSON references without constructing a Processor directly.

§Example

use citum_engine::{
    Bibliography, Citation, CitationItem, CitationSpec, Config, Contributor,
    ContributorForm, ContributorList, ContributorRole, DateForm, EdtfString,
    Monograph, MonographType, MultilingualString, Processing, Processor, Reference,
    Rendering, StructuredName, Style, StyleInfo, TemplateComponent, TemplateContributor,
    TemplateDate, TemplateDateVariable, Title, WrapPunctuation,
};

// Create a simple style using native Citum types
let style = Style {
    info: StyleInfo {
        title: Some("Simple".to_string()),
        id: Some("simple".into()),
        ..Default::default()
    },
    options: Some(Config {
        processing: Some(Processing::AuthorDate),
        ..Default::default()
    }),
    citation: Some(CitationSpec {
        template: Some(vec![
            TemplateComponent::Contributor(TemplateContributor {
                contributor: ContributorRole::Author,
                form: ContributorForm::Short,
                rendering: Rendering::default(),
                ..Default::default()
            }),
            TemplateComponent::Date(TemplateDate {
                date: TemplateDateVariable::Issued,
                form: DateForm::Year,
                rendering: Rendering::default(),
                ..Default::default()
            }),
        ]),
        wrap: Some(WrapPunctuation::Parentheses.into()),
        ..Default::default()
    }),
    ..Default::default()
};

// Create a bibliography using native Citum reference data
let mut bib = Bibliography::new();
let reference = Reference::Monograph(Box::new(Monograph {
    id: Some("kuhn1962".into()),
    r#type: MonographType::Book,
    title: Some(Title::Single("The Structure of Scientific Revolutions".to_string())),
    author: Some(Contributor::ContributorList(ContributorList(vec![
        Contributor::StructuredName(StructuredName {
            family: MultilingualString::Simple("Kuhn".to_string()),
            given: MultilingualString::Simple("Thomas".to_string()),
            suffix: None,
            dropping_particle: None,
            non_dropping_particle: None,
        }),
    ]))),
    issued: EdtfString("1962".to_string()),
    ..Default::default()
}));
bib.insert("kuhn1962".to_string(), reference);

// Create processor and render
let processor = Processor::new(style, bib);
let citation = Citation {
    id: Some("c1".into()),
    items: vec![CitationItem { id: "kuhn1962".to_string(), ..Default::default() }],
    ..Default::default()
};
let result = processor.process_citation(&citation).unwrap();
assert_eq!(result, "(Kuhn, 1962)");

Re-exports§

pub use api::BibliographyBlockRequest;
pub use api::BibliographyEntry;
pub use api::CitationInsertPosition;
pub use api::CitationOccurrence;
pub use api::CitationOccurrenceItem;
pub use api::DocumentOptions;
pub use api::DocumentSession;
pub use api::DocumentSessionError;
pub use api::EntryMetadata;
pub use api::FormatDocumentError;
pub use api::FormatDocumentRequest;
pub use api::FormatDocumentResult;
pub use api::FormattedBibliography;
pub use api::FormattedBibliographyBlock;
pub use api::FormattedCitation;
pub use api::OpenSessionResult;
pub use api::OutputFormatKind;
pub use api::PreviewCitationResult;
pub use api::RefsInput;
pub use api::SessionMutationResult;
pub use api::StyleInput;
pub use api::Warning;
pub use api::WarningLevel;
pub use api::apply_style_overrides;
pub use api::format_document;
pub use api::format_document_with_resolver;
pub use api::format_document_with_style;
pub use error::ProcessorError;
pub use processor::document::DocumentFormat;
pub use processor::ProcessedReferences;
pub use processor::Processor;
pub use reference::Bibliography;
pub use render::ProcTemplate;
pub use render::ProcTemplateComponent;
pub use render::citation_to_string;
pub use render::refs_to_string;
pub use values::ComponentValues;
pub use values::ProcHints;
pub use values::ProcValues;
pub use values::RenderContext;
pub use values::RenderOptions;

Modules§

api: Interactive document-level API for batch citation formatting. Interactive document-level API for batch citation formatting.
error: Error types returned by citation and bibliography processing.
grouping: Bibliography grouping support.
processor: Citation, bibliography, sorting, and document processing logic. The Citum processor for rendering citations and bibliographies.
reference: Reference types for the Citum processor.
render: Output-format renderers and string conversion helpers. Rendering utilities for Citum templates.
values: Template value resolution and formatting helpers. Value extraction for template components.

Structs§

Citation: A citation containing one or more references.
CitationItem: A single citation item referencing a bibliography entry.
CitationSpec: Citation specification.
Config: Top-level style configuration.
ContributorList: A list of contributors.
EdtfString: An EDTF string.
Locale: A locale definition containing language-specific terms and formatting rules.
Monograph: A monograph, such as a book or a report, is a monolithic work published or produced as a complete entity.
Reference: The Reference model: a class-specific overlay reachable through accessor methods.
Rendering: Rendering instructions applied to template components.
StructuredName: A structured name is a name broken down into its constituent parts.
Style: The new Citum Style model.
StyleInfo: Style metadata.
TemplateContributor: A contributor component for rendering names.
TemplateDate: A date component for rendering dates.

Enums§

Contributor: A contributor can be a single string, a structured name, or a list of contributors.
ContributorForm: How to render contributor names.
ContributorRole: Contributor roles.
DateForm: Date rendering forms.
MonographType: Discriminates monograph subtypes for style-directed formatting.
MultilingualString: A string that can be represented in multiple languages and scripts.
Processing: Processing mode for citation/bibliography generation.
TemplateComponent: A template component - the building blocks of citation/bibliography templates.
TemplateDateVariable: Date variables.
Title: A title can be a single string, a structured title, or a multilingual title.
WrapPunctuation: Punctuation to wrap a component in.