add external tool range format document

Author: CppCXY

docs/external_format/external_formatter_options_CN.md

@@ -6,6 +6,7 @@ emmyLua_ls支持使用外部格式化工具来格式化 Lua 代码。通过配
 
 在 `.emmyrc.json` 文件中，你可以配置外部格式化工具：
 
+文档格式化配置:
 ```json
 {
   "format" : {
@@ -20,8 +21,31 @@ emmyLua_ls支持使用外部格式化工具来格式化 Lua 代码。通过配
       }
   }
 }
+
+```
+范围格式化配置:
+```json
+{
+    "format" : {
+        "externalToolRangeFormat": {
+            "program": "stylua",
+            "args": [
+                "-",
+                "--stdin-filepath",
+                "${file}",
+                "--indent-width=${indent_size}",
+                "--indent-type",
+                "${use_tabs?Tabs:Spaces}",
+                "--range-start=${start_offset}",
+                "--range-end=${end_offset}"
+            ],
+            "timeout": 5000
+        }
+    }
+}
 ```
 
+
 ## 配置项说明
 
 - **program**: 外部格式化工具的可执行文件路径
@@ -38,6 +62,10 @@ emmyLua_ls支持使用外部格式化工具来格式化 Lua 代码。通过配
 |------|------|--------|
 | `${file}` | 当前文件的完整路径 | `/path/to/script.lua` |
 | `${indent_size}` | 缩进大小（空格数） | `4` |
+| `${start_offset}` | 选定范围的起始UTF8偏移量 | `0` |
+| `${end_offset}` | 选定范围的结束UTF8偏移量 | `100` |
+| `${start_line}` | 当前文件的起始行 | `1` |
+| `${end_line}` | 当前文件的结束行 | `10` |
 
 ### 条件变量
 
@@ -78,6 +106,20 @@ emmyLua_ls支持使用外部格式化工具来格式化 Lua 代码。通过配
                 "--indent-type",
                 "${use_tabs?Tabs:Spaces}"
             ]
+        },
+        "externalToolRangeFormat": {
+            "program": "stylua",
+            "args": [
+                "-",
+                "--stdin-filepath",
+                "${file}",
+                "--indent-width=${indent_size}",
+                "--indent-type",
+                "${use_tabs?Tabs:Spaces}",
+                "--range-start=${start_offset}",
+                "--range-end=${end_offset}"
+            ],
+            "timeout": 5000
         }
     }
 }

docs/external_format/external_formatter_options_EN.md

@@ -1,13 +1,14 @@
-# External Formatter Options
+# External Formatter Tool Options
 
-[中文版本](./external_formatter_options_CN.md)
+[中文版](external_formatter_options_CN.md)
 
-EmmyLua_ls supports using external formatting tools to format Lua code. By configuring the `.emmyrc.json` file, you can integrate any command-line code formatting tool.
+EmmyLua_ls supports using external formatting tools to format Lua code. By configuring the `.emmyrc.json` file, you can integrate any code formatting tool that supports command line interface.
 
 ## Configuration Format
 
 In the `.emmyrc.json` file, you can configure external formatting tools:
 
+Document formatting configuration:
 ```json
 {
   "format" : {
@@ -22,33 +23,60 @@ In the `.emmyrc.json` file, you can configure external formatting tools:
       }
   }
 }
+
+```
+Range formatting configuration:
+```json
+{
+    "format" : {
+        "externalToolRangeFormat": {
+            "program": "stylua",
+            "args": [
+                "-",
+                "--stdin-filepath",
+                "${file}",
+                "--indent-width=${indent_size}",
+                "--indent-type",
+                "${use_tabs?Tabs:Spaces}",
+                "--range-start=${start_offset}",
+                "--range-end=${end_offset}"
+            ],
+            "timeout": 5000
+        }
+    }
+}
 ```
 
+
 ## Configuration Options
 
 - **program**: Path to the external formatting tool executable
-- **args**: List of arguments to pass to the formatting tool
-- **timeout**: Timeout for the formatting operation in milliseconds (default: 5000ms)
+- **args**: List of arguments passed to the formatting tool
+- **timeout**: Timeout for formatting operations (milliseconds), default is 5000ms
 
 ## Variable Substitution
 
