Update Command Lib

exp_commands/module/commands/authorities.lua

@@ -8,15 +8,15 @@ The default permission authorities controlled by the flags: admin_only, system_o
 /c require("modules/exp-commands").disable("my-command")
 ]]
 
-local Global = require("modules/exp_util/global")
+local Storage = require("modules/exp_util/storage")
 local Commands = require("modules/exp_commands")
 local add, allow, deny = Commands.add_permission_authority, Commands.status.success, Commands.status.unauthorised
 
-local permission_authorities = {}
+local authorities = {}
 
 local system_players = {}
 local disabled_commands = {}
-Global.register({
+Storage.register({
     system_players,
     disabled_commands,
 }, function(tbl)
@@ -25,13 +25,13 @@ Global.register({
 end)
 
 --- Allow a player access to system commands, use for debug purposes only
--- @tparam[opt] string player_name The name of the player to give access to, default is the current player
+--- @param player_name string? The name of the player to give access to, default is the current player
 function Commands.unlock_system_commands(player_name)
     system_players[player_name or game.player.name] = true
 end
 
 --- Remove access from system commands for a player, use for debug purposes only
--- @tparam[opt] string player_name The name of the player to give access to, default is the current player
+--- @param player_name string? The name of the player to give access to, default is the current player
 function Commands.lock_system_commands(player_name)
     system_players[player_name or game.player.name] = nil
 end
@@ -42,13 +42,13 @@ function Commands.get_system_command_players()
 end
 
 --- Stops a command from be used by any one
--- @tparam string command_name The name of the command to disable
+--- @param command_name string The name of the command to disable
 function Commands.disable(command_name)
     disabled_commands[command_name] = true
 end
 
 --- Allows a command to be used again after disable was used
--- @tparam string command_name The name of the command to enable
+--- @param command_name string The name of the command to enable
 function Commands.enable(command_name)
     disabled_commands[command_name] = nil
 end
@@ -59,7 +59,7 @@ function Commands.get_disabled_commands()
 end
 
 --- If a command has the flag "admin_only" then only admins can use the command#
-permission_authorities.admin_only =
+authorities.admin_only =
     add(function(player, command)
         if command.flags.admin_only and not player.admin then
             return deny{ "exp-commands-permissions.admin-only" }
@@ -69,7 +69,7 @@ permission_authorities.admin_only =
     end)
 
 --- If a command has the flag "system_only" then only rcon connections can use the command
-permission_authorities.system_only =
+authorities.system_only =
     add(function(player, command)
         if command.flags.system_only and not system_players[player.name] then
             return deny{ "exp-commands-permissions.system-only" }
@@ -79,8 +79,8 @@ permission_authorities.system_only =
     end)
 
 --- If Commands.disable was called then no one can use the command
-permission_authorities.disabled =
-    add(function(_, command)
+authorities.disabled =
+    add(function(_player, command)
         if disabled_commands[command.name] then
             return deny{ "exp-commands-permissions.disabled" }
         else
@@ -88,4 +88,4 @@ permission_authorities.disabled =
         end
     end)
 
-return permission_authorities
+return authorities

exp_commands/module/commands/data_types.lua

@@ -1,179 +0,0 @@
---[[-- Command Module - Default data types
-The default data types that are available to all commands
-
-@usage Adds parsers for:
-    boolean
-    string-options - options: array of strings
-    string-key - map: table of string keys and any values
-    string-max-length - maximum: number
-    number
-    integer
-    number-range - minimum: number, maximum: number
-    integer-range - minimum: number, maximum: number
-    player
-    player-online
-    player-alive
-    force
-    surface
-    color
-]]
-
-local ExpUtil = require("modules/exp_util")
-local Commands = require("modules/exp_commands")
-local add, parse = Commands.add_data_type, Commands.parse_data_type
-local valid, invalid = Commands.status.success, Commands.status.invalid_input
-
---- A boolean value where true is one of: yes, y, true, 1
-add("boolean", function(input)
-    input = input:lower()
-    if input == "yes"
-    or input == "y"
-    or input == "true"
-    or input == "1" then
-        return valid(true)
-    else
-        return valid(false)
-    end
-end)
-
---- A string, validation does nothing but it is a requirement
-add("string", function(input)
-    return valid(input)
-end)
-
---- A string from a set of options, takes one argument which is an array of options
-add("string-options", function(input, _, options)
-    local option = ExpUtil.auto_complete(options, input)
-    if option == nil then
-        return invalid{ "exp-commands-parse.string-options", table.concat(options, ", ") }
-    else
-        return valid(option)
-    end
-end)
-
---- A string which is the key of a table, takes one argument which is an map of string keys to values
-add("string-key", function(input, _, map)
-    local option = ExpUtil.auto_complete(map, input, true)
-    if option == nil then
-        return invalid{ "exp-commands-parse.string-options", table.concat(table.get_keys(map), ", ") }
-    else
-        return valid(option)
-    end
-end)
-
---- A string with a maximum length, takes one argument which is the maximum length of a string
-add("string-max-length", function(input, _, maximum)
-    if input:len() > maximum then
-        return invalid{ "exp-commands-parse.string-max-length", maximum }
-    else
-        return valid(input)
-    end
-end)
-
---- A number
-add("number", function(input)
-    local number = tonumber(input)
-    if number == nil then
-        return invalid{ "exp-commands-parse.number" }
-    else
-        return valid(number)
-    end
-end)
-
---- An integer, number which has been floored
-add("integer", function(input)
-    local number = tonumber(input)
-    if number == nil then
-        return invalid{ "exp-commands-parse.number" }
-    else
-        return valid(math.floor(number))
-    end
-end)
-
---- A number in a given inclusive range
-add("number-range", function(input, _, minimum, maximum)
-    local success, status, number = parse("number", input)
-    if not success then
-        return status, number
-    elseif number < minimum or number > maximum then
-        return invalid{ "exp-commands-parse.number-range", minimum, maximum }
-    else
-        return valid(number)
-    end
-end)
-
---- An integer in a given inclusive range
-add("integer-range", function(input, _, minimum, maximum)
-    local success, status, number = parse("integer", input)
-    if not success then
-        return status, number
-    elseif number < minimum or number > maximum then
-        return invalid{ "exp-commands-parse.number-range", minimum, maximum }
-    else
-        return valid(number)
-    end
-end)
-
---- A player who has joined the game at least once
-add("player", function(input)
-    local player = game.get_player(input)
-    if player == nil then
-        return invalid{ "exp-commands-parse.player", input }
-    else
-        return valid(player)
-    end
-end)
-
---- A player who is online
-add("player-online", function(input)
-    local success, status, player = parse("player", input)
-    if not success then
-        return status, player
-    elseif player.connected == false then
-        return invalid{ "exp-commands-parse.player-online" }
-    else
-        return valid(player)
-    end
-end)
-
---- A player who is online and alive
-add("player-alive", function(input)
-    local success, status, player = parse("player-online", input)
-    if not success then
-        return status, player
-    elseif player.character == nil or player.character.health <= 0 then
-        return invalid{ "exp-commands-parse.player-alive" }
-    else
-        return valid(player)
-    end
-end)
-
---- A force within the game
-add("force", function(input)
-    local force = game.forces[input]
-    if force == nil then
-        return invalid{ "exp-commands-parse.force" }
-    else
-        return valid(force)
-    end
-end)
-
---- A surface within the game
-add("surface", function(input)
-    local surface = game.surfaces[input]
-    if surface == nil then
-        return invalid{ "exp-commands-parse.surface" }
-    else
-        return valid(surface)
-    end
-end)
-
---- A name of a color from the predefined list, too many colours to use string-key
-add("color", function(input)
-    local color = ExpUtil.auto_complete(Commands.color, input, true)
-    if color == nil then
-        return invalid{ "exp-commands-parse.color" }
-    else
-        return valid(color)
-    end
-end)

exp_commands/module/commands/help.lua

@@ -2,23 +2,26 @@
 Game command to list and search all registered commands in a nice format
 @commands _system-ipc
 
-@usage-- Get all messages related to banning a player
+--- Get all messages related to banning a player
 /commands ban
 -- Get the second page of results
 /commands ban 2
 ]]
 
-local Global = require("modules/exp_util/global")
+local Storage = require("modules/exp_util/storage")
 local Commands = require("modules/exp_commands")
 
 local PAGE_SIZE = 5
 
 local search_cache = {}
-Global.register(search_cache, function(tbl)
+Storage.register(search_cache, function(tbl)
     search_cache = tbl
 end)
 
 --- Format commands into a strings across multiple pages
+--- @param commands { [string]: Commands.Command } The commands to split into pages
+--- @param page_size number The number of requests to show per page
+--- @return LocalisedString[][], number
 local function format_as_pages(commands, page_size)
     local pages = { {} }
     local page_length = 0
@@ -34,22 +37,37 @@ local function format_as_pages(commands, page_size)
             page_length = 1
         end
 
+        local description
+        if command.defined_at then
+            --- @cast command Commands.ExpCommand
+            description = { "", command.help_text[2], "- ", command.description }
+        else
+            description = command.description
+        end
+
         local aliases = #command.aliases > 0 and { "exp-commands-help.aliases", table.concat(command.aliases, ", ") } or ""
-        pages[current_page][page_length] = { "exp-commands-help.format", command.name, command.description, command.help, aliases }
+        pages[current_page][page_length] = { "exp-commands-help.format", command.name, description, aliases }
     end
 
     return pages, total
 end
 
-Commands.new("commands", "List and search all commands for a keyword")
+Commands.new("commands", { "exp-commands-help.description" })
     :add_aliases{ "chelp", "helpp" }
-    :argument("keyword", "string")
-    :optional("page", "integer")
-    :defaults{ page = 1 }
+    :optional("keyword", { "exp-commands-help.arg-keyword" }, Commands.types.string)
+    :optional("page", { "exp-commands-help.arg-page" }, Commands.types.integer)
+    :defaults{ keyword = "", page = 1 }
     :register(function(player, keyword, page)
+        -- Allow listing of all commands
+        local as_number = tonumber(keyword)
+        local cache = search_cache[player.index]
+        if as_number and page == 1 then
+            keyword = cache and cache.keyword or ""
+            page = as_number
+        end
+
         keyword = keyword:lower()
         local pages, found
-        local cache = search_cache[player.index]
         if cache and cache.keyword == keyword then
             -- Cached value found, no search is needed
             pages = cache.pages

exp_commands/module/commands/ipc.lua

@@ -2,7 +2,7 @@
 System command which sends an object to the clustorio api, should be used for debugging / echo commands
 @commands _system-ipc
 
-@usage-- Send a message on your custom channel, message is a json string
+--- Send a message on your custom channel, message is a json string
 /_ipc myChannel { "myProperty": "foo", "playerName": "Cooldude2606" }
 ]]
 
@@ -11,12 +11,12 @@ local Clustorio = require("modules/clusterio/api")
 
 local json_to_table = helpers.json_to_table
 
-Commands.new("_ipc", "Send an IPC message on the selected channel")
+Commands.new("_ipc", { "exp-commands-ipc.description" })
     :add_flags{ "system_only" }
     :enable_auto_concatenation()
-    :argument("channel", "string")
-    :argument("message", "string")
-    :register(function(_, channel, message)
+    :argument("channel", { "exp-commands-ipc.arg-channel" }, Commands.types.string)
+    :argument("message", { "exp-commands-ipc.arg-message" }, Commands.types.string)
+    :register(function(_player, channel, message)
         local tbl = json_to_table(message)
         if tbl == nil then
             return Commands.status.invalid_input("Invalid json string")

exp_commands/module/commands/rcon.lua

@@ -2,16 +2,16 @@
 System command which runs arbitrary code within a custom (not sandboxed) environment
 @commands _system-rcon
 
-@usage-- Get the names of all online players, using rcon
+--- Get the names of all online players, using rcon
 /_system-rcon local names = {}; for index, player in pairs(game.connected_player) do names[index] = player.name end; return names;
 
-@usage-- Get the names of all online players, using clustorio ipcs
+--- Get the names of all online players, using clustorio ipcs
 /_system-rcon local names = {}; for index, player in pairs(game.connected_player) do names[index] = player.name end; ipc("online-players", names);
 ]]
 
 local ExpUtil = require("modules/exp_util")
 local Async = require("modules/exp_util/async")
-local Global = require("modules/exp_util/global")
+local Storage = require("modules/exp_util/storage")
 local Commands = require("modules/exp_commands")
 local Clustorio = require("modules/clusterio/api")
 
@@ -27,7 +27,7 @@ rcon_statics.Async = Async
 rcon_statics.ExpUtil = ExpUtil
 rcon_statics.Commands = Commands
 rcon_statics.Clustorio = Clustorio
-rcon_statics.output = Commands.print
+rcon_statics.print = Commands.print
 rcon_statics.ipc = Clustorio.send_json
 --- @diagnostic enable: name-style-check
 
@@ -45,7 +45,7 @@ function rcon_callbacks.entity(player) return player and player.selected end
 function rcon_callbacks.tile(player) return player and player.surface.get_tile(player.position) end
 
 --- The rcon env is saved between command runs to prevent desyncs
-Global.register(rcon_env, function(tbl)
+Storage.register(rcon_env, function(tbl)
     rcon_env = setmetatable(tbl, { __index = rcon_statics })
 end)
 
@@ -61,10 +61,10 @@ function Commands.add_rcon_callback(name, callback)
     rcon_callbacks[name] = callback
 end
 
-Commands.new("_rcon", "Execute arbitrary code within a custom environment")
+Commands.new("_rcon", { "exp-commands-rcon.description" })
     :add_flags{ "system_only" }
     :enable_auto_concatenation()
-    :argument("invocation", "string")
+    :argument("invocation", { "exp-commands-rcon.arg-invocation" }, Commands.types.string)
     :register(function(player, invocation_string)
         -- Construct the environment the command will run within
         local env = setmetatable({}, { __index = rcon_env, __newindex = rcon_env })
@@ -80,8 +80,7 @@ Commands.new("_rcon", "Execute arbitrary code within a custom environment")
         else
             local success, rtn = xpcall(invocation, debug.traceback)
             if success == false then
-                local err = rtn:gsub("%.%.%..-/temp/currently%-playing/", "")
-                return Commands.status.error(err)
+                return Commands.status.error(rtn)
             else
                 return Commands.status.success(rtn)
             end

exp_commands/module/commands/sudo.lua

@@ -2,20 +2,21 @@
 System command to execute a command as another player using their permissions (except for permissions group actions)
 @commands _system-sudo
 
-@usage-- Run the example command as another player
+--- Run the example command as another player
 -- As Cooldude2606: /repeat 5
 /_system-sudo Cooldude2606 repeat 5
 ]]
 
 local Commands = require("modules/exp_commands")
 
-Commands.new("_sudo", "Run a command as another player")
+Commands.new("_sudo", { "exp-commands-sudo.description" })
     :add_flags{ "system_only" }
     :enable_auto_concatenation()
-    :argument("player", "player")
-    :argument("command", "string-key", Commands.registered_commands)
-    :argument("arguments", "string")
-    :register(function(_, player, command, parameter)
+    :argument("player", { "exp-commands-sudo.arg-player" }, Commands.types.player)
+    :argument("command", { "exp-commands-sudo.arg-command" }, Commands.types.string_key(Commands.registered_commands))
+    :argument("arguments", { "exp-commands-sudo.arg-arguments" }, Commands.types.string)
+    :register(function(_player, player, command, parameter)
+        --- @diagnostic disable-next-line: invisible
         return Commands._event_handler{
             name = command.name,
             tick = game.tick,

exp_commands/module/commands/types.lua

@@ -0,0 +1,206 @@
+--[[-- Command Module - Default data types
+The default data types that are available to all commands
+
+Adds parsers for:
+    boolean
+    string_options - options: array of strings
+    string_key - map: table of string keys and any values
+    string_max_length - maximum: number
+    number
+    integer
+    number_range - minimum: number, maximum: number
+    integer_range - minimum: number, maximum: number
+    player
+    player_online
+    player_alive
+    force
+    surface
+    color
+]]
+
+local ExpUtil = require("modules/exp_util")
+local Commands = require("modules/exp_commands")
+local add, parse = Commands.add_data_type, Commands.parse_input
+local valid, invalid = Commands.status.success, Commands.status.invalid_input
+
+--- A boolean value where true is one of: yes, y, true, 1
+add("boolean", function(input)
+    input = input:lower()
+    if input == "yes"
+    or input == "y"
+    or input == "true"
+    or input == "1" then
+        return valid(true)
+    else
+        return valid(false)
+    end
+end)
+
+--- A string, validation does nothing but it is a requirement
+--- @type Commands.InputParser
+add("string", function(input)
+    return valid(input)
+end)
+
+--- A string from a set of options, takes one argument which is an array of options
+--- @param options string[] The options which can be selected
+--- @return Commands.InputParser
+add("string_array", function(options)
+    return function(input)
+        local option = ExpUtil.auto_complete(options, input)
+        if option == nil then
+            return invalid{ "exp-commands-parse.string-options", table.concat(options, ", ") }
+        else
+            return valid(option)
+        end
+    end
+end)
+
+--- A string which is the key of a table, takes one argument which is an map of string keys to values
+--- @param map { [string]: any } The options which can be selected
+--- @return Commands.InputParser
+add("string_key", function(map)
+    return function(input)
+        local option = ExpUtil.auto_complete(map, input, true)
+        if option == nil then
+            return invalid{ "exp-commands-parse.string-options", table.concat(table.get_keys(map), ", ") }
+        else
+            return valid(option)
+        end
+    end
+end)
+
+--- A string with a maximum length, takes one argument which is the maximum length of a string
+--- @param maximum number The maximum length of the input
+--- @return Commands.InputParser
+add("string_max_length", function(maximum)
+    return function(input)
+        if input:len() > maximum then
+            return invalid{ "exp-commands-parse.string-max-length", maximum }
+        else
+            return valid(input)
+        end
+    end
+end)
+
+--- A number
+add("number", function(input)
+    local number = tonumber(input)
+    if number == nil then
+        return invalid{ "exp-commands-parse.number" }
+    else
+        return valid(number)
+    end
+end)
+
+--- An integer, number which has been floored
+add("integer", function(input)
+    local number = tonumber(input)
+    if number == nil then
+        return invalid{ "exp-commands-parse.number" }
+    else
+        return valid(math.floor(number))
+    end
+end)
+
+--- A number in a given inclusive range
+--- @param minimum number The minimum of the allowed range, inclusive
+--- @param maximum number The maximum of the allowed range, inclusive
+--- @return Commands.InputParser
+add("number_range", function(minimum, maximum)
+    local parser_number = Commands.types.number
+    return function(input, player)
+        local success, status, result = parse(input, player, parser_number)
+        if not success then
+            return status, result
+        elseif result < minimum or result > maximum then
+            return invalid{ "exp-commands-parse.number-range", minimum, maximum }
+        else
+            return valid(result)
+        end
+    end
+end)
+
+--- An integer in a given inclusive range
+--- @param minimum number The minimum of the allowed range, inclusive
+--- @param maximum number The maximum of the allowed range, inclusive
+--- @return Commands.InputParser
+add("integer_range", function(minimum, maximum)
+    local parser_integer = Commands.types.integer
+    return function(input, player)
+        local success, status, result = parse(input, player, parser_integer)
+        if not success then
+            return status, result
+        elseif result < minimum or result > maximum then
+            return invalid{ "exp-commands-parse.number-range", minimum, maximum }
+        else
+            return valid(result)
+        end
+    end
+end)
+
+--- A player who has joined the game at least once
+add("player", function(input)
+    local player = game.get_player(input)
+    if player == nil then
+        return invalid{ "exp-commands-parse.player", input }
+    else
+        return valid(player)
+    end
+end)
+
+--- A player who is online
+add("player_online", function(input, player)
+    local success, status, result = parse(input, player, Commands.types.player)
+    --- @cast result LuaPlayer
+    if not success then
+        return status, result
+    elseif result.connected == false then
+        return invalid{ "exp-commands-parse.player-online" }
+    else
+        return valid(result)
+    end
+end)
+
+--- A player who is online and alive
+add("player_alive", function(input, player)
+    local success, status, result = parse(input, player, Commands.types.player_online)
+    --- @cast result LuaPlayer
+    if not success then
+        return status, result
+    elseif result.character == nil or result.character.health <= 0 then
+        return invalid{ "exp-commands-parse.player-alive" }
+    else
+        return valid(result)
+    end
+end)
+
+--- A force within the game
+add("force", function(input)
+    local force = game.forces[input]
+    if force == nil then
+        return invalid{ "exp-commands-parse.force" }
+    else
+        return valid(force)
+    end
+end)
+
+--- A surface within the game
+add("surface", function(input)
+    local surface = game.surfaces[input]
+    if surface == nil then
+        return invalid{ "exp-commands-parse.surface" }
+    else
+        return valid(surface)
+    end
+end)
+
+--- A name of a color from the predefined list, too many colours to use string-key
+add("color", function(input)
+    local color = ExpUtil.auto_complete(Commands.color, input, true)
+    if color == nil then
+        return invalid{ "exp-commands-parse.color" }
+    else
+        return valid(color)
+    end
+end)