format: offer one-operand-per-line layout for and/or chains

Author: MillhioreBT

crates/emmylua_formatter/src/config/mod.rs

@@ -154,6 +154,15 @@ pub struct LayoutConfig {
     /// This applies only to the last direct expression in a statement,
     /// including standalone call statements, plus keyed table-field values.
     pub prefer_chain_break_on_statement_tail: bool,
+    /// Offer a one-operand-per-line layout candidate for same-operator binary
+    /// chains (3 or more operands sharing the same operator, such as a run of
+    /// `and`/`or` conditions).
+    ///
+    /// When the chain does not fit compactly, this lets the formatter break at
+    /// the chain's own operators (one operand per line) instead of breaking
+    /// inside an individual operand, such as expanding a nested call's
+    /// argument list.
+    pub prefer_binary_chain_operand_per_line: bool,
 }
 
 impl Default for LayoutConfig {
@@ -167,6 +176,7 @@ impl Default for LayoutConfig {
             prefer_call_args_layout_from_source: false,
             prefer_table_layout_from_source: false,
             prefer_chain_break_on_statement_tail: false,
+            prefer_binary_chain_operand_per_line: false,
         }
     }
 }

crates/emmylua_formatter/src/formatter/expr.rs

@@ -3231,6 +3231,17 @@ fn try_format_flat_binary_chain(
     let fill_parts =
         build_binary_chain_fill_parts(ctx, plan, &operands, &op_token.syntax().clone(), op);
     let packed = build_binary_chain_packed(ctx, plan, &operands, &op_token.syntax().clone(), op);
+    let one_per_line = if ctx.config.layout.prefer_binary_chain_operand_per_line {
+        Some(build_binary_chain_one_per_line(
+            ctx,
+            plan,
+            &operands,
+            &op_token.syntax().clone(),
+            op,
+        ))
+    } else {
+        None
+    };
 
     Some(choose_sequence_layout(
         ctx,
@@ -3239,6 +3250,7 @@ fn try_format_flat_binary_chain(
                 fill_parts,
             )])])]),
             packed: Some(packed),
+            one_per_line,
             ..Default::default()
         },
         SequenceLayoutPolicy {
@@ -3348,6 +3360,31 @@ fn build_binary_chain_packed(
     ])]
 }
 