-In the `args` parameter, you can use the following variables, which will be replaced with actual values at runtime:
+In the `args` parameters, you can use the following variables that will be replaced with actual values at runtime:
 
 ### Simple Variables
 
 | Variable | Description | Example Value |
 |----------|-------------|---------------|
-| `${file}` | Full path to the current file | `/path/to/script.lua` |
+| `${file}` | Full path of the current file | `/path/to/script.lua` |
 | `${indent_size}` | Indentation size (number of spaces) | `4` |
+| `${start_offset}` | Start UTF8 offset of the selected range | `0` |
+| `${end_offset}` | End UTF8 offset of the selected range | `100` |
+| `${start_line}` | Start line of the current file | `1` |
+| `${end_line}` | End line of the current file | `10` |
 
 ### Conditional Variables
 
-Conditional variables use the format `${variable?true_value:false_value}` to return different values based on conditions:
+Conditional variables use the format `${variable?true_value:false_value}`, returning different values based on conditions:
 
-| Variable | Description | When true | When false |
-|----------|-------------|-----------|------------|
+| Variable | Description | Returns when true | Returns when false |
+|----------|-------------|-------------------|-------------------|
 | `${use_tabs?--use-tabs:--use-spaces}` | Whether to use tab indentation | `--use-tabs` | `--use-spaces` |
-| `${insert_final_newline?--final-newline:}` | Whether to insert a newline at the end of file | `--final-newline` | Empty string |
+| `${insert_final_newline?--final-newline:}` | Whether to insert newline at end of file | `--final-newline` | Empty string |
 | `${non_standard_symbol?--allow-non-standard}` | Whether to allow non-standard symbols | `--allow-non-standard` | Empty string |
 
 ## Variable Syntax
@@ -60,7 +88,7 @@ Conditional variables use the format `${variable?true_value:false_value}` to ret
 
 ### Special Handling
 - If a conditional variable results in an empty string, that argument will not be passed to the external tool
-- Variable names are case sensitive
+- Variable names are case-sensitive
 - Unknown variables will remain unchanged
 
 ## Configuration Examples
@@ -80,22 +108,36 @@ Conditional variables use the format `${variable?true_value:false_value}` to ret
                 "--indent-type",
                 "${use_tabs?Tabs:Spaces}"
             ]
+        },
+        "externalToolRangeFormat": {
+            "program": "stylua",
+            "args": [
+                "-",
+                "--stdin-filepath",
+                "${file}",
+                "--indent-width=${indent_size}",
+                "--indent-type",
+                "${use_tabs?Tabs:Spaces}",
+                "--range-start=${start_offset}",
+                "--range-end=${end_offset}"
+            ],
+            "timeout": 5000
         }
     }
 }
 ```
 
 ## Workflow
 
-1. When the user triggers code formatting, the EmmyLua analyzer reads the configured external tool settings
-2. Parse the variables in `args` and replace them with actual values
-3. Start the external formatting tool and pass the current code to it through stdin
-4. Wait for the external tool to complete processing and read the formatted code
-5. If formatting is successful, apply the result to the editor
+1. When the user triggers code formatting, EmmyLua analyzer reads the configured external tool settings
+2. Parses variables in `args` and replaces them with actual values
+3. Starts the external formatting tool and passes the current code to it via stdin
+4. Waits for the external tool to complete processing and reads the formatted code
+5. If formatting is successful, applies the result to the editor
 
 ## Error Handling
 
 - If the external tool doesn't exist or cannot be executed, an error log will be recorded
-- If the formatting process times out, the process will be terminated and a timeout error will be logged
-- If the external tool returns a non-zero exit code, the error information will be logged
-- If the output is not valid UTF-8 text, an encoding error will be logged
+- If the formatting process times out, the process will be terminated and a timeout error will be recorded
+- If the external tool returns a non-zero exit code, error information will be recorded
+- If the output is not valid UTF-8 text, an encoding error will be recorded