feat: add --help

changelog.md

@@ -8,6 +8,7 @@
 * `FIX` reimplement section `luals.config` in file doc.json
 * `FIX` incorrect file names in file doc.json
 * `FIX` remove extra `./` path prefix in the check report when using `--check=.`
+* `NEW` CLI: added `--help`.
 
 ## 3.13.6
 `2025-2-6`

script/cli/help.lua

@@ -0,0 +1,161 @@
+local util = require 'utility'
+
+--- @class cli.arg
+--- @field type? string|string[]
+--- @field description string Description of the argument in markdown format.
+--- @field example? string
+--- @field default? any
+
+--- @type table<string, cli.arg>
+local args = {
+    ['--help'] = {
+        description = [[
+            Print this message.
+        ]],
+    },
+    ['--check'] = {
+        type = 'string',
+        description = [[
+            Perform a "diagnosis report" where the results of the diagnosis are written to the logpath.
+        ]],
+        example = [[--check=C:\Users\Me\path\to\workspace]]
+    },
+    ['--checklevel'] = {
+        type = 'string',
+        description = [[
+            To be used with --check. The minimum level of diagnostic that should be logged.
+            Items with lower priority than the one listed here will not be written to the file.
+            Options include, in order of priority:
+
+                - Error
+                - Warning
+                - Information
+                - Hint
+        ]],
+        default = 'Warning',
+        example = [[--checklevel=Information]]
+    },
+    ['--check_format'] = {
+        type = { 'json',  'pretty' },
+        description = [[
+            Output format for the check results.
+            - 'pretty': results are displayed to stdout in a human-readable format.
+            - 'json': results are written to a file in JSON format. See --check_out_path
+        ]],
+        default = 'pretty'
+    },
+    ['--version'] = {
+        type = 'boolean',
+        description = [[
+            Get the version of the Lua language server.
+            This will print it to the command line and immediately exit.
+        ]],
+    },
+    ['--doc'] = {
+        type = 'string',
+        description = [[
+            Generate documentation from a workspace.
+            The files will be output in your log path.
+        ]],
+        example = [[--doc=C:/Users/Me/Documents/myLuaProject/]]
+    },
+    ['--doc_out_path'] = {
+        type = 'string',
+        description = [[
+            The path to output generated documentation at.
+            See --doc for more info.
+        ]],
+        example = [[--doc_out_path=C:/Users/Me/Documents/myLuaProjectDocumentation]]
+    },
+    ['--logpath'] = {
+        type = 'string',
+        description = [[
+            Where the log should be written to.
+        ]],
+        default = './log',
+        example = [[--logpath=D:/luaServer/logs]]
+    },
+    ['--loglevel'] = {
+        type = 'string',
+        description = [[
+            The minimum level of logging that should appear in the logfile.
+            Can be used to log more detailed info for debugging and error reporting.
+
+            Options:
+
+                - error
+                - warn
+                - info
+                - debug
+                - trace
+        ]],
+        example = [[--loglevel=trace]]
+    },
+    ['--metapath'] = {
+        type = 'string',
+        description = [[
+            Where the standard Lua library definition files should be generated to.
+        ]],
+        default = './meta',
+        example = [[--metapath=D:/sumnekoLua/metaDefintions]]
+    },
+    ['--locale'] = {
+        type = 'string',
+        description = [[
+            The language to use. Defaults to en-us.
+            Options can be found in locale/ .
+        ]],
+        example = [[--locale=zh-cn]]
+    },
+    ['--configpath'] = {
+        type = 'string',
+        description = [[
+            The location of the configuration file that will be loaded.
+            Can be relative to the workspace.
+            When provided, config files from elsewhere (such as from VS Code) will no longer be loaded.
+        ]],
+        example = [[--configpath=sumnekoLuaConfig.lua]]
+    },
+    ['--force-accept-workspace'] = {
+        type = 'boolean',
+        description = [[
+            Allows the use of root/home directory as the workspace.
+        ]]
+    },
+    ['--socket'] = {
+        type = 'number',
+        description = [[
+            Will communicate to a client over the specified TCP port instead of through stdio.
+        ]],
+        example = [[--socket=5050]]
+    },
+    ['--develop'] = {
+        type = 'boolean',
+        description = [[
+            Enables development mode. This allows plugins to write to the logpath.
+        ]]
+    }
+}
+
+for nm, attrs in util.sortPairs(args) do
+    if attrs.type == 'boolean' then
+        print(nm)
+    else
+        print(nm .. "=<value>")
+    end
+    if attrs.description then
+        local normalized_description = attrs.description:gsub("^%s+", ""):gsub("\n%s+", "\n"):gsub("%s+$", "")
+        print("\n    " .. normalized_description:gsub('\n', '\n    '))
+    end
+    local attr_type = attrs.type
+    if type(attr_type) == "table" then
+        print("\n    Values: " .. table.concat(attr_type, ', '))
+    end
+    if attrs.default then
+        print("\n    Default: " .. tostring(attrs.default))
+    end
+    if attrs.example then
+        print("\n    Example: " .. attrs.example)
+    end
+    print()
+end

script/cli/init.lua

@@ -1,3 +1,8 @@
+if _G['HELP'] then
+    require 'cli.help'
+    os.exit(0, true)
+end
+
 if _G['VERSION'] then
     require 'cli.version'
     os.exit(0, true)

script/global.d.lua

@@ -109,3 +109,5 @@ THREAD_ID = 1
 CHECK_WORKER = ''
 
 QUIET = false
+
+HELP = false