badness-formatter 0.13.0

Deterministic, rule-based formatter for LaTeX and BibTeX
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
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
//! Formatter configuration.
//!
//! Under the optional `serde` feature every type here is (de)serializable, and
//! under `schema` it also derives `schemars::JsonSchema`. Both are off by
//! default: the CLI keeps its own serde-named mirrors in `config.rs` so the
//! TOML spelling stays a config concern. The features exist for embedders that
//! publish a config schema. Serialized names are public API and use kebab case.

/// How the formatter lays out line breaks inside a paragraph.
///
/// The sentence-boundary detection behind [`WrapMode::Sentence`] and
/// [`WrapMode::Semantic`] is a per-language abbreviation profile
/// (`formatter::sentence`); the language and any user no-break abbreviations are
/// resolved from config into the [`SentenceOptions`](super::SentenceOptions)
/// threaded through the lowering.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(rename_all = "kebab-case")
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub enum WrapMode {
    /// Greedy fill: pack words up to `line_width`, breaking only where the next
    /// word would not fit. The default.
    #[default]
    Reflow,
    /// Preserve acceptable authored breaks and redistribute only the smallest
    /// region needed to satisfy `line_width` and approach the soft equilibrium
    /// target ([`FormatStyle::stable_wrap_target`]). Aimed at keeping revision
    /// diffs small: a small prose edit perturbs the smallest possible region.
    Stable,
    /// Wrap after each sentence (one sentence per line). Line width is ignored — a
    /// long sentence stays on one line.
    Sentence,
    /// Semantic line breaks (<https://sembr.org/>): keep the author's soft line
    /// breaks, add a break after each sentence, and fill overlong lines to
    /// `line_width`. Clause boundaries survive only where the author placed a
    /// break (no comma/colon detection). A zero width disables width-based breaks.
    Semantic,
    /// Leave paragraph line breaks exactly as authored (only collapse trailing
    /// whitespace and blank-line runs, as before reflow existed).
    Preserve,
}

/// How a single-formula *display-math* body (`\[…\]`, `$$…$$`, a non-grid
/// `equation`) is line-broken. Grid environments (`align`, `gather`, matrices)
/// and inline `$…$` are unaffected.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(rename_all = "kebab-case")
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub enum MathWrap {
    /// Derive from the resolved [`WrapMode`]: [`WrapMode::Preserve`] gives
    /// [`MathWrap::Preserve`], every other wrap mode gives [`MathWrap::Break`].
    /// The default.
    #[default]
    Auto,
    /// Keep the author's line breaks inside the body. Content within each
    /// authored line is still normalized (operator spacing, script tightening),
    /// and lines sit at the body indent.
    Preserve,
    /// Never insert breaks: the body stays on one line, overflowing the line
    /// width if too long (matching inline math's behavior).
    SingleLine,
    /// Break a too-long body before its top-level binary/relation operators
    /// (amsmath style).
    Break,
}

impl MathWrap {
    /// Resolve [`MathWrap::Auto`] against the effective wrap mode. Never
    /// returns `Auto`.
    #[must_use]
    pub fn resolve(self, wrap: WrapMode) -> Self {
        match self {
            Self::Auto => {
                if wrap == WrapMode::Preserve {
                    Self::Preserve
                } else {
                    Self::Break
                }
            }
            other => other,
        }
    }
}

/// The byte sequence the formatter's line breaks render as.
///
/// The layout engine always builds output with `\n` (the printer is the sole
/// authority on *where* breaks go); this only selects how those breaks, and the
/// ones carried through from the source, are spelled in the final string. The
/// conversion is document-wide — protected regions included, since a `verbatim`
/// body whose line terminators disagreed with the rest of the file would be a
/// mixed-ending document (see the invariant note in
/// `docs/src/development/architecture.md`, § *The formatter*).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(rename_all = "kebab-case")
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub enum LineEnding {
    /// Keep what the source used: `\r\n` if the document's first line break is a
    /// CRLF, `\n` otherwise. The default, so formatting never rewrites a file's
    /// line endings behind the author's back.
    #[default]
    Auto,
    /// Always `\n` (Unix).
    Lf,
    /// Always `\r\n` (Windows).
    Crlf,
    /// `\r\n` on Windows, `\n` everywhere else.
    Native,
}

/// How continuation lines in a list item are indented from the `\item` column.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(rename_all = "kebab-case")
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub enum ItemIndent {
    /// Align continuations under the body following a bare `\item `. The default.
    #[default]
    Hang,
    /// Indent continuations by one `indent_width` step.
    Indent,
    /// Align continuations with the `\item` command.
    None,
}

impl LineEnding {
    /// Resolve to a concrete ending. `detected` is what the source used and is
    /// consulted only by [`LineEnding::Auto`]; the result is never `Auto` or
    /// `Native`.
    #[must_use]
    pub fn resolve(self, detected: Self) -> Self {
        match self {
            Self::Auto => match detected {
                Self::Crlf => Self::Crlf,
                _ => Self::Lf,
            },
            Self::Native => {
                if cfg!(windows) {
                    Self::Crlf
                } else {
                    Self::Lf
                }
            }
            other => other,
        }
    }

