support format with lsp options, add external format document

CppCXY · CppCXY · commit e9b859e570d4 · 2025-08-07T14:51:50.000+08:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -30,7 +30,7 @@ tokio-util = "0.7.15"
 walkdir = "2.5.0"
 serde_yml = "0.0.12"
 dirs = "6"
-emmylua_codestyle = "0.4.1"
+emmylua_codestyle = "0.5.0"
 wax = "0.6.0"
 percent-encoding = "2.3"
 flagset = "0.4.6"
diff --git a/README.md b/README.md
@@ -254,7 +254,7 @@ EmmyLua Analyzer Rust implements the standard LSP protocol, making it compatible
 - [📖 **Features Guide**](./docs/features/features_EN.md) - Comprehensive feature documentation
 - [⚙️ **Configuration**](./docs/config/emmyrc_json_EN.md) - Advanced configuration options
 - [🎨 **Code Style**](https://github.com/CppCXY/EmmyLuaCodeStyle/blob/master/README_EN.md) - Formatting and style guidelines
-
+- [🛠️ **External Formatter Integration**](./docs/external_format/external_formatter_options_EN.md) - Using external formatters
 ---
 
 ## 🛠️ Usage & Examples
diff --git a/crates/emmylua_ls/src/handlers/document_formatting/external_format.rs b/crates/emmylua_ls/src/handlers/document_formatting/external_format.rs
@@ -1,4 +1,4 @@
-use emmylua_code_analysis::EmmyrcExternalTool;
+use emmylua_code_analysis::{EmmyrcExternalTool, FormattingOptions};
 use std::process::Stdio;
 use std::time::Duration;
 use tokio::io::AsyncWriteExt;
@@ -9,6 +9,7 @@ pub async fn external_tool_format(
     emmyrc_external_tool: &EmmyrcExternalTool,
     text: &str,
     file_path: &str,
+    options: FormattingOptions,
 ) -> Option<String> {
     let exe_path = &emmyrc_external_tool.program;
     let args = &emmyrc_external_tool.args;
@@ -17,8 +18,9 @@ pub async fn external_tool_format(
     let mut cmd = Command::new(exe_path);
 
     for arg in args {
-        let processed_arg = arg.replace("${file}", file_path);
-        cmd.arg(processed_arg);
+        if let Some(processed_arg) = parse_macro_arg(arg, file_path, &options) {
+            cmd.arg(processed_arg);
+        }
     }
 
     cmd.stdin(Stdio::piped())
@@ -79,3 +81,97 @@ pub async fn external_tool_format(
         }
     }
 }
+
+fn parse_macro_arg(arg: &str, file_path: &str, options: &FormattingOptions) -> Option<String> {
+    let mut result = String::new();
+    let mut chars = arg.chars().peekable();
+
+    while let Some(ch) = chars.next() {
+        if ch == '$' && chars.peek() == Some(&'{') {
+            chars.next();
+
+            // collect ${} content
+            let mut content = String::new();
+            let mut brace_count = 1;
+
+            while let Some(inner_ch) = chars.next() {
+                if inner_ch == '{' {
+                    brace_count += 1;
+                    if brace_count > 1 {
+                        content.push(inner_ch);
+                    }
+                } else if inner_ch == '}' {
+                    brace_count -= 1;
+                    if brace_count == 0 {
+                        break;
+                    }
+                    content.push(inner_ch);
+                } else {
+                    content.push(inner_ch);
+                }
+            }
+
+            // parse content
+            let replacement = if content.contains('?') {
+                // handle ${key:value} format
+                let parts: Vec<&str> = content.splitn(2, '?').collect();
+                if parts.len() == 2 {
+                    let key = parts[0].trim();
+                    let value = parts[1].trim();
+
+                    let (true_value, fail_value) = if value.contains(':') {
+                        let value_parts = value.splitn(2, ':').collect::<Vec<&str>>();
+                        let true_value = value_parts[0].trim();
+                        let fail_value = value_parts.get(1).map_or("", |s| s.trim());
+                        (true_value, fail_value)
+                    } else {
+                        (value, "")
+                    };
+
+                    match key {
+                        "use_tabs" => {
+                            if options.use_tabs {
+                                true_value.to_string()
+                            } else {
+                                fail_value.to_string()
+                            }
+                        }
+                        "insert_final_newline" => {
+                            if options.insert_final_newline {
+                                true_value.to_string()
+                            } else {
+                                fail_value.to_string()
+                            }
+                        }
+                        "non_standard_symbol" => {
+                            if options.non_standard_symbol {
+                                true_value.to_string()
+                            } else {
+                                fail_value.to_string()
+                            }
+                        }
+                        _ => true_value.to_string(), // if not a predefined key, return value
+                    }
+                } else {
+                    content.clone()
+                }
+            } else {
+                // handle ${variable} format
+                match content.trim() {
+                    "file" => file_path.to_string(),
+                    "indent_size" => options.indent_size.to_string(),
+                    _ => "".to_string(),
+                }
+            };
+
+            result.push_str(&replacement);
+        } else {
+            result.push(ch);
+        }
+    }
+
+    if result.is_empty() {
+        return None; // if no content was processed, return None
+    }
+    Some(result)
+}
diff --git a/crates/emmylua_ls/src/handlers/document_formatting/mod.rs b/crates/emmylua_ls/src/handlers/document_formatting/mod.rs
@@ -1,6 +1,6 @@
 mod external_format;
 
-use emmylua_code_analysis::reformat_code;
+use emmylua_code_analysis::{FormattingOptions, reformat_code};
 use lsp_types::{
     ClientCapabilities, DocumentFormattingParams, OneOf, ServerCapabilities, TextEdit,
 };
@@ -43,11 +43,17 @@ pub async fn on_formatting_handler(
     let text = document.get_text();
     let file_path = document.get_file_path();
     let normalized_path = file_path.to_string_lossy().to_string().replace("\\", "/");
+    let formatting_options = FormattingOptions {
+        indent_size: params.options.tab_size,
+        use_tabs: !params.options.insert_spaces,
+        insert_final_newline: params.options.insert_final_newline.unwrap_or(true),
+        non_standard_symbol: !emmyrc.runtime.nonstandard_symbol.is_empty(),
+    };
 
     let mut formatted_text = if let Some(external_config) = &emmyrc.format.external_tool {
-        external_tool_format(&external_config, text, &normalized_path).await?
+        external_tool_format(&external_config, text, &normalized_path, formatting_options).await?
     } else {
-        reformat_code(text, &normalized_path)
+        reformat_code(text, &normalized_path, formatting_options)
     };
 
     if client_id.is_intellij() || client_id.is_other() {
diff --git a/crates/emmylua_ls/src/handlers/document_range_formatting/mod.rs b/crates/emmylua_ls/src/handlers/document_range_formatting/mod.rs
@@ -1,4 +1,4 @@
-use emmylua_code_analysis::range_format_code;
+use emmylua_code_analysis::{FormattingOptions, range_format_code};
 use lsp_types::{
     ClientCapabilities, DocumentRangeFormattingParams, OneOf, Position, Range, ServerCapabilities,
     TextEdit,
@@ -29,7 +29,7 @@ pub async fn on_range_formatting_handler(
     if syntax_tree.has_syntax_errors() {
         return None;
     }
-
+    let emmyrc = analysis.get_emmyrc();
     let document = analysis
         .compilation
         .get_db()
@@ -38,13 +38,20 @@ pub async fn on_range_formatting_handler(
     let text = document.get_text();
     let file_path = document.get_file_path();
     let normalized_path = file_path.to_string_lossy().to_string().replace("\\", "/");
+    let formatting_options = FormattingOptions {
+        indent_size: params.options.tab_size,
+        use_tabs: !params.options.insert_spaces,
+        insert_final_newline: params.options.insert_final_newline.unwrap_or(true),
+        non_standard_symbol: !emmyrc.runtime.nonstandard_symbol.is_empty(),
+    };
     let formatted_result = range_format_code(
         text,
         &normalized_path,
         request_range.start.line as i32,
         0,
         request_range.end.line as i32 + 1,
         0,
+        formatting_options,
     )?;
 
     let mut formatted_text = formatted_result.text;
diff --git a/docs/external_format/external_formatter_options_CN.md b/docs/external_format/external_formatter_options_CN.md
@@ -0,0 +1,99 @@
+# 外部格式化工具选项
+
+emmyLua_ls支持使用外部格式化工具来格式化 Lua 代码。通过配置 `.emmyrc.json` 文件，你可以集成任何支持命令行的代码格式化工具。
+
+## 配置格式
+
+在 `.emmyrc.json` 文件中，你可以配置外部格式化工具：
+
+```json
+{
+  "format" : {
+      "externalTool": {
+          "program": "stylua",
+          "args": [
+              "-",
+              "--stdin-filepath",
+              "${file}",
+          ],
+          "timeout": 5000
+      }
+  }
+}
+```
+
+## 配置项说明
+
+- **program**: 外部格式化工具的可执行文件路径
+- **args**: 传递给格式化工具的参数列表
+- **timeout**: 格式化操作的超时时间（毫秒），默认值为 5000ms
+
+## 变量替换
+
+在 `args` 参数中，你可以使用以下变量，它们会在运行时被实际值替换：
+
+### 简单变量
+
+| 变量 | 描述 | 示例值 |
+|------|------|--------|
+| `${file}` | 当前文件的完整路径 | `/path/to/script.lua` |
+| `${indent_size}` | 缩进大小（空格数） | `4` |
+
+### 条件变量
+
+条件变量使用 `${variable?true_value:false_value}` 的格式，根据条件返回不同的值：
+
+| 变量 | 描述 | true 时返回 | false 时返回 |
+|------|------|-------------|--------------|
+| `${use_tabs?--use-tabs:--use-spaces}` | 是否使用制表符缩进 | `--use-tabs` | `--use-spaces` |
+| `${insert_final_newline?--final-newline:}` | 是否在文件末尾插入换行符 | `--final-newline` | 空字符串 |
+| `${non_standard_symbol?--allow-non-standard}` | 是否允许非标准符号 | `--allow-non-standard` | 空字符串 |
+
+## 变量语法说明
+
+### 基本语法
+- `${variable}` - 简单变量替换
+- `${variable?value}` - 条件变量，当条件为真时返回 value，否则返回空字符串
+- `${variable?true_value:false_value}` - 条件变量，根据条件返回不同的值
+
+### 特殊处理
+- 如果条件变量的结果为空字符串，该参数将不会传递给外部工具
+- 变量名区分大小写
+- 未知的变量将保持原样不被替换
+
+## 配置示例
+
+### 使用 Stylua 格式化器
+
+```json
+{
+    "format" : {
+        "externalTool": {
+            "program": "stylua",
+            "args": [
+                "-",
+                "--stdin-filepath",
+                "${file}",
+                "--indent-width=${indent_size}",
+                "--indent-type",
+                "${use_tabs?Tabs:Spaces}"
+            ]
+        }
+    }
+}
+```
+
+## 工作流程
+
+1. 当用户触发代码格式化时，EmmyLua 分析器会读取配置的外部工具设置
+2. 解析 `args` 中的变量，将它们替换为实际值
+3. 启动外部格式化工具，并将当前代码通过 stdin 传递给它
+4. 等待外部工具完成处理，读取格式化后的代码
+5. 如果格式化成功，将结果应用到编辑器中
+
+## 错误处理
+
+- 如果外部工具不存在或无法执行，会记录错误日志
+- 如果格式化过程超时，会终止进程并记录超时错误
+- 如果外部工具返回非零退出码，会记录错误信息
+- 如果输出不是有效的 UTF-8 文本，会记录编码错误
diff --git a/docs/external_format/external_formatter_options_EN.md b/docs/external_format/external_formatter_options_EN.md
