Merge branch 'main' into copilot/fix-70

Author: felix-andreas

crates/roughly/tests/format/formatter.template.md

@@ -49,7 +49,7 @@ Roughly applies specific formatting rules to different R code constructs. The fo
 ```r
 # assignment_operators : compare
 x<-1
-result<<-calculate()
+data<<-compute()
 ```
 
 **Binary operators** get spaces around them, except for range (`:`) and power (`^`) operators:
@@ -67,7 +67,7 @@ sequence=1:10
 # pipeline_operators : compare
 data %>%
 filter(condition) %>%
-summarize(mean_value=mean(value))
+select(value)
 ```
 
 ### Code Blocks and Braced Expressions
@@ -114,12 +114,11 @@ The formatter normalizes line spacing between expressions, allowing at most one
 
 ```r
 # line_spacing : compare
-calculate_mean <- function(data) {
-  clean_data <- data[!is.na(data)]
+x <- 1
+y <- 2
 
 
-  mean(clean_data)
-}
+z <- 3
 ```
 
 ### Function Calls and Arguments
@@ -128,30 +127,62 @@ Function calls receive consistent formatting with proper spacing around argument
 
 ```r
 # function_calls : compare
-calculate(data=dataset,method="mean",na.rm=TRUE)
-complex_call(argument1,
-    argument2=value,
-        argument3)
+process(data=dataset,method="mean",na.rm=TRUE)
+call(arg1,
+    arg2=value,
+        arg3)
+```
+
+**Nested function calls** can be formatted in a hugged style:
+
+```r
+# hugging_nested_function_calls : format
+# Hugged format - both functions start on the same line
+result <- outer(inner(
+  arg
+))
+
+# Expanded format - also valid
+result <- outer(
+  inner(
+    arg
+  )
+)
 ```
 
-**Argument hugging**: When function arguments can fit on a single line and the last argument's value starts on the same line as the opening parenthesis, the formatter keeps a compact format. Otherwise, it expands to multiple lines with proper indentation.
+**Mixed line formats** are allowed when the last argument starts on the same line:
+
+```r
+# mixed_line_format : format
+# This format is preserved - last argument starts on same line
+call(a = x, b = y, c = inner(
+  expr
+))
+```
 
-**Nested function calls** are formatted with hugging when appropriate:
+This behavior is particularly useful for testing frameworks and S4 method definitions:
 
 ```r
-# nested_function_calls : compare
-result <- outer(inner(a,b),other(c,d))
+# test_that_and_s4_example: format
+test_that("description", {
+  expect_equal(result, expected)
+})
+
+setMethod("show", "MyClass", function(object) {
+  cat("MyClass object\n")
+})
 ```
 
+
 ### Function Definitions
 
 Function definitions follow consistent formatting rules for parameters and body structure:
 
 ```r
 # function_definitions : compare
