citum-engine 0.57.0

Citum citation and bibliography processor
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

/*
SPDX-License-Identifier: MIT OR Apache-2.0
SPDX-FileCopyrightText: © 2023-2026 Bruce D'Arcus and Citum contributors
*/

//! 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
//!
//! ```rust
//! 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)");
//! ```

/// Interactive document-level API for batch citation formatting.
pub mod api;
/// Error types returned by citation and bibliography processing.
pub mod error;
#[cfg(feature = "ffi")]
pub mod ffi;
pub mod grouping;
/// Citation, bibliography, sorting, and document processing logic.
pub mod processor;
pub mod reference;
/// Output-format renderers and string conversion helpers.
pub mod render;
mod sort_partitioning;
mod sort_support;
/// Template value resolution and formatting helpers.
pub mod values;

pub use api::{
    BibliographyEntry, CitationOccurrence, CitationOccurrenceItem, DocumentOptions, EntryMetadata,
    FormatDocumentError, FormatDocumentRequest, FormatDocumentResult, FormattedBibliography,
    FormattedCitation, OutputFormatKind, RefsInput, StyleInput, Warning, WarningLevel,
    format_document, format_document_with_style,
};
pub use citum_schema::options::{Config, Processing};
pub use citum_schema::reference::{
    Contributor, ContributorList, EdtfString, Monograph, MonographType, MultilingualString,
    StructuredName, Title,
};
pub use citum_schema::template::{
    ContributorForm, ContributorRole, DateForm, DateVariable as TemplateDateVariable, Rendering,
    TemplateComponent, TemplateContributor, TemplateDate, WrapPunctuation,
};
pub use citum_schema::{CitationSpec, Style, StyleInfo};
pub use error::ProcessorError;
pub use processor::document::DocumentFormat;
pub use processor::{ProcessedReferences, Processor};
pub use reference::{Bibliography, Citation, CitationItem, Reference};
pub use render::{ProcTemplate, ProcTemplateComponent, citation_to_string, refs_to_string};
pub use values::{ComponentValues, ProcHints, ProcValues, RenderContext, RenderOptions};

// Re-export Locale from citum_schema for convenience
pub use citum_schema::locale::Locale;