Module:CLI

Documentation for this module may be created at Module:CLI/doc

--  <nowiki>
--- CLI command-line generator for development & debugging tools.
--  This module is used to execute command lines containing command line
--  arguments. Command line strings are quoted similarly to shell quotes
--  in Unix and Windows command lines. Unlike Unix, single quoting is
--  supported.
--  
--  The command line string supports these environment variables:
--   * `%PATH%` - calling module in the Lua stack.
--   * `%OS%` - Lua version (5.1 for the foreseeable future).
--  
--  This module is supplied arguments in the Scribunto console. The
--  general command synopsis (in man command format) is:
--  {{#tag:pre|p "<command> [<arg>] [--flag [ <value>]]"}}
--  The help command will output a command synopsis in the [man command
--  format](https://linux.die.net/man/7/man-pages).
--  
--  This module supports the following syntax:
--   * Positional arguments (space-delimited): `one two three`
--   * Boolean command flags: `-one`, `--one`
--   * Variable command flags: `--one "numero uno"`
--   * Quoted arguments: `one "numero dos"`
--   * Variable assignments: `one="one"`
--   * Escapes: quotes as `\\"` or `\\'` and spaces as `\\ `
--  
--  The first positional argument is recognised as a command word and is
--  executed within the command object. The command sends its output to
--  the [[Lua templating/Debug console|Scribunto console]] using
--  @{mw.log}. Note that command flags must be placed after positional
--  arguments to work.
--  
--  The command API prints the CLI usage if the `help` command word or
--  `--help`/`-help` flag is supplied. When a command is combined with
--  `--help` or `-help`, or a command word is defined as a second
--  positional argument, the help statement is tailored to the specific
--  command, its usage and options.
--  
--  @release            beta
--  @classmod           CommandLine
--  @pragma             ulist
--  @pragma             noluaref
--  @author             [[User:8nml|8nml]]
--  @attribution        [[github:laurent|@laurent]] ([[github:laurent/massren|Github]])
--  @demo               [[Module:Docbunto/cli]]
--  @see                [https://stackoverflow.com/a/46973603 Original code (Go)].
local CommandLine = {}

--  Module dependencies.
local util = require 'libraryUtil'
local _VERSION = _VERSION
local pairs, ipairs, next, rawget, error = pairs, ipairs, next, rawget, error
local tostring, tonumber, type, setmetatable = tostring, tonumber, type, setmetatable
local log, traceback, remove, insert = mw.log, debug.traceback, table.remove, table.insert

--  Module variables.
local CLI_INTERPRETER = 'LuaSandbox'
local CLI_STATE_START = 'start'
local CLI_STATE_QUOTE = 'quote'
local CLI_STATE_ARG = 'argument'

--- Converts a Lua string representation of a primitive.
--  @param              {string} str Unquoted string, or Lua primitive
--                      as a string representation.
--  @return             {number|boolean|string} Lua primitive that
--                      corresponds to string, or origiinal string.
local function tovalue(str)
    if tonumber(str) then
        return tonumber(str)
    elseif str == 'true' then
        return true
    elseif str == 'false' then
        return false
    elseif str == 'nil' then
        return nil
    else
        return str
    end
end

--- Adds a metatable for indexing CLI options table by name.
local function options_metatable(t, k)
    for _, opt in ipairs(t) do
        if k == opt.name or (opt.alias and k == opt.alias) then
            return opt
        end
    end
    return rawget(t, k)
end

--- Synopsis generator function.
--  @param              {table} options Array of option names or option
--                      configurations.
--  @param              {table} config Command line configuration.
--  @return             {string} Command line sypnosis.
local function synopsis(options, config, word)
    local buffer, optconf = {}

    table.insert(buffer, '    p "')
    table.insert(buffer, word)
    table.insert(buffer, #options ~= 0 and ' ' or '')

    for index, opt in ipairs(options) do
        optconf = type(opt) == 'table' and opt or config.options[opt]
        table.insert(buffer, index ~= 1 and ' ' or '')
        table.insert(buffer, optconf.required and (optconf.alias and '{' or '') or '[')
        table.insert(buffer, type(optconf.name) == 'number'
            and ('<' .. (optconf.alias or tostring(optconf.name)) .. '>')
            or  (
                    '--' .. optconf.name ..
                    (optconf.type and ' ' or '') ..
                    (optconf.type and ('<'.. optconf.type ..'>') or '')
                )
        )
        table.insert(buffer, optconf.alias and ' | ' or '')
        table.insert(buffer, optconf.alias
            and (
                (#optconf.alias == 1 and '-' or '--') ..
                optconf.alias ..
                (optconf.type and ' ' or '') ..
                (optconf.type and ('<'.. optconf.type ..'>') or '')
            )
            or  ''
        )
        table.insert(buffer, optconf.required and (optconf.alias and '}' or '') or ']')
    end
    table.insert(buffer, '"')

    return table.concat(buffer)
end

--- Okay, what do **YOU** think this does?
local function padright(str, len, char)
    char = char or ' '
    return str .. string.rep(char, len - #str)
end

--- Command line function generator.
--  @param              {table} config
--                      Command line configuration.
--  @param              {string} config.description
--                      Interfaced module description.
--  @param              {table} config.commands
--                      Object containing command methods.
--  @param              {table} config.words
--                      Configuration object with command methods as
--                      keys. Each table contains the following
--                      configuration table fields:
--                       ** `description` Description of command.
--                      (string)
--                       ** `options` Dependent options for command.
--                      (table)
--  @param[opt]         {table} config.options
--                      Command line options configuration. This option
--                      is defined as an array with option configuration
--                      tables as elements. Each table contains the
--                      following configuration table fields:
--                       ** `name` Name of option. Accepts number when
--                      the option is a positional argument. (string
--                      or number)
--                       ** `alias` Alias for option. (string; optional)
--                       ** `description` Description of option. (string)
--                       ** `type` Type of option. Omitted for boolean
--                      flags. (optional)
--                       ** `required` Whether the argument or flag is
--                      not optional. Default: `false`. (boolean;
--                      optional)
--  @return             {function} Command line handler. Help commands
--                      will produce a command synopsis detailing usage,
--                      a list of commands and a list of options. Other
--                      commands will be executed if a corresponding
--                      method is present in `config.commands`.
function CommandLine:new(config)
    util.checkType('new', 1, config, 'table')
    util.checkTypeForNamedArg('new', 'description', config.description, 'string')
    util.checkTypeForNamedArg('new', 'commands', config.commands, 'table')
    util.checkTypeForNamedArg('new', 'words', config.words, 'table')
    util.checkTypeForNamedArg('new', 'options', config.options, 'table', true)
    setmetatable(config.options, { __index = options_metatable })

    return function(command)
        local args, argv, argc = self:parse(command, config)
        local word = remove(args, 1)

        if ((word == 'help') or args.help) then
            if
                args[1] or
                (word and word ~= 'help' and args.help == true) or
                type(args.help) == 'string'
            then
                local command; if word == 'help' then
                    command = args[1]
                elseif type(args.help) == 'boolean' then
                    command = word
                elseif type(args.help) == 'string' then
                    command = args.help
                end

                if not command or not config.words[command] then
                    log('"' .. tostring(command) .. '" is not a recognised command. Printing help..')
                    log('')
                    CommandLine:new(config) 'help'
                    return
                end

                log(tostring(command) .. ': ' .. config.words[command].description)

                if not config.words[command].options then
                    return
                end
                log('')

                log('Command sypnosis:')
                log(synopsis(config.words[command].options, config, command))
                log('')

                log('Command line options available in "' .. tostring(command) .. '":')
                for _, opt in ipairs(config.words[command].options) do
                    log(
                        '    ' ..
                        padright(
                            tostring(config.options[opt].name) ..
                            (config.options[opt].alias and (' | ' .. config.options[opt].alias) or ''),
                            24
                        ) ..
                        ': ' ..
                        config.options[opt].description
                    )
                end

            else
                log(config.description)
                log('')

                log('General command line sypnosis:')
                log(synopsis(config.options, config, '<command>'))
                log('')

                log('Commands available in ' .. args[0] .. ':')
                for word, wordconf in pairs(config.words) do
                    log('    ' .. padright(tostring(word), 24) .. ': ' .. wordconf.description)
                end
                log('')

                log('Command line options available in ' .. args[0] .. ':')
                for _, optconf in ipairs(config.options) do
                    log(
                        '    ' ..
                        padright(
                            tostring(optconf.name) ..
                            (optconf.alias and (' | ' .. optconf.alias) or ''),
                            24
                        ) ..
                        ': ' ..
                        optconf.description
                    )
                end
            end

        elseif word and config.commands[word] then
            return config.commands[word](args)
        else
            log('"' .. tostring(word) .. '" is not a recognised command. Printing help..')
            log('')
            CommandLine:new(config) 'help'
        end
    end
end

--- Command line shell quote parser.
--  @function           CommandLine:parse
--  @param              {string} command Command line to be parsed.
--  @param[opt]         {table} config Command line configuration.
--  @error[377]         {string} "empty command line"
--  @error[382]         {string} "unterminated quote in command line:
--                      $command"
--  @error[424]         {string} "unconfigured argument or flag "$arg"
--                      in command line"
--  @return             {table} Map of processed arguments. The array,
--                      or sequential keys in the map list positional
--                      arguments in the command line. The flags in
--                      the command line are converted into named
--                      arguments. Metadata fields:
--                       * `0` The CLI module name or context.
--                       * `"PATH"` The CLI module name or context.
--                       * `-1` The Lua interpreter Scribunto uses.
--                       * `-2` The Lua version Scribunto runs.
--                       * `"OS"` The Lua version Scribunto runs.
--  @return             {table} Array of processed arguments. Includes
--                      the metadata fields listed above.
--  @return             {table} Number of arguments passed by the user,
--                      counted like the C or C++ `argc` convention.
function CommandLine:parse(command, config)
    util.checkType('parse', 1, command, 'string')
    util.checkType('parse', 2, config, 'table', true)
    config = config or { options = {} }

    local args = {}
    local argv = {}
    local argc = 0

    -- Initialise stack variables.
    local state = CLI_STATE_START
    local stack = ''
    local quote = '"'
    local escape_next = true

    -- Attach version, interpreter & module path to argument value array.
    argv[-2] = _VERSION
    argv[-1] = CLI_INTERPRETER
    argv[0] = mw.title.getCurrentTitle().prefixedText
    for modulename in (traceback() or ''):gmatch('\n\t([^(%[][^:\n]+:[^:\n]+)') do
        if not modulename:find(':CLI%f[%z: ]') then
            argv[0] = modulename:gsub('(input):%d+$', '%1')
            break
        end
    end

    -- Attach version, interpreter and module path to argument map array.
    args[-1] = argv[-1]
    args[0] = argv[0]
    args.PATH = argv[0]
    args.OS = argv[-2]

    -- Replace %PATH% with the module name.
    command = command:gsub('%%PATH%%', argv[0])

    -- Replace %OS% with the Lua version.
    command = command:gsub('%%OS%%', argv[-2])

    -- Parse command chunks.
    local cmd_length = 0
    for chunk in command:gmatch('.') do
        cmd_length = cmd_length + 1
        -- Shell quote parsing.
        if state == CLI_STATE_QUOTE then
            -- Reset the stack and state.
            if chunk == quote then
                insert(argv, stack)
                stack = ''
                state = CLI_STATE_START
            else
                stack = stack .. chunk
            end

        elseif escape_next then
            stack = stack .. chunk
            escape_next = false

        elseif chunk == '\\' then
            escape_next = true

        elseif chunk == '"' or chunk == "'" then
            state = CLI_STATE_QUOTE
            quote = chunk

        elseif state == CLI_STATE_ARG then
            if chunk == ' ' or chunk == '\t' then
                insert(argv, stack)
                stack = ''
                state = CLI_STATE_START
            else
                stack = stack .. chunk
                if #command == cmd_length then
                    insert(argv, stack)
                end
            end

        elseif chunk ~= ' ' and chunk ~= '\t' then
            state = CLI_STATE_ARG
            stack = stack .. chunk
        end
    end

    -- Check for empty command line.
    local argc = #argv
    if argc == 0 then
        error('empty command line')
    end

    -- Check for unterminated strings.
    if state == CLI_STATE_QUOTE then
        error('unterminated quote in command line: ' .. command)
    end

    -- Command line argument parsing.
    for index, arg in ipairs(argv) do
        argv[index] = tovalue(arg)
    end

    for index, arg in ipairs(argv) do
        -- Command line flag parsing.
        if type(arg) == 'string' and arg:find('^%-') then
            arg = arg:gsub('^%-%-?', '')
            if type(argv[index + 1]) == 'string' and not argv[index + 1]:find('^%-') then
                index = index + 1
                args[arg] = argv[index]
            else
                args[arg] = true
            end

        -- Command line variable parsing.
        elseif type(arg) == 'string' and arg:find('%S=%S') then
            local key = arg:match('^[^=]+')
            key = tonumber(key) or key
            local val = arg:match('[^=]+$')
            args[key] = val
            _G[key] = val

        -- Positional command line arguments.
        else
            insert(args, arg)
        end
    end

    -- Check for undefined options when configured.
    for arg in pairs(args) do
        if
            next(config.options) and
            (args[1] ~= 'help' and arg ~= 'help') and
            (arg ~= 'PATH' and arg ~= 'OS') and
            ( type(arg) ~= 'number' or (arg >= 2) ) and
            not config.options[type(arg) == 'number' and (arg - 1) or arg]
        then
            error('unconfigured argument or flag "' .. (type(arg) == 'number' and tostring(arg - 1) or arg) .. '" in command line')
        end
    end

    -- Alias translation for configured argument options.
    if type(config) == 'table' and type(config.options) == 'table' then
        for _, optconf in ipairs(config.options) do
            if optconf.alias and args[optconf.alias] then
                args[optconf.name] = args[optconf.alias]
                remove(args, optconf.alias)
            end
        end
    end

    return args, argv, argc
end

return CommandLine
--  </nowiki>