-calc<-function(x,y=1){x+y}
-stats<-function(data,method="mean"){
-  result(data,method)
+process<-function(x,y=1){x+y}
+filter<-function(data,method="simple"){
+  select(data,method)
 }
 ```
 
@@ -172,17 +203,15 @@ lapply(data,\(x)x+1)
 
 ```r
 # conditional_statements : compare
-if(condition){action} else{alternative}
+if(condition){action()} else{action()}
 
 if(
-  long_condition ||
+  condition ||
   other_condition){
   action()
 }
 ```
 
-**Condition hugging**: When conditions fit on a single line without comments, the formatter keeps them compact. For multiline conditions, proper indentation is applied.
-
 **Block enforcement**: If an if-statement has a multiline condition, the formatter ensures the body is wrapped in braces even if it's a single expression.
 
 ### Loops and Control Flow
@@ -198,31 +227,29 @@ for(item in collection) process(item)
 
 ```r
 # while_loops : compare
-while(condition) action()
+while(condition) process()
 ```
 
 **Repeat loops** also enforce braced blocks:
 
 ```r
 # repeat_loops : compare
-repeat action()
+repeat process()
 ```
 
 **Loop condition formatting**: Complex conditions that span multiple lines receive proper indentation within the parentheses.
 
 ### Parenthesized Expressions
 
-Parenthesized expressions maintain their layout with smart formatting for readability:
+Parenthesized expressions receive proper spacing for operators:
 
 ```r
 # parenthesized_expressions : compare
-(x+y*z)
-(long_expression+
- other_part)
+(
+  expression +
+    other_part)
 ```
 
-**Parenthesis hugging**: If the content fits on one line, parentheses hug the content. For multiline content, proper indentation is applied.
-
 ### String Literals
 
 String literals receive intelligent quote normalization. The formatter prefers double quotes (`"`) unless the string contains unescaped double quotes:
@@ -239,17 +266,17 @@ quoted_content <- 'Say "hello"'
 
 ```r
 # subsetting : compare
-data[row_index,column_index]
-environment[["variable_name"]]
-object$member_variable
+data[row,col]
+data[["name"]]
+object$value
 ```
 
 **Namespace operators** (`::` and `:::`):
 
 ```r
 # namespace_operators : compare
-package::public_function
-package:::private_function
+pkg::process
+pkg:::filter
 ```
 
 ### Unary Operators
@@ -259,15 +286,15 @@ Unary operators receive appropriate spacing based on their type and context:
 ```r
 # unary_operators : compare
 result = ! condition
-number = - 42
-formula = ~ response + predictor
+value = - 42
+formula = ~ x + y
 ```
 
 **Special spacing rule**: The `~` (formula) operator gets a space when followed by complex expressions, but not when followed by simple identifiers.
 
 ## Format Suppression
 
-You can disable formatting for specific code sections using the `# fmt: skip` comment directive:
+You can disable formatting for specific code sections using the `# fmt: skip` comment directive. This is useful when you want to preserve specific formatting for readability, such as aligned data structures.
 
 ```r
 # format_suppression : format
@@ -280,15 +307,19 @@ matrix(
   nrow=2
 ) # This code won't be reformatted
 
+# fmt: skip
 matrix(c(1, 2,
-         3, 4), nrow=2) # fmt: skip
-# The line above won't be reformatted
+         3, 4), nrow=2) # The line above won't be reformatted
 ```
 
+Without the `fmt: skip` directive, the `matrix(...)` expression would be broken into multiple lines according to standard formatting rules.
+
 The `fmt: skip` directive can be placed:
 - Before a line to skip formatting that entire expression
 - At the end of a line to skip formatting just that line
 
+You can also skip formatting for an entire file by placing `# fmt: skip-file` at the top of the file. This directive must be placed at the very beginning of the file to take effect.
+
 ## Advanced Formatting Features
 
 The formatter intelligently handles various R idioms and special patterns:
@@ -341,7 +372,6 @@ PersonClass <- R6Class(
 - **Switch statements**: Fallthrough cases (`case = ,`) are handled correctly
 - **Multi-line strings**: String literal structure is preserved
 - **Formula objects**: Proper spacing around `~` operator based on complexity
-- **S4 slot access**: `@` operator formatting maintained
 
 ## Auto-Bracing
 
@@ -351,7 +381,7 @@ The formatter automatically adds braces to control flow structures when they imp
 
 ```r
 # auto_bracing_function_defintions : compare
-f <- function(x) 
+process <- function(x) 
   x + 1
 ```
 
@@ -360,7 +390,7 @@ f <- function(x)
 ```r
 # auto_bracing_conditional_statements : compare
 if (condition)
-  single_statement
+  action()
 ```
 
 **Loops**: All loop bodies are automatically braced for consistency:
@@ -373,7 +403,7 @@ for (i in 1:n)
 
 ## Hugging Behavior
 
-"Hugging" refers to how nested function calls are formatted - keeping them compact by allowing the inner calls to start on the same line as the outer call's opening parenthesis. This is part of roughly's non-invasive approach: both hugged and expanded formats are allowed.
+"Hugging" refers to how nested expressions are formatted in multiline contexts - keeping them compact by allowing inner expressions to start on the same line as the outer expression's opening delimiter. This is part of roughly's non-invasive approach: both hugged and expanded formats are allowed, but hugging only applies to multiline expressions.
 
 **Nested function calls** can be formatted in a hugged style:
 
@@ -392,6 +422,20 @@ result <- outer(
 )
 ```
 
+**Parenthesized expressions** can also use hugging:
+
+```r
+# hugging_parenthesized : format
+(expression +
+  other_part)
+
+# Also allowed
+(
+  expression +
+    other_part
+)
+```
+
 **Non-invasive multi-line formatting**: When expressions are already multi-line, roughly only adds necessary spacing but preserves the overall structure. However, if all arguments don't fit on their separate lines, they will be properly separated:
 
 ```r
@@ -401,29 +445,6 @@ call(
   b=y, c=z)
 ```
 
-**Mixed line formats** are allowed when the last argument starts on the same line:
-
-```r
-# mixed_line_format : format
-# This format is preserved - last argument starts on same line
-call(a = x, b = y, c = inner(
-  expr
-))
-```
-
-This behavior is particularly useful for testing frameworks and S4 method definitions:
-
-```r
-# test_that_and_s4_example: format
-test_that("description", {
-  expect_equal(result, expected)
-})
-
-setMethod("show", "MyClass", function(object) {
-  cat("MyClass object\n")
-})
-```
-
 ## Line Endings
 
 The formatter automatically detects and preserves the line ending style (`LF` or `CRLF`) used in the original file.

crates/roughly/tests/snapshots/test_format__documentation_examples__assignment_operators.snap

@@ -3,4 +3,4 @@ source: crates/roughly/tests/test_format.rs
 expression: code
 ---
 x <- 1
-result <<- calculate()
+data <<- compute()

crates/roughly/tests/snapshots/test_format__documentation_examples__auto_bracing_conditional_statements.snap

@@ -3,5 +3,5 @@ source: crates/roughly/tests/test_format.rs
 expression: code
 ---
 if (condition) {
-  single_statement
+  action()
 }

crates/roughly/tests/snapshots/test_format__documentation_examples__auto_bracing_function_defintions.snap

@@ -2,6 +2,6 @@
 source: crates/roughly/tests/test_format.rs
 expression: code
 ---
-f <- function(x) {
+process <- function(x) {
   x + 1
 }

crates/roughly/tests/snapshots/test_format__documentation_examples__conditional_statements.snap

@@ -2,10 +2,10 @@
 source: crates/roughly/tests/test_format.rs
 expression: code
 ---
-if (condition) { action } else { alternative }
+if (condition) { action() } else { action() }
 
 if (
-  long_condition ||
+  condition ||
     other_condition
 ) {
   action()

crates/roughly/tests/snapshots/test_format__documentation_examples__for_loops.snap

@@ -2,6 +2,6 @@
 source: crates/roughly/tests/test_format.rs
 expression: code
 ---
-for (item in collection) {
+for (item in data) {
   process(item)
 }

crates/roughly/tests/snapshots/test_format__documentation_examples__format_suppression.snap

@@ -11,6 +11,6 @@ matrix(
   nrow=2
 ) # This code won't be reformatted
 
+# fmt: skip
 matrix(c(1, 2,
-         3, 4), nrow=2) # fmt: skip
-# The line above won't be reformatted
+         3, 4), nrow=2) # The line above won't be reformatted

crates/roughly/tests/snapshots/test_format__documentation_examples__function_calls.snap

@@ -2,9 +2,9 @@
 source: crates/roughly/tests/test_format.rs
 expression: code
 ---
-calculate(data = dataset, method = "mean", na.rm = TRUE)
-complex_call(
-  argument1,
-  argument2 = value,
-  argument3
+process(data = dataset, method = "mean", na.rm = TRUE)
+call(
+  arg1,
+  arg2 = value,
+  arg3
 )

crates/roughly/tests/snapshots/test_format__documentation_examples__function_definitions.snap

@@ -2,7 +2,7 @@
 source: crates/roughly/tests/test_format.rs
 expression: code
 ---
-calc <- function(x, y = 1) { x + y }
-stats <- function(data, method = "mean") {
-  result(data, method)
+process <- function(x, y = 1) { x + y }
+filter <- function(data, method = "simple") {
+  select(data, method)
 }