Add balanced line wrapping for binary operators, profiler, specify

continuation line definition

Close #270

Author: NathanLovato

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This file documents the changes made to the formatter with each release.
 
+## Unreleased: 0.22.0
+
+### Added
+
+- Added a profiling option to the benchmark script compatible with the samply profiler
+
+### Changed
+
+- Implemented new balanced line wrapping algorithm for long chains of expressions, including operations and boolean expressions
+- Specified the definition for continuation lines and changed function calls and other statements and expressions to use a single extra indent instead of two by default
+- Always force lambda functions to have a line return after the function declaration, like regular functions
+
+### Fixed
+
+- Conditions that exceed max-line-length by only a few columns get backslash + attribute-dot wrapping instead of the parenthesized and-wrap used for larger overflows (#270)
+
 ## Release 0.21.0 (2026-07-16)
 
 ### Added

Cargo.toml

@@ -67,3 +67,10 @@ path = "src/main.rs"
 [profile.release]
 strip = true
 lto = true
+
+# For the profiler, we want optimizations but also debug symbols so we can see
+# function names in the profiler UI.
+[profile.profiling]
+inherits = "release"
+debug = true
+strip = false

README.md

@@ -402,6 +402,27 @@ To run the formatter's test suite, use this command:
 cargo test
 ```
 
+### Benchmarking and profiling
+
+Run the timing benchmark to compare total formatter runtime between revisions:
+
+```bash
+cargo run --bin benchmark --release
+```
+
+The output result is the median time of multiple batches of formatter runs over the same files.
+
+To profile the run and see which functions use the most CPU time, I use the sampling profiler [samply](https://github.com/mstange/samply). Install it like this, then I've prepared a script to run the formatter while running the profiler:
+
+```bash
+cargo install --locked samply
+./benchmarks/profile.sh
+```
+
+Samply allows you to view the profiling results in Firefox's profiler UI.
+
+The script runs 5000 iterations by default, but you can pass a different count as an argument, for example `./benchmarks/profile.sh 10000`.
+
 ### Debugging and visualizing the tree structure
 
 You can use the tree-sitter command line tool to parse GDScript files and visualize the syntax tree. This shows you the structure that the tree-sitter parser generates, which you can then use to write formatting rules:

benchmarks/profile.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -e
+
+# Read first cli argument and default to 5000 otherwise.
+iterations="${1:-5000}"
+cargo build --profile profiling --bin benchmark
+exec samply record target/profiling/benchmark --profile-long "$iterations"

src/bin/benchmark.rs

@@ -3,6 +3,12 @@
 //!
 //! Run cargo run --bin benchmark --release to compile and run the benchmark.
 //! You can use it in a shell script to compare performance between two git revisions.
+//! To profile the CPU usage of the benchmark, run:
+//!
+//! ```sh
+//! cargo build --profile profiling --bin benchmark
+//! samply record target/profiling/benchmark --profile-long
+//! ```
 //!
 //! For example, to compare between this commit and the previous one:
 //!
@@ -14,110 +20,168 @@
 //! git checkout -
 //! ```
 use gdscript_formatter::{FormatterConfiguration, RenderElement, format_gdscript_with_buffers};
-use std::{fs, time::Instant};
+use std::{
+    env, fs,
+    hint::black_box,
+    time::{Duration, Instant},
+};
 
-const ITERATIONS: u16 = 40;
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let short_content = fs::read_to_string("benchmarks/gdscript_files/short.gd")?;
-    let long_content = fs::read_to_string("benchmarks/gdscript_files/long.gd")?;
-    let config = FormatterConfiguration::default();
+const PROFILE_ITERATIONS: usize = 5_000;
+const WARMUP_DURATION: Duration = Duration::from_millis(200);
+const SAMPLE_DURATION: Duration = Duration::from_millis(200);
+const SAMPLE_COUNT: usize = 10;
 
-    println!("Running GDScript Formatter Benchmark...");
+/// A struct that stores data and has functions to benchmark the GDScript
+/// formatter and measure performance.
+struct BenchmarkRunner {
+    render_elements: Vec<RenderElement>,
+    output: String,
+}
 
-    let mut render_elements: Vec<RenderElement> = Vec::new();
-    let mut output = String::new();
+struct BenchmarkMeasurement {
+    median_seconds_per_iteration: f64,
+    total_iterations: usize,
+}
 
-    println!("Running short file warmup (10 iterations)");
-    for _ in 0..10 {
-        format_gdscript_with_buffers(&short_content, &config, &mut render_elements, &mut output)?;
+impl BenchmarkRunner {
+    fn new() -> Self {
+        Self {
+            render_elements: Vec::new(),
+            output: String::new(),
+        }
     }
 
-    println!("Benchmarking short file ({} iterations)", ITERATIONS);
-    let mut start = Instant::now();
-    for _ in 0..ITERATIONS {
-        format_gdscript_with_buffers(&short_content, &config, &mut render_elements, &mut output)?;
+    fn format(&mut self, source: &str, config: &FormatterConfiguration) -> Result<(), String> {
+        format_gdscript_with_buffers(
+            black_box(source),
+            black_box(config),
+            &mut self.render_elements,
+            &mut self.output,
+        )?;
+        black_box(&self.output);
+        Ok(())
     }
-    let duration_short_file = start.elapsed();
 
-    println!("Benchmarking long file ({} iterations)...", ITERATIONS);
-    start = Instant::now();
-    for _ in 0..ITERATIONS {
-        format_gdscript_with_buffers(&long_content, &config, &mut render_elements, &mut output)?;
-    }
-    let long_time = start.elapsed();
+    fn measure(
+        &mut self,
+        source: &str,
+        config: &FormatterConfiguration,
+    ) -> Result<BenchmarkMeasurement, String> {
+        let warmup_start = Instant::now();
+        while warmup_start.elapsed() < WARMUP_DURATION {
+            self.format(source, config)?;
+        }
 
-    let safe_config = FormatterConfiguration {
-        safe: true,
-        ..config
-    };
+        let mut seconds_per_iteration = Vec::with_capacity(SAMPLE_COUNT);
+        let mut total_iterations = 0;
+        let mut sample_index = 0;
+        while sample_index < SAMPLE_COUNT {
+            let sample_start = Instant::now();
+            let mut sample_iterations = 0;
+            while sample_start.elapsed() < SAMPLE_DURATION {
+                self.format(source, config)?;
+                sample_iterations += 1;
+            }
+            let sample_seconds = sample_start.elapsed().as_secs_f64();
+            seconds_per_iteration.push(sample_seconds / sample_iterations as f64);
+            total_iterations += sample_iterations;
+            sample_index += 1;
+        }
 
-    println!(
-        "Benchmarking short file with safe mode ({} iterations)...",
-        ITERATIONS
-    );
-    start = Instant::now();
-    for _ in 0..ITERATIONS {
-        format_gdscript_with_buffers(
-            &short_content,
-            &safe_config,
-            &mut render_elements,
-            &mut output,
-        )?;
+        let mut current_index = 1;
+        while current_index < seconds_per_iteration.len() {
+            let mut sorted_index = current_index;
+            while sorted_index > 0
+                && seconds_per_iteration[sorted_index] < seconds_per_iteration[sorted_index - 1]
+            {
+                seconds_per_iteration.swap(sorted_index, sorted_index - 1);
+                sorted_index -= 1;
+            }
+            current_index += 1;
+        }
+
+        Ok(BenchmarkMeasurement {
+            median_seconds_per_iteration: seconds_per_iteration[SAMPLE_COUNT / 2],
+            total_iterations,
+        })
     }
-    let duration_short_file_safe = start.elapsed();
+}
 
-    println!(
-        "Benchmarking long file with safe mode ({} iterations)...",
-        ITERATIONS
-    );
-    start = Instant::now();
-    for _ in 0..ITERATIONS {
-        format_gdscript_with_buffers(
-            &long_content,
-            &safe_config,
-            &mut render_elements,
-            &mut output,
-        )?;
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let short_content = fs::read_to_string("benchmarks/gdscript_files/short.gd")?;
+    let long_content = fs::read_to_string("benchmarks/gdscript_files/long.gd")?;
+    let config = FormatterConfiguration::default();
+
+    let mut arguments = env::args();
+    arguments.next();
+    if let Some(argument) = arguments.next() {
+        if argument != "--profile-long" {
+            return Err(format!("Unknown benchmark argument: {argument}").into());
+        }
+        let iterations = if let Some(value) = arguments.next() {
+            value.parse::<usize>()?
+        } else {
+            PROFILE_ITERATIONS
+        };
+        if arguments.next().is_some() {
+            return Err("Usage: benchmark --profile-long [iterations]".into());
+        }
+
+        let mut runner = BenchmarkRunner::new();
+        for _ in 0..10 {
+            runner.format(&long_content, &config)?;
+        }
+        println!("Profiling long GDScript file ({iterations} iterations)...");
+        for _ in 0..iterations {
+            runner.format(&long_content, &config)?;
+        }
+        return Ok(());
     }
-    let long_time_safe = start.elapsed();
 
-    let average_time_short = duration_short_file.as_micros() as f64 / f64::from(ITERATIONS);
-    let average_time_long = long_time.as_micros() as f64 / f64::from(ITERATIONS);
-    let average_time_safe_short =
-        duration_short_file_safe.as_micros() as f64 / f64::from(ITERATIONS);
-    let average_time_safe_long = long_time_safe.as_micros() as f64 / f64::from(ITERATIONS);
+    println!("Running GDScript Formatter Benchmark...");
+
+    let safe_config = FormatterConfiguration {
+        safe: true,
+        ..config.clone()
+    };
+    let mut runner = BenchmarkRunner::new();
+    println!("Benchmarking short file...");
+    let short = runner.measure(&short_content, &config)?;
+    println!("Benchmarking short file with safe mode...");
+    let short_safe = runner.measure(&short_content, &safe_config)?;
+    println!("Benchmarking long file...");
+    let long = runner.measure(&long_content, &config)?;
+    println!("Benchmarking long file with safe mode...");
+    let long_safe = runner.measure(&long_content, &safe_config)?;
 
     let short_slowdown =
-        ((average_time_safe_short - average_time_short) / average_time_short) * 100.0;
-    let long_slowdown = ((average_time_safe_long - average_time_long) / average_time_long) * 100.0;
+        (short_safe.median_seconds_per_iteration / short.median_seconds_per_iteration - 1.0)
+            * 100.0;
+    let long_slowdown =
+        (long_safe.median_seconds_per_iteration / long.median_seconds_per_iteration - 1.0) * 100.0;
 
     println!("\nBenchmark Results:");
     println!("=================");
     println!(
-        "Short file ({} iterations): {:?} (avg: {:.2}ms per iteration)",
-        ITERATIONS,
-        duration_short_file,
-        average_time_short / 1000.0
+        "Short file ({} iterations): {:.3}ms median per iteration",
+        short.total_iterations,
+        short.median_seconds_per_iteration * 1000.0
     );
     println!(
-        "Long file ({} iterations):   {:?} (avg: {:.2}ms per iteration)",
-        ITERATIONS,
-        long_time,
-        average_time_long / 1000.0
+        "Long file ({} iterations):   {:.3}ms median per iteration",
+        long.total_iterations,
+        long.median_seconds_per_iteration * 1000.0
     );
     println!(
-        "Short file with safe mode ({} iterations): {:?} (avg: {:.2}ms per iteration, {:.1}% slower)",
-        ITERATIONS,
-        duration_short_file_safe,
-        average_time_safe_short / 1000.0,
+        "Short file with safe mode ({} iterations): {:.3}ms median per iteration, {:.1}% slower",
+        short_safe.total_iterations,
+        short_safe.median_seconds_per_iteration * 1000.0,
         short_slowdown
     );
     println!(
-        "Long file with safe mode ({} iterations):   {:?} (avg: {:.2}ms per iteration, {:.1}% slower)",
-        ITERATIONS,
-        long_time_safe,
-        average_time_safe_long / 1000.0,
+        "Long file with safe mode ({} iterations):   {:.3}ms median per iteration, {:.1}% slower",
+        long_safe.total_iterations,
+        long_safe.median_seconds_per_iteration * 1000.0,
         long_slowdown
     );