+fn build_binary_chain_one_per_line(
+    ctx: &FormatContext,
+    plan: &FormatPlan,
+    operands: &[LuaExpr],
+    op_token: &LuaSyntaxToken,
+    op: BinaryOperator,
+) -> Vec<DocIR> {
+    let first_line = format_expr(ctx, plan, &operands[0]);
+
+    let mut tail = Vec::new();
+    let mut previous = &operands[0];
+    for operand in operands.iter().skip(1) {
+        let (_space_before, segment) =
+            build_binary_chain_segment(ctx, plan, previous, operand, op_token, op);
+        tail.push(ir::hard_line());
+        tail.extend(segment);
+        previous = operand;
+    }
+
+    vec![ir::group_break(vec![
+        ir::list(first_line),
+        ir::indent(tail),
+    ])]
+}
+
 fn build_binary_chain_segment(
     ctx: &FormatContext,
     plan: &FormatPlan,

crates/emmylua_formatter/src/test/breaking_tests.rs

@@ -106,6 +106,148 @@ local t = {
             r#"local t = { user = { name = "a", age = 1 }, enabled = true }
 "#,
             r#"local t = { user = { name = "a", age = 1 }, enabled = true }
+"#,
+            config
+        );
+    }
+
+    #[test]
+    fn test_binary_chain_operand_per_line_fixes_nested_call_breaking() {
+        // Without the flag, the `and` chain does not fit, and the formatter
+        // falls back to breaking inside the nested `getStorageValue` call
+        // argument list instead of breaking at the chain's own operators.
+        let config = LuaFormatConfig {
+            layout: LayoutConfig {
+                max_line_width: 120,
+                prefer_binary_chain_operand_per_line: true,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert_format_with_config!(
+            r#"if player:getStorageValue(Storage.ExplorerSociety.TheIceMusic) >= 62 and player:getStorageValue(Storage.ExplorerSociety.QuestLine) >= 62 and player:removeItem(5022, 1) then
+	player:getPosition():sendMagicEffect(CONST_ME_TELEPORT)
+	player:teleportTo(carvingTP.position)
+end
+"#,
+            r#"
+if player:getStorageValue(Storage.ExplorerSociety.TheIceMusic) >= 62
+    and player:getStorageValue(Storage.ExplorerSociety.QuestLine) >= 62
+    and player:removeItem(5022, 1) then
+    player:getPosition():sendMagicEffect(CONST_ME_TELEPORT)
+    player:teleportTo(carvingTP.position)
+end
+"#,
+            config
+        );
+    }
+
+    #[test]
+    fn test_binary_chain_operand_per_line_disabled_keeps_legacy_behavior() {
+        // Regression guard: with the flag off (the default), behavior is
+        // unchanged from before this option existed, including the
+        // less-than-ideal nested-call break.
+        let config = LuaFormatConfig {
+            layout: LayoutConfig {
+                max_line_width: 120,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert_format_with_config!(
+            r#"if player:getStorageValue(Storage.ExplorerSociety.TheIceMusic) >= 62 and player:getStorageValue(Storage.ExplorerSociety.QuestLine) >= 62 and player:removeItem(5022, 1) then
+	player:getPosition():sendMagicEffect(CONST_ME_TELEPORT)
+	player:teleportTo(carvingTP.position)
+end
+"#,
+            r#"
+if player:getStorageValue(Storage.ExplorerSociety.TheIceMusic) >= 62 and player:getStorageValue(
+        Storage.ExplorerSociety.QuestLine
+    )
+        >= 62 and player:removeItem(5022, 1) then
+    player:getPosition():sendMagicEffect(CONST_ME_TELEPORT)
+    player:teleportTo(carvingTP.position)
+end
+"#,
+            config
+        );
+    }
+
+    #[test]
+    fn test_binary_chain_operand_per_line_keeps_short_chain_flat() {
+        // A chain that already fits on one line stays flat even with the
+        // option enabled; the new candidate only wins when it is needed.
+        let config = LuaFormatConfig {
+            layout: LayoutConfig {
+                max_line_width: 120,
+                prefer_binary_chain_operand_per_line: true,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert_format_with_config!(
+            r#"if a and b and c then
+	work()
+end
+"#,
+            r#"
+if a and b and c then
+    work()
+end
+"#,
+            config
+        );
+    }
+
+    #[test]
+    fn test_binary_chain_operand_per_line_does_not_override_shorter_fill_layout() {
+        // When the existing fill/packed layout already fits without
+        // overflowing max_line_width in fewer lines than one-operand-per-line
+        // would need, the scorer keeps preferring the more compact layout.
+        let config = LuaFormatConfig {
+            layout: LayoutConfig {
+                max_line_width: 100,
+                prefer_binary_chain_operand_per_line: true,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert_format_with_config!(
+            r#"if get_value(namespace_alpha_beta) >= threshold_value and get_value(namespace_gamma_delta) >= threshold_value and remove_item(item_id_number, item_count) then
+	do_something()
+end
+"#,
+            r#"
+if get_value(namespace_alpha_beta) >= threshold_value and get_value(namespace_gamma_delta)
+        >= threshold_value and remove_item(item_id_number, item_count) then
+    do_something()
+end
+"#,
+            config
+        );
+    }
+
+    #[test]
+    fn test_binary_chain_operand_per_line_works_for_or_operator() {
+        let config = LuaFormatConfig {
+            layout: LayoutConfig {
+                max_line_width: 120,
+                prefer_binary_chain_operand_per_line: true,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        assert_format_with_config!(
+            r#"if player:getStorageValue(Storage.QuestSystem.FirstPartCompleted) == 1 or player:getStorageValue(Storage.QuestSystem.SecondPartCompleted) == 1 or player:getStorageValue(Storage.QuestSystem.ThirdPartCompleted) == 1 then
+	work()
+end
+"#,
+            r#"
+if player:getStorageValue(Storage.QuestSystem.FirstPartCompleted) == 1
+    or player:getStorageValue(Storage.QuestSystem.SecondPartCompleted) == 1
+    or player:getStorageValue(Storage.QuestSystem.ThirdPartCompleted) == 1 then
+    work()
+end
 "#,
             config
         );

docs/emmylua_formatter/options_CN.md

@@ -59,6 +59,7 @@ width = 4
 - `prefer_call_args_layout_from_source`：是否优先保留显式多行调用参数列表的源码排版目标
 - `prefer_table_layout_from_source`：是否优先保留显式多行纯数组 table 的源码排版目标
 - `prefer_chain_break_on_statement_tail`：是否优先把语句尾部的 fluent chain 断成多行
+- `prefer_binary_chain_operand_per_line`：为同一运算符的多元二元表达式链（3 个及以上操作数，例如一串 `and`/`or` 条件）提供“每个操作数一行”的候选布局
 
 默认值：
 
@@ -72,6 +73,7 @@ func_params_expand = "Auto"
 prefer_call_args_layout_from_source = false
 prefer_table_layout_from_source = false
 prefer_chain_break_on_statement_tail = false
+prefer_binary_chain_operand_per_line = false
 ```
 
 行为说明：
@@ -87,6 +89,8 @@ prefer_chain_break_on_statement_tail = false
 - `prefer_chain_break_on_statement_tail = true` 会影响语句中的最后一个直接表达式，包括独立调用语句，以及带 key 的 table field value；当它是一个足够长的 fluent chain 时，会优先改成链式断行。
 - 这里的 chain head 定义为：`root` 加上前导命名空间/字段访问，再加上第一个调用段；但如果 `root` 本身已经是一个调用，则 head 就停在这个调用本身。例如 `Builder:new():add():add()` 的 head 是 `Builder:new()`，`ConsoleFormattingBuilder():setColor():build()` 的 head 是 `ConsoleFormattingBuilder()`，`vim.api.nvim_set_keymap(...)` 的 head 是整个 `vim.api.nvim_set_keymap(...)`。
 - 这里的换行起点定义为：head 之后的第一个 continuation 段。也就是说，只有第一个调用之后仍然继续链下去的部分才会成为链式换行候选；纯命名空间限定调用不会因为这个选项被误判成 chain。
+- `prefer_binary_chain_operand_per_line = true` 适用于由同一个运算符连接的 3 个及以上操作数，最常见的场景是 `if`/`while` 条件头里的一串 `and`/`or`。它只是新增一个候选布局；格式化器仍然会在 flat、fill、packed、one-operand-per-line 之间挑选行数最少且不超过 `max_line_width` 的那个，所以短链条或者用 fill/packed 就已经能放下的链条不受影响。
+- 不开启这个选项时，如果整条链放不下，格式化器可能会转而在其中某个操作数内部断行（比如展开某个嵌套调用的参数列表），而不是在链自身的运算符处断行。开启后格式化器多了一个干净的备选方案：每个操作数单独一行，运算符放在每个续行的开头（`and`/`or` 在行首，与本项目现有二元表达式的前置运算符风格一致）。
 
 ## output
 

docs/emmylua_formatter/options_EN.md

@@ -59,6 +59,7 @@ width = 4
 - `prefer_call_args_layout_from_source`: prefer keeping the source layout goal for explicit multiline call argument lists
 - `prefer_table_layout_from_source`: prefer keeping the source layout goal for explicit multiline pure-array tables
 - `prefer_chain_break_on_statement_tail`: prefer multiline breaking for fluent chains in statement-tail position
+- `prefer_binary_chain_operand_per_line`: offer a one-operand-per-line layout candidate for same-operator binary chains (3 or more operands), such as a run of `and`/`or` conditions
 
 Default:
 
@@ -72,6 +73,7 @@ func_params_expand = "Auto"
 prefer_call_args_layout_from_source = false
 prefer_table_layout_from_source = false
 prefer_chain_break_on_statement_tail = false
+prefer_binary_chain_operand_per_line = false
 ```
 
 Behavior notes:
@@ -87,6 +89,8 @@ Behavior notes:
 - `prefer_chain_break_on_statement_tail = true` applies to the last direct expression in a statement, including standalone call statements, and also to keyed table-field values; when that expression is a long enough fluent chain, the formatter prefers chain-style breaking.
 - The chain head is defined as the `root`, plus any leading namespace or field accesses, plus the first call segment; however, if the `root` itself already ends in a call, the head stops at that call. For example, the head of `Builder:new():add():add()` is `Builder:new()`, the head of `ConsoleFormattingBuilder():setColor():build()` is `ConsoleFormattingBuilder()`, and the head of `vim.api.nvim_set_keymap(...)` is the whole `vim.api.nvim_set_keymap(...)` call.
 - The break start is defined as the first continuation segment after that head. In other words, only segments that continue after the first call are eligible for chain-style line breaking; a namespace-qualified terminal call is not treated as a fluent chain by this option.
+- `prefer_binary_chain_operand_per_line = true` applies to a run of 3 or more operands joined by the same operator, most commonly a chain of `and`/`or` conditions in an `if`/`while` header. It only adds a candidate layout; the formatter still picks whichever candidate (flat, fill, packed, or one-operand-per-line) produces the fewest lines without overflowing `max_line_width`, so short chains and chains that already fit with fill/packed are unaffected.
+- Without this option, a chain that does not fit can end up breaking inside one of its own operands (for example, expanding a nested call's argument list) instead of breaking at the chain's operators. Enabling it gives the formatter a clean alternative: one operand per line, with the operator leading each continuation line (`and`/`or` at the start of the line, matching this project's existing leading-operator style for binary expressions).
 
 ## output