rdlfmt/

lib.rs

//! A formatter for SystemRDL.
//!
//! ```text
//! source text
//!     |
//!     v  syntax              lossless CST, comments and all
//!     v  rules               one function per node kind
//!     v  formatter           annotated output and alignment
//!     v  String              final rendering
//! ```
//!
//! # A deliberately small intermediate representation
//!
//! Pretty-printers usually build a document IR (Wadler groups, Oppen's
//! algorithm) because their layout decisions depend on rendered width: whether
//! a list fits on one line cannot be known until everything inside it has been
//! laid out, so the decision has to be deferred and the alternatives measured.
//!
//! None of the *line breaking* rules here are width-dependent. Following the PeakRDL style
//! guide, braces always break, statements are one per line, expressions never
//! break, and a parenthesised list breaks when it holds more than one element.
//! Every one of those is decidable from the tree alone, before a single
//! character is written, so this formatter does not need groups, alternatives,
//! or a fitting algorithm.
//!
//! Column alignment does need hindsight. The formatter therefore retains a
//! narrow IR over its ordinary output: semantic row and cell boundaries grouped
//! into list-local scopes. Once every newline is final, an alignment pass
//! measures adjacent one-line rows and inserts padding before the String is
//! returned. Padding never feeds back into layout.
//!
//! # What the formatter will not do
//!
//! Reformat a file the parser did not fully understand. [`format()`] returns
//! [`FormatError`] when the parse reports errors, because the rules assume a
//! tree shape that error recovery does not guarantee, and rewriting a file
//! whose structure was guessed at is how a formatter corrupts code.
//!
//! Preprocessor directives need no separate rule against them, which is the
//! point of treating even the conditionals as trivia: a `` `ifdef `` whose
//! branches hand a brace back and forth leaves the braces unbalanced, and so is
//! refused by the same check as any other input the parser could not follow.
//! Everything else formats like a comment -- its own line, payload untouched --
//! except that a branching directive is left-aligned rather than indented with
//! the code around it, having no place in the brace hierarchy. See the docs in
//! [`crate::syntax::parser`] for why ignoring a conditional cannot corrupt
//! the file.

pub mod syntax;

mod formatter;
mod rules;

use crate::syntax::{ParseError, SyntaxKind, lex, parse};
use formatter::{Formatter, line_ending};

/// Why no formatted output was produced.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FormatError {
    /// The input did not parse. Formatting is refused rather than attempted:
    /// the rules assume a tree shape that error recovery does not guarantee.
    Parse(Vec<ParseError>),
    /// Formatting would have changed the code, not just its layout.
    ///
    /// Always a bug in this crate, never something the input can cause. The
    /// output is withheld so that the bug cannot reach a file.
    Corrupted(String),
}

impl FormatError {
    /// The parse errors that caused the refusal, or empty for other causes.
    pub fn errors(&self) -> &[ParseError] {
        match self {
            FormatError::Parse(errors) => errors,
            FormatError::Corrupted(_) => &[],
        }
    }
}

impl std::fmt::Display for FormatError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            FormatError::Parse(errors) => {
                write!(f, "cannot format input with syntax errors: ")?;
                for (i, err) in errors.iter().enumerate() {
                    if i > 0 {
                        write!(f, "; ")?;
                    }
                    write!(f, "{err}")?;
                }
                Ok(())
            }
            FormatError::Corrupted(what) => write!(
                f,
                "internal error: formatting would have changed the code ({what}); \
                 this is a bug in rdlfmt, please report it"
            ),
        }
    }
}

impl std::error::Error for FormatError {}

/// Formats SystemRDL source.
///
/// There is nothing to configure, deliberately: a formatter earns its value by
/// ending arguments, not by relocating them into a config file. Indentation is
/// four spaces, which is what the PeakRDL style guide asks for.
///
/// A `// rdlfmt: off` comment suppresses formatting for the statements that
/// follow it, until a `// rdlfmt: on` or the end of the enclosing body; a
/// `// rdlfmt: skip` covers the single statement below it. That is an opt-out
/// for one passage rather than a setting -- it travels with the code it
/// applies to, and says only that a passage is already the way its author
/// wants it.
///
/// The output is verified before it is returned: see `verify`. A caller that
/// gets `Ok` has a guarantee, not just a hope, that only whitespace moved.
///
/// # Errors
/// [`FormatError::Parse`] if `src` does not parse cleanly. The source is left
/// for the caller to report on rather than being passed through unchanged, so
/// that a broken file is never silently mistaken for a formatted one.
///
/// [`FormatError::Corrupted`] if the formatter has a bug.
pub fn format(src: &str) -> Result<String, FormatError> {
    let parsed = parse(src);
    if !parsed.errors().is_empty() {
        return Err(FormatError::Parse(parsed.errors().to_vec()));
    }

    let mut f = Formatter::new(src);
    rules::format_node(&mut f, &parsed.syntax());
    let out = f.finish();

    verify(src, &out)?;
    Ok(out)
}

/// Checks that formatting moved nothing but whitespace.
///
/// The test suite asserts this over the inputs someone thought to write down.
/// Doing it here instead makes it hold for every input there will ever be,
/// which is what justifies a tool that overwrites source files by default. The
/// cost is one extra lex of the output -- nothing next to the parse that
/// produced it.
///
/// Comments are compared alongside the code, trimmed at the end, because a
/// dropped comment is a real loss even though it changes no behaviour. The
/// trim is what lets the formatter tidy trailing spaces inside one.
fn verify(src: &str, out: &str) -> Result<(), FormatError> {
    // Checked separately because the token comparison below cannot see it: line
    // endings live inside the whitespace this function filters out, so silently
    // rewriting every one of them would pass the check that follows.
    let (want, got) = (line_ending(src), line_ending(out));
    if want != got {
        return Err(FormatError::Corrupted(format!(
            "line endings changed from {want:?} to {got:?}"
        )));
    }

    let (before, after) = (lex(src), lex(out));
    let keep = |(kind, _): &(SyntaxKind, &str)| *kind != SyntaxKind::WHITESPACE;
    let mut before = before.iter().filter(keep);
    let mut after = after.iter().filter(keep);

    loop {
        return match (before.next(), after.next()) {
            (None, None) => Ok(()),
            (Some((a, at)), Some((b, bt))) if a == b && at.trim_end() == bt.trim_end() => continue,
            (Some((a, at)), Some((b, bt))) => Err(FormatError::Corrupted(format!(
                "{a:?} {at:?} became {b:?} {bt:?}"
            ))),
            (Some((a, at)), None) => Err(FormatError::Corrupted(format!("{a:?} {at:?} was lost"))),
            (None, Some((b, bt))) => Err(FormatError::Corrupted(format!(
                "{b:?} {bt:?} appeared from nowhere"
            ))),
        };
    }
}