    /// The bytes this ending renders as. `Auto`/`Native` answer as `Lf`; call
    /// [`LineEnding::resolve`] first.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Crlf => "\r\n",
            _ => "\n",
        }
    }

    /// What `text` uses: [`LineEnding::Crlf`] if its first line break is a CRLF,
    /// [`LineEnding::Lf`] otherwise (including a document with no line break at
    /// all). Never returns `Auto` or `Native`.
    #[must_use]
    pub fn detect(text: &str) -> Self {
        match text.find('\n') {
            Some(idx) if idx > 0 && text.as_bytes()[idx - 1] == b'\r' => Self::Crlf,
            _ => Self::Lf,
        }
    }
}

/// [`LineEnding::detect`] over a tree's text, chunk by chunk, so a whole-document
/// `String` is never materialized just to look at the first line break. `\r\n` is
/// a single `NEWLINE` token, so the pair cannot straddle a chunk boundary — the
/// `prev_cr` carry is belt-and-braces.
pub(crate) fn detect_line_ending(text: &rowan::SyntaxText) -> LineEnding {
    let mut detected = LineEnding::Lf;
    let mut prev_cr = false;
    // `Err` is the early exit: the first line break decides.
    let _: Result<(), ()> = text.try_for_each_chunk(|chunk| {
        if let Some(idx) = chunk.find('\n') {
            let crlf = if idx == 0 {
                prev_cr
            } else {
                chunk.as_bytes()[idx - 1] == b'\r'
            };
            if crlf {
                detected = LineEnding::Crlf;
            }
            return Err(());
        }
        prev_cr = chunk.ends_with('\r');
        Ok(())
    });
    detected
}

