auto import 文档

Author: CppCXY

README.md

@@ -15,7 +15,7 @@
 * [格式化行为介绍](docs/format_action.md)
 * [如何配置格式化](docs/format_config.md)
 * [代码诊断配置](docs/diagnosis_config.md)
-
+* [auto import配置](docs/auto_import_config.md)
 # Contribute
 
 任何pr或者issue都是欢迎的

README_EN.md

@@ -15,7 +15,7 @@ In addition to providing language service examples, the project also provides an
 * [Introduction to formatting behavior](docs/format_action_EN.md)
 * [How to configure formatting](docs/format_config_EN.md)
 * [Code diagnosis configuration](docs/diagnosis_config_EN.md)
-
+* [auto import configuration](docs/auto_import_config_EN.md)
 # Contribute
 
 Any pr or issue are welcome 

docs/auto_import_config.md

@@ -0,0 +1,81 @@
+# Auto Import
+
+现在大部分语言插件都有auto import方面的功能，lua在这方面由于模块化方式不统一，个人对模块的理解和使用上差异较大，导致auto import 方面的插件几乎没有。
+
+该项目提供一种被普遍使用的近乎于标准的引入模块的方式的auto import功能。
+
+## lua.module.json 配置文件
+
+auto import 功能不再使用.editorconfig文件作为配置文件。采用lua.module.json作为配置文件，该文件位于哪个目录内则该目录内的所有lua文件会以该目录内的lua.module.json为模块配置。并且扩展的起始目录为该目录。
+
+如果工作区内存在多个lua.module.json则采用就近原则，也就是说一个文件的模块配置以最靠近它的lua.module.json为准。
+
+
+### lua.module.json 基本形式
+```json
+{
+    "name": "root",
+    "import": [
+        "root"
+    ]
+}
+```
+
+该基本形式定义了模块名称和引入模块名，也就是说在模块(lua.modudle.json称为模块)定义了自身名称之后，可以通过import字段引入该名称，对于该模块能够影响的所有lua文件，只能看见到import字段引入的模块名称引入的lua模块路径。
+
+换句话说对于以下目录结构
+
+```plaintext
+scirpt
+|-lua.module.json 
+|-aaa.lua
+|-lib
+| |-lua.module.json
+| |-bbb.lua
+```
+
+如果lua.module.json的内容分别
+```json
+// script/lua.module.json
+{
+    "name": "root",
+    "import": [
+        "root", "lib"
+    ]
+}
+// script/lib/lua.module.json
+{
+    "name": "lib",
+    "import": [
+        "lib"
+    ]
+}
+```
+
+则lib目录下的bbb文件在auto import时是无法看见aaa.lua文件的因为他没有引入root模块
+而script/aaa.lua文件是可以看见bbb.lua文件的，因为他引入了lib模块名
+
+### 配置项 separator
+
+该配置项决定的是auto import时路径的分隔符号，一般来说lua推荐的是 '.' 作为模块路径分隔符号，但是很多项目并不是足够的规范采用 '/' 作为分隔符。
+
+该配置项的默认值是 '.'
+
+### 配置项 import.function
+
+该配置项指示auto import时采用的引入函数，一般来说lua标准是使用 require 函数，但是有很多项目另外造了个用法近似语义略有区别的函数引入模块比如 import
+
+该配置项默认值是 "require"
+
+### 配置项 special.module
+
+该配置项是数组，基本形式是
+```json
+{
+    "special.module": [
+        {"name": "socket_core", "module": "socket.core"}
+    ]
+}
+```
+该配置项是对某些已有的模块的auto import 匹配名称做设定，当有如上设定时，输入socket_core 时会自动引入socket.core模块
+

docs/auto_import_config_EN.md

@@ -0,0 +1,78 @@
+# Auto Import
+
+Nowadays, most language plugins have auto import functions. Due to the inconsistent modularization of Lua in this respect, there are large differences in personal understanding and use of modules, resulting in almost no auto import plugins.
+
+This project provides a commonly used auto import function that is almost a standard way of importing modules.
+
+## lua.module.json configuration file
+
+The auto import function no longer uses the .editorconfig file as a configuration file. Use lua.module.json as the configuration file. In which directory the file is located, all lua files in that directory will use lua.module.json in that directory as the module configuration. And the starting directory of the extension is this directory.
+
+If there are multiple lua.module.json in the workspace, the principle of proximity is adopted, which means that the module configuration of a file is based on the lua.module.json closest to it.
+
+### lua.module.json basic form
+```json
+{
+     "name": "root",
+     "import": [
+         "root"
+     ]
+}
+```
+
+This basic form defines the module name and the imported module name, that is to say, after the module (lua.modudle.json is called the module) defines its own name, the name can be imported through the import field for all lua files that the module can affect , You can only see the lua module path introduced by the module name introduced in the import field.
+
+In other words for the following directory structure
+```plaintext
+scirpt
+|-lua.module.json
+|-aaa.lua
+|-lib
+| |-lua.module.json
+| |-bbb.lua
+```
+
+If the contents of lua.module.json are respectively
+```json
+// script/lua.module.json
+{
+     "name": "root",
+     "import": [
+         "root", "lib"
+     ]
+}
+// script/lib/lua.module.json
+{
+     "name": "lib",
+     "import": [
+         "lib"
+     ]
+}
+```
+
+Then the bbb file in the lib directory cannot see the aaa.lua file during auto import because it did not introduce the root module
+The script/aaa.lua file can see the bbb.lua file because it introduced the lib module name
+
+### Configuration "separator"
+
+This configuration item determines the path separator symbol during auto import. Generally speaking, Lua recommends'.' as the module path separator symbol, but many items are not sufficiently standardized to use'/' as the separator.
+
+The default value of this configuration item is'.'
+
+### Configuration "import.function"
+
+This configuration item indicates the import function used in auto import. Generally speaking, the Lua standard uses the require function, but many projects have also created a function with slightly different usage and semantics to import modules such as import
+
+The default value of this configuration item is "require"
+
+### Configuration item special.module
+
+The configuration item is an array, the basic form is
+```json
+{
+     "special.module": [
+         {"name": "socket_core", "module": "socket.core"}
+     ]
+}
+```
+This configuration item is to set the auto import matching name of some existing modules. When the above settings are set, the socket.core module will be automatically imported when socket_core is entered.