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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
//! Generate PDFs with [Typst](https://typst.app) straight from your Rust types.
//!
//! Derive [`ToDict`](macro@ToDict) on a struct and it becomes a Typst input
//! dictionary — feed it to a `.typ` template as `sys.inputs` and render to PDF,
//! with no hand-written dict building. The [`ToValue`] / [`ToDict`] traits do
//! the Rust-to-Typst value conversion, with optional `chrono`, `time`,
//! `rust_decimal`, `serde_json`, and `uuid` support.
//!
//! Rendering uses two parts:
//!
//! - [`WorldBase`] — built once; loads fonts and roots file access at a directory.
//! - [`ConcreteWorld`] — one per document; attaches this generation's `sys.inputs` and any virtual
//! in-memory files (images, generated assets, …).
//!
//! # Example
//!
//! ```
//! use typst_template::{ToDict, WorldBaseConfig};
//!
//! #[derive(ToDict)]
//! struct Invoice {
//! client: String,
//! total: i64,
//! }
//!
//! // A base that only uses the embedded fonts (no system font lookup).
//! let base = WorldBaseConfig::new(".").system_fonts(false).build();
//!
//! let world = base
//! .concrete("main.typ")
//! .file("main.typ", "Invoice for #sys.inputs.client: #sys.inputs.total EUR")
//! .inputs(Invoice { client: "ACME".into(), total: 42 })
//! .build();
//!
//! let pdf = world.render_pdf_default().output.expect("render succeeds");
//! assert_eq!(&pdf[..4], b"%PDF");
//! ```
//!
//! # Reusing a base
//!
//! Build the [`WorldBase`] once, then derive a [`ConcreteWorld`] per document:
//!
//! ```
//! use typst_template::WorldBaseConfig;
//!
//! let base = WorldBaseConfig::new(".").system_fonts(false).build();
//!
//! for name in ["Alice", "Bob"] {
//! let pdf = base
//! .concrete("main.typ")
//! .file("main.typ", "Hello, #sys.inputs.name!")
//! .input("name", name)
//! .build()
//! .render_pdf_default()
//! .output
//! .expect("render succeeds");
//! assert_eq!(&pdf[..4], b"%PDF");
//! }
//! ```
//!
//! # `datetime.today()`
//!
//! With no `chrono`/`time` feature, `datetime.today()` is disabled by default
//! and returns nothing; set a value with
//! [`today`](ConcreteWorldBuilder::today). With `chrono` or `time` enabled it
//! defaults to the system clock ([`today_system`](ConcreteWorldBuilder::today_system)),
//! and [`today_system_in`](ConcreteWorldBuilder::today_system_in) (with
//! `chrono-tz` or `time-tz`) pins "local" to a DST-aware named zone.
//!
//! Note: with the `time` backend, `today_system` falls back to UTC when the
//! OS-local offset is unavailable (e.g. in a multithreaded process); use a named
//! zone (or `chrono`) for a specific local zone.
//!
//! # Features
//!
//! - `derive` *(default)* — the [`ToDict`](macro@ToDict) derive macro.
//! - `chrono` — [`ToValue`] for `chrono` date/time types, plus a system-clock `datetime.today()`.
//! - `time` — [`ToValue`] for `time` date/time types, plus a system-clock `datetime.today()`.
//! `chrono` takes precedence if both are enabled.
//! - `chrono-tz` / `time-tz` — named-time-zone support for
//! [`today_system_in`](ConcreteWorldBuilder::today_system).
//! - `rust_decimal` — [`ToValue`] for `rust_decimal::Decimal`.
//! - `serde_json` — [`ToValue`]/[`ToDict`] for `serde_json` values.
//! - `uuid` — [`ToValue`] for `uuid::Uuid`.
//!
//! # Typst compatibility
//!
//! This release targets **Typst 0.15**. The re-exported [`typst`] crate is part
//! of the public API, so moving to a new Typst version is a breaking change; see
//! the README for the version compatibility table.
// Let the `ToDict` derive refer to this crate as `::typst_template` even from
// within the crate's own tests and examples.
extern crate self as typst_template;
/// Implementation details used by the [`ToDict`](macro@ToDict) derive. Not part
/// of the public API.
// Re-export the time-zone crates so callers can name the zone passed to
// `today_system_in` without depending on them directly.
pub use chrono_tz;
pub use time_tz;
pub use ;
pub use ;
pub use PdfOptions;
/// Derives [`ToDict`](trait@ToDict) (and, through it, [`ToValue`]) for a named
/// struct. See the [derive crate](typst_template_derive::ToDict) for the full list
/// of `#[typst(...)]` attributes.
///
/// ```
/// use typst_template::{ToDict, ToValue, Value};
///
/// fn cents(amount: i64) -> Value {
/// Value::Str(format!("{}.{:02}", amount / 100, amount % 100).into())
/// }
///
/// #[derive(ToDict)]
/// struct Meta {
/// locale: String,
/// }
///
/// #[derive(ToDict)]
/// #[typst(rename_all = "camelCase")]
/// struct Invoice {
/// client_name: String,
/// #[typst(rename = "amount", with = "cents")]
/// amount_cents: i64,
/// #[typst(skip)]
/// internal_id: u64,
/// #[typst(flatten)]
/// meta: Meta,
/// }
///
/// let dict = Invoice {
/// client_name: "ACME".into(),
/// amount_cents: 1050,
/// internal_id: 7,
/// meta: Meta { locale: "hr".into() },
/// }
/// .into_dict();
///
/// assert_eq!(dict.get("clientName").unwrap(), &Value::Str("ACME".into()));
/// assert_eq!(dict.get("amount").unwrap(), &Value::Str("10.50".into()));
/// assert_eq!(dict.get("locale").unwrap(), &Value::Str("hr".into())); // flattened
/// assert!(dict.get("internalId").is_err()); // skipped
/// ```
pub use ToDict;
pub use ;
pub use Zone;
pub use ;
// Re-export the Typst crates and the handful of types that appear in this
// crate's public API, so downstream users don't need to depend on them
// directly or match versions by hand.
pub use ;