citum_engine/
lib.rs

1/*
2SPDX-License-Identifier: MIT OR Apache-2.0
3SPDX-FileCopyrightText: © 2023-2026 Bruce D'Arcus and Citum contributors
4*/
5
6//! Citum Processor
7//!
8//! This crate provides the core citation and bibliography processing functionality
9//! for the Citum project. It takes style definitions, bibliographic data, and
10//! citation information and produces formatted output.
11//!
12//! The processor is designed to be pluggable with different renderers and supports
13//! advanced features like disambiguation, sorting, and localization.
14//!
15//! For document-level integrations, use [`format_document`] with a
16//! [`FormatDocumentRequest`]. The request carries a [`StyleInput`] and
17//! [`RefsInput`], so callers can pass local style paths, inline style YAML, local
18//! bibliography paths, inline bibliography YAML, or inline JSON references
19//! without constructing a [`Processor`] directly.
20
21//! # Example
22//!
23//! ```rust
24//! use citum_engine::{
25//!     Bibliography, Citation, CitationItem, CitationSpec, Config, Contributor,
26//!     ContributorForm, ContributorList, ContributorRole, DateForm, EdtfString,
27//!     Monograph, MonographType, MultilingualString, Processing, Processor, Reference,
28//!     Rendering, StructuredName, Style, StyleInfo, TemplateComponent, TemplateContributor,
29//!     TemplateDate, TemplateDateVariable, Title, WrapPunctuation,
30//! };
31//!
32//! // Create a simple style using native Citum types
33//! let style = Style {
34//!     info: StyleInfo {
35//!         title: Some("Simple".to_string()),
36//!         id: Some("simple".into()),
37//!         ..Default::default()
38//!     },
39//!     options: Some(Config {
40//!         processing: Some(Processing::AuthorDate),
41//!         ..Default::default()
42//!     }),
43//!     citation: Some(CitationSpec {
44//!         template: Some(vec![
45//!             TemplateComponent::Contributor(TemplateContributor {
46//!                 contributor: ContributorRole::Author,
47//!                 form: ContributorForm::Short,
48//!                 rendering: Rendering::default(),
49//!                 ..Default::default()
50//!             }),
51//!             TemplateComponent::Date(TemplateDate {
52//!                 date: TemplateDateVariable::Issued,
53//!                 form: DateForm::Year,
54//!                 rendering: Rendering::default(),
55//!                 ..Default::default()
56//!             }),
57//!         ]),
58//!         wrap: Some(WrapPunctuation::Parentheses.into()),
59//!         ..Default::default()
60//!     }),
61//!     ..Default::default()
62//! };
63//!
64//! // Create a bibliography using native Citum reference data
65//! let mut bib = Bibliography::new();
66//! let reference = Reference::Monograph(Box::new(Monograph {
67//!     id: Some("kuhn1962".into()),
68//!     r#type: MonographType::Book,
69//!     title: Some(Title::Single("The Structure of Scientific Revolutions".to_string())),
70//!     author: Some(Contributor::ContributorList(ContributorList(vec![
71//!         Contributor::StructuredName(StructuredName {
72//!             family: MultilingualString::Simple("Kuhn".to_string()),
73//!             given: MultilingualString::Simple("Thomas".to_string()),
74//!             suffix: None,
75//!             dropping_particle: None,
76//!             non_dropping_particle: None,
77//!         }),
78//!     ]))),
79//!     issued: EdtfString("1962".to_string()),
80//!     ..Default::default()
81//! }));
82//! bib.insert("kuhn1962".to_string(), reference);
83//!
84//! // Create processor and render
85//! let processor = Processor::new(style, bib);
86//! let citation = Citation {
87//!     id: Some("c1".into()),
88//!     items: vec![CitationItem { id: "kuhn1962".to_string(), ..Default::default() }],
89//!     ..Default::default()
90//! };
91//! let result = processor.process_citation(&citation).unwrap();
92//! assert_eq!(result, "(Kuhn, 1962)");
93//! ```
94
95/// Interactive document-level API for batch citation formatting.
96pub mod api;
97/// Error types returned by citation and bibliography processing.
98pub mod error;
99#[cfg(feature = "ffi")]
100pub mod ffi;
101pub mod grouping;
102/// Citation, bibliography, sorting, and document processing logic.
103pub mod processor;
104pub mod reference;
105/// Output-format renderers and string conversion helpers.
106pub mod render;
107mod sort_partitioning;
108mod sort_support;
109/// Template value resolution and formatting helpers.
110pub mod values;
111
112pub use api::{
113    BibliographyEntry, CitationInsertPosition, CitationOccurrence, CitationOccurrenceItem,
114    DocumentOptions, DocumentSession, DocumentSessionError, EntryMetadata, FormatDocumentError,
115    FormatDocumentRequest, FormatDocumentResult, FormattedBibliography, FormattedCitation,
116    OpenSessionResult, OutputFormatKind, PreviewCitationResult, RefsInput, SessionMutationResult,
117    StyleInput, Warning, WarningLevel, format_document, format_document_with_resolver,
118    format_document_with_style,
119};
120pub use citum_schema::options::{Config, Processing};
121pub use citum_schema::reference::{
122    Contributor, ContributorList, EdtfString, Monograph, MonographType, MultilingualString,
123    StructuredName, Title,
124};
125pub use citum_schema::template::{
126    ContributorForm, ContributorRole, DateForm, DateVariable as TemplateDateVariable, Rendering,
127    TemplateComponent, TemplateContributor, TemplateDate, WrapPunctuation,
128};
129pub use citum_schema::{CitationSpec, Style, StyleInfo};
130pub use error::ProcessorError;
131pub use processor::document::DocumentFormat;
132pub use processor::{ProcessedReferences, Processor};
133pub use reference::{Bibliography, Citation, CitationItem, Reference};
134pub use render::{ProcTemplate, ProcTemplateComponent, citation_to_string, refs_to_string};
135pub use values::{ComponentValues, ProcHints, ProcValues, RenderContext, RenderOptions};
136
137// Re-export Locale from citum_schema for convenience
138pub use citum_schema::locale::Locale;
citum_engine/lib.rs

citum_engine/
lib.rs
