common/parser_tools/djot_options.rs
1//! Per-feature selection for djot import/export.
2//!
3//! The djot importer and exporter round-trip a set of *optional* block-level
4//! attributes — paragraph alignment, line height, text direction, non-breakable
5//! lines and background color — through djot's native `{key=value}` block
6//! attribute syntax (e.g. `{alignment=center}` on the line before a paragraph).
7//! These two option structs let a caller choose which of those attributes are
8//! carried. Everything else (headings, lists, tables, blockquotes, code blocks
9//! and all inline formatting) is always imported/exported and is not gated.
10//!
11//! Both structs default to **all enabled** — the fully lossless round-trip. Use
12//! [`DjotImportOptions::none`] / [`DjotExportOptions::none`] to restrict the
13//! round-trip to the core structural and inline feature set only.
14//!
15//! The attribute keys used on the wire are the model field names:
16//! `alignment`, `line_height`, `direction`, `non_breakable_lines`,
17//! `page_break_before`, `front_matter`, `background_color`, `top_margin`,
18//! `text_indent` and `semantic_role`. Block attributes are only emitted/read for standalone
19//! paragraphs and headings; list items, code blocks and table cells normalise
20//! their block styling away (the same boundary the other targets observe).
21
22use serde::{Deserialize, Serialize};
23
24/// The serde default of an attribute added after the options were first serialized: on,
25/// as [`DjotImportOptions::all`] and [`DjotExportOptions::all`], the two `Default`s, have it.
26const fn enabled() -> bool {
27 true
28}
29
30/// Selects which optional block attributes the djot **importer** applies to the
31/// document model. An attribute present in the source but disabled here is
32/// parsed and discarded, exactly like an unrepresentable construct.
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
34pub struct DjotImportOptions {
35 /// Apply paragraph alignment from `{alignment=left|right|center|justify}`.
36 pub alignment: bool,
37 /// Apply line height from `{line_height=<int>}`.
38 pub line_height: bool,
39 /// Apply text direction from `{direction=ltr|rtl}`.
40 pub direction: bool,
41 /// Apply non-breakable lines from `{non_breakable_lines=true|false}`.
42 pub non_breakable_lines: bool,
43 /// Apply "start on a new page" from `{page_break_before=true|false}`.
44 pub page_break_before: bool,
45 /// Mark the block as front matter from `{front_matter=true|false}` (see
46 /// `Block::fmt_front_matter`).
47 ///
48 /// Unlike its older neighbours, which a serialized value must state, this one may be
49 /// missing from a value written before it existed, and is then on, as in
50 /// [`Self::default`]: off would drop the mark on every import that value configures.
51 #[serde(default = "enabled")]
52 pub front_matter: bool,
53 /// Apply block background color from `{background_color="<value>"}`.
54 pub background_color: bool,
55 /// Apply the block's own space-above from `{top_margin=<int>}`, overriding
56 /// the document-wide paragraph spacing for that one block.
57 pub top_margin: bool,
58 /// Apply the block's own first-line indent from `{text_indent=<int>}`,
59 /// overriding the document-wide first-line indent for that one block.
60 pub text_indent: bool,
61 /// Carry the frame's semantic role from `{semantic_role=epigraph}`. Unlike its
62 /// neighbours this one describes the enclosing **blockquote**, not the paragraph it
63 /// is written on: it rides the quote's first block because that is the only channel
64 /// djot block attributes have, and the importer moves it onto the frame.
65 pub semantic_role: bool,
66}
67
68impl DjotImportOptions {
69 /// Every optional block attribute enabled — the lossless default.
70 pub const fn all() -> Self {
71 Self {
72 alignment: true,
73 line_height: true,
74 direction: true,
75 non_breakable_lines: true,
76 page_break_before: true,
77 front_matter: true,
78 background_color: true,
79 top_margin: true,
80 text_indent: true,
81 semantic_role: true,
82 }
83 }
84
85 /// No optional block attributes — import only the core structural and
86 /// inline feature set, discarding any block-attribute styling.
87 pub const fn none() -> Self {
88 Self {
89 alignment: false,
90 line_height: false,
91 direction: false,
92 non_breakable_lines: false,
93 page_break_before: false,
94 front_matter: false,
95 background_color: false,
96 top_margin: false,
97 text_indent: false,
98 semantic_role: false,
99 }
100 }
101}
102
103impl Default for DjotImportOptions {
104 fn default() -> Self {
105 Self::all()
106 }
107}
108
109/// Selects which optional block attributes the djot **exporter** emits as
110/// `{key=value}` block attributes. A disabled attribute is omitted from the
111/// output even when the model carries a value for it.
112#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
113pub struct DjotExportOptions {
114 /// Emit paragraph alignment as `{alignment=…}`.
115 pub alignment: bool,
116 /// Emit line height as `{line_height=…}`.
117 pub line_height: bool,
118 /// Emit text direction as `{direction=…}`.
119 pub direction: bool,
120 /// Emit non-breakable lines as `{non_breakable_lines=…}`.
121 pub non_breakable_lines: bool,
122 /// Emit "start on a new page" as `{page_break_before=…}`.
123 pub page_break_before: bool,
124 /// Emit the front-matter mark as `{front_matter=…}`. Missing from a serialized value
125 /// written before it existed, it is on, as in [`Self::default`]; see
126 /// [`DjotImportOptions::front_matter`].
127 #[serde(default = "enabled")]
128 pub front_matter: bool,
129 /// Emit block background color as `{background_color=…}`.
130 pub background_color: bool,
131 /// Emit the block's own space-above as `{top_margin=…}`.
132 pub top_margin: bool,
133 /// Emit the block's own first-line indent as `{text_indent=…}`.
134 pub text_indent: bool,
135 /// Emit the enclosing blockquote's semantic role as `{semantic_role=…}` on the
136 /// quote's first block, so the model→djot→model round trip stays a fixpoint.
137 pub semantic_role: bool,
138 /// Drop inline images instead of emitting `{width=… height=…}`.
139 ///
140 /// Unlike every other field here this one is not a block attribute and is
141 /// **not** governed by [`Self::all`]/[`Self::none`]: an image is content, not
142 /// styling, so "emit no optional attributes" must not quietly delete it.
143 /// Only a caller that has decided not to place the image files beside the
144 /// output turns it on.
145 #[serde(default)]
146 pub omit_images: bool,
147}
148
149impl DjotExportOptions {
150 /// Every optional block attribute emitted — the lossless default.
151 pub const fn all() -> Self {
152 Self {
153 alignment: true,
154 line_height: true,
155 direction: true,
156 non_breakable_lines: true,
157 page_break_before: true,
158 front_matter: true,
159 background_color: true,
160 top_margin: true,
161 text_indent: true,
162 semantic_role: true,
163 omit_images: false,
164 }
165 }
166
167 /// No optional block attributes — emit only the core structural and inline
168 /// feature set, dropping any block-attribute styling.
169 pub const fn none() -> Self {
170 Self {
171 alignment: false,
172 line_height: false,
173 direction: false,
174 non_breakable_lines: false,
175 page_break_before: false,
176 front_matter: false,
177 background_color: false,
178 top_margin: false,
179 text_indent: false,
180 semantic_role: false,
181 // Content, not styling — see the field's own doc.
182 omit_images: false,
183 }
184 }
185}
186
187impl Default for DjotExportOptions {
188 fn default() -> Self {
189 Self::all()
190 }
191}
192
193#[cfg(test)]
194mod tests {
195 use super::{DjotExportOptions, DjotImportOptions};
196
197 /// A value serialized before `front_matter` existed reads back with it on, as `Default`
198 /// has it, and not silently off.
199 #[test]
200 fn options_serialized_before_front_matter_read_back_with_it_on() {
201 let mut import = serde_json::to_value(DjotImportOptions::all()).unwrap();
202 import.as_object_mut().unwrap().remove("front_matter");
203 let import: DjotImportOptions = serde_json::from_value(import).unwrap();
204 assert_eq!(import, DjotImportOptions::default());
205
206 let mut export = serde_json::to_value(DjotExportOptions::all()).unwrap();
207 export.as_object_mut().unwrap().remove("front_matter");
208 let export: DjotExportOptions = serde_json::from_value(export).unwrap();
209 assert_eq!(export, DjotExportOptions::default());
210
211 // A value that states it is read as stated.
212 let none: DjotImportOptions =
213 serde_json::from_value(serde_json::to_value(DjotImportOptions::none()).unwrap())
214 .unwrap();
215 assert!(!none.front_matter);
216 }
217}