/// Rewrite `out`'s line terminators as `resolved` (already through
/// [`LineEnding::resolve`], so `Auto`/`Native` render as LF).
///
/// Only the `\r\n`/`\n` pair is converted; a lone `\r` — which the parser also
/// lexes as a line break, but which can only reach the output through a verbatim
/// region — is left exactly as authored, keeping this transformation the
/// well-understood CRLF/LF one.
pub(crate) fn apply_line_ending(out: &mut String, resolved: LineEnding) {
    let needs_work = match resolved {
        LineEnding::Crlf => out.contains('\n'),
        _ => out.contains("\r\n"),
    };
    if !needs_work {
        return;
    }

    let ending = resolved.as_str();
    let mut result = String::with_capacity(out.len() + out.len() / 16);
    for (i, segment) in out.split('\n').enumerate() {
        if i > 0 {
            result.push_str(ending);
        }
        result.push_str(segment.strip_suffix('\r').unwrap_or(segment));
    }
    *out = result;
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(
    feature = "serde",
    derive(serde::Serialize, serde::Deserialize),
    serde(default, rename_all = "kebab-case")
)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct FormatStyle {
    /// Width used for layout decisions. Zero disables width-based wrapping;
    /// structural breaks and the selected paragraph policy still apply.
    pub line_width: usize,
    pub indent_width: usize,
    pub item_indent: ItemIndent,
    pub wrap: WrapMode,
    pub math_wrap: MathWrap,
    pub line_ending: LineEnding,
}

impl Default for FormatStyle {
    fn default() -> Self {
        Self {
            line_width: 80,
            indent_width: 2,
            item_indent: ItemIndent::default(),
            wrap: WrapMode::default(),
            math_wrap: MathWrap::default(),
            line_ending: LineEnding::default(),
        }
    }
}

/// Columns below `line_width` that [`WrapMode::Stable`] aims for as its soft
/// equilibrium target. A larger offset widens the acceptable band
/// `[target, line_width]`, so more authored breaks fall inside it and survive
/// untouched — which is the whole point of the mode (minimize revision diffs).
/// Deliberately *not* configurable yet: keeping the config surface minimal (see
/// the maintainer discussion on the PR). Promote this to a `FormatStyle`/config
/// field if a concrete user need for tuning it appears.
pub(crate) const STABLE_WRAP_TARGET_OFFSET: usize = 15;

/// Leave headroom for column arithmetic while exceeding any realizable document.
pub(crate) const UNLIMITED_LINE_WIDTH: usize = usize::MAX / 2;

impl FormatStyle {
    pub(crate) fn effective_line_width(self) -> usize {
        if self.line_width == 0 {
            UNLIMITED_LINE_WIDTH
        } else {
            self.line_width
        }
    }

    /// Soft equilibrium target for [`WrapMode::Stable`]: [`STABLE_WRAP_TARGET_OFFSET`]
    /// columns below the hard `line_width`, clamped to at least one column. It can
    /// never exceed a positive hard width, including for styles built directly
    /// by API callers. Zero means unlimited width: stable wrapping then retains
    /// authored breaks without balancing line lengths.
    pub fn stable_wrap_target(self) -> usize {
        if self.line_width == 0 {
            return 0;
        }
        self.line_width
            .saturating_sub(STABLE_WRAP_TARGET_OFFSET)
            .clamp(1, self.line_width.max(1))
    }
}

#[cfg(all(test, feature = "serde"))]
mod serde_tests {
    use super::{FormatStyle, ItemIndent, LineEnding, MathWrap, WrapMode};

    /// The wire spelling of every variant, as a `match` so a new variant fails
    /// to compile here instead of silently shipping an unchecked spelling.
    /// These strings are `badness.toml`'s, and embedders (the dprint plugin)
    /// publish them in their own config schema.
    fn wrap_wire(mode: WrapMode) -> &'static str {
        match mode {
            WrapMode::Reflow => "reflow",
            WrapMode::Stable => "stable",
            WrapMode::Sentence => "sentence",
            WrapMode::Semantic => "semantic",
            WrapMode::Preserve => "preserve",
        }
    }

    fn math_wrap_wire(mode: MathWrap) -> &'static str {
        match mode {
            MathWrap::Auto => "auto",
            MathWrap::Preserve => "preserve",
            MathWrap::SingleLine => "single-line",
            MathWrap::Break => "break",
        }
    }

    fn line_ending_wire(ending: LineEnding) -> &'static str {
        match ending {
            LineEnding::Auto => "auto",
            LineEnding::Lf => "lf",
            LineEnding::Crlf => "crlf",
            LineEnding::Native => "native",
        }
    }

    fn item_indent_wire(indent: ItemIndent) -> &'static str {
        match indent {
            ItemIndent::Hang => "hang",
            ItemIndent::Indent => "indent",
            ItemIndent::None => "none",
        }
    }

    fn round_trip<T>(value: T, expected: &str)
    where
        T: serde::Serialize + serde::de::DeserializeOwned + PartialEq + std::fmt::Debug,
    {
        let json = serde_json::to_string(&value).expect("serializes");
        assert_eq!(json, format!("\"{expected}\""));
        let back: T = serde_json::from_str(&json).expect("deserializes");
        assert_eq!(back, value);
    }

    #[test]
    fn wrap_modes_use_their_toml_spelling() {
        for mode in [
            WrapMode::Reflow,
            WrapMode::Stable,
            WrapMode::Sentence,
            WrapMode::Semantic,
            WrapMode::Preserve,
        ] {
            round_trip(mode, wrap_wire(mode));
        }
    }

    #[test]
    fn math_wraps_use_their_toml_spelling() {
        for mode in [
            MathWrap::Auto,
            MathWrap::Preserve,
            MathWrap::SingleLine,
            MathWrap::Break,
        ] {
            round_trip(mode, math_wrap_wire(mode));
        }
    }

    #[test]
    fn line_endings_use_their_toml_spelling() {
        for ending in [
            LineEnding::Auto,
            LineEnding::Lf,
            LineEnding::Crlf,
            LineEnding::Native,
        ] {
            round_trip(ending, line_ending_wire(ending));
        }
    }

    #[test]
    fn item_indents_use_their_toml_spelling() {
        for indent in [ItemIndent::Hang, ItemIndent::Indent, ItemIndent::None] {
            round_trip(indent, item_indent_wire(indent));
        }
    }

    #[test]
    fn format_style_keys_are_kebab_case_and_default_the_rest() {
        let json = serde_json::to_value(FormatStyle::default()).expect("serializes");
        let object = json.as_object().expect("an object");
        let mut keys: Vec<_> = object.keys().map(String::as_str).collect();
        keys.sort_unstable();
        assert_eq!(
            keys,
            [
                "indent-width",
                "item-indent",
                "line-ending",
                "line-width",
                "math-wrap",
                "wrap"
            ]
        );

        let partial: FormatStyle =
            serde_json::from_str(r#"{"line-width": 100}"#).expect("deserializes");
        assert_eq!(
            partial,
            FormatStyle {
                line_width: 100,
                ..FormatStyle::default()
            }
        );
    }
}

#[cfg(all(test, feature = "schema"))]
mod schema_tests {
    use super::{ItemIndent, LineEnding, MathWrap, WrapMode};

    /// The schema an embedder publishes has to enumerate the accepted values,
    /// not just say "string".
    fn variants(schema: schemars::Schema) -> Vec<String> {
        let json = serde_json::to_value(schema).expect("schema serializes");
        let mut values: Vec<String> = json
            .get("oneOf")
            .and_then(|one_of| one_of.as_array())
            .expect("an enum schema is a oneOf")
            .iter()
            .map(|variant| {
                variant
                    .get("const")
                    .and_then(|value| value.as_str())
                    .expect("each variant is a const")
                    .to_string()
            })
            .collect();
        values.sort();
        values
    }

    #[test]
    fn enums_advertise_their_wire_values() {
        assert_eq!(
            variants(schemars::schema_for!(WrapMode)),
            ["preserve", "reflow", "semantic", "sentence", "stable"]
        );
        assert_eq!(
            variants(schemars::schema_for!(MathWrap)),
            ["auto", "break", "preserve", "single-line"]
        );
        assert_eq!(
            variants(schemars::schema_for!(LineEnding)),
            ["auto", "crlf", "lf", "native"]
        );
        assert_eq!(
            variants(schemars::schema_for!(ItemIndent)),
            ["hang", "indent", "none"]
        );
    }
}