citum_engine/
lib.rs

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

citum_engine/
lib.rs
