cliargs.lua

local cli = {}

-- ------- --
-- Helpers --
-- ------- --
local expand = function(str, size, fill)
  if not fill then fill = ' ' end

  local out = str

  for i=0,size - #str do
    out = out .. fill
  end

  return out
end

local split = function(str, pat)
  local t = {}
  local fpat = "(.-)" .. pat
  local last_end = 1
  local s, e, cap = str:find(fpat, 1)
  while s do
    if s ~= 1 or cap ~= "" then
  table.insert(t,cap)
    end
    last_end = e+1
    s, e, cap = str:find(fpat, last_end)
  end
  if last_end <= #str then
    cap = str:sub(last_end)
    table.insert(t, cap)
  end
  return t
end

local join = function(t, delim)
  out = ""
  i = 0
  for _,item in pairs(t) do
    out = item .. delim
  end
  out = out:sub(0, #out - #delim)
  return out
end

local delimit = function(str, size, pad)
  if not pad then pad = 0 end

  local out = ""
  local words = split(str, ' ')

  local offset = 0
  for word_idx,word in pairs(words) do
    out = out .. word .. ' '
    offset = offset + #word
    if offset > size and word_idx ~= #words then
      out = out .. '\n'
      for i=0,pad do out = out .. ' '; end
      offset = 0
    end
  end

  return out
end

-- -------- --
-- CLI Main --
-- -------- --

--- Creates a new instance of the CLI arguments parser and consumes `arg`.
---
--- **Note**: you don't need to invoke this directly as it is automatically
--- done when you `require("cli")`.
---
--- ### Parameters
--- 1. **name**: The name of the application, used in usage and help listings
function cli:new(name)
  local o = {}
  setmetatable(o, { __index = self })
  self.__index = self

  o.name = name
  o.required = required_args or {}
  o.optional = optional_args or {}
  o.args = arg

  o.colsz = { 20, 45 }

  return o
end

function cli:error(msg)
  print(self.name .. ": error: " .. msg .. '; re-run with --help for usage.')
  return false
end

--- Assigns the name of the program which will be used for logging.
function cli:set_name(name)
  self.name = name
end

--- Defines a required argument. 
--- Required arguments have no special notation and are order-sensitive. 
--- *Note:* if `@ref` is omitted, the value will be stored in `args[@key]`.  
--- *Aliases: `add_argument`*
---
--- ### Parameters
--- 1. **key**: the argument's "name" that will be displayed to the user
--- 1. **desc**: a description of the argument
--- 1. **ref**: optional; the table key that will be used to hold the value of this argument
---
--- ### Usage example
--- The following will parse the argument (if specified) and set its value in `args["root_path"]`:  
--- `cli:add_arg("root", "path to where root scripts can be found", "root_path")`  
function cli:add_arg(key, desc, ref)
  if not ref then ref = key end
  table.insert(self.required, { key = key, desc = desc, ref = ref })
end

--- Defines an optional argument.
--- Optional arguments can use 3 different notations, and can accept a value.  
--- *Aliases: `add_option`*
---
--- ### Parameters
--- 1. **key**: the argument identifier, can be either `-key`, or `-key, --expanded-key`:  
--- if the first notation is used then a value can be defined after a space (`'-key VALUE'`),  
--- if the 2nd notation is used then a value can be defined after an `=` (`'key, --expanded-key=VALUE'`).
--- 1. **desc**: a description for the argument to be shown in --help
--- 1. **ref**: *optional*; override where the value will be stored, @see cli:add_arg
--- 1. **default**: *optional*; specify a default value (the default is "")
---
--- ### Usage example
--- The following option will be stored in `args["i"]` with a default value of `my_file.txt`:  
--- `cli:add_option("-i, --input=FILE", "path to the input file", nil, "my_file.txt")`
function cli:add_opt(key, desc, ref, default)
  if not ref then
    if key:find('%-%-') == 1 then
      ref = key:gsub("(%-%-)", ""):gsub("(=.*)", "")
    else
      ref = string.gsub(key, '[%W]', ''):sub(0,1)
    end
  end

  local entry = { 
    key = key,
    expanded_key = "",
    ref = ref,
    value = "",
    desc = desc,
    default = default == nil and "" or default
  }

  -- parameterize the key if needed, possible variations:
  -- 1. -key
  -- 2. -key VALUE
  -- 3. -key, --expanded
  -- 4. -key, --expanded=VALUE

  -- -a, --argument[=VALUE] was passed
  if key:find(',') then
    local k,ek = unpack( split(key, ',') )
            ek = ek:gsub(' ', '')
    if ek:find('=') then
      ek,v = unpack( split(ek,'=') )
         v = v:gsub(' ', '')

      entry.value = v
    end

    entry.key = k
    entry.expanded_key = ek
  -- --argument[=VALUE] was passed
  elseif key:find('%-%-') == 1 then
    if key:find('=') then
      k,v = unpack( split(key,'=') )
        v = v:gsub(' ', '')

      entry.value = v
      key = k
    end
    entry.key = ""-- key
    entry.expanded_key = key
  -- -a[ VALUE] was passed
  elseif key:find(' ') then
    local k,v = unpack( split(key, ' ') )
          k = k:gsub(' ', '')
          v = v:gsub(' ', '')

    entry.key, entry.value = k, v
  end

  table.insert(self.optional, entry)
end

--- Define a flag argument (on/off). This is a convenience helper for cli.add_opt(). 
--- See cli.add_opt() for more information.
---
--- ### Parameters
-- 1. **key**: the argument's key
-- 1. **desc**: a description of the argument to be displayed in the help listing
-- 1. **ref**: optionally override where the key which will hold the value
function cli:add_flag(key, desc, ref)
  return self:add_opt(key, desc, ref, false)
end

function cli:locate_entry(key)
  -- strip the leading -- from the key if it's an expanded one
  if key:find('%-%-') == 1 and key:find('=') then
    key = split(key, '=')[1]
  end

  for _,entry in ipairs(self.optional) do
    if entry.key == key then
      return entry,false
    elseif entry.expanded_key == key then
      return entry,true
    end
  end

  return nil, nil
end

--- Parses the arguments found in #arg and returns a table with the populated values.
--- ### Returns
--- 1. a table containing the keys specified when the arguments were defined along with the parsed values.
function cli:parse_args(dump)

  -- missing any required arguments?
  if #self.args < #self.required then
    self:error("missing arguments, at least " .. #self.required .. " argument(s) must be specified")
    self:print_usage()
    return false
  end

  -- starts with --help? display the help listing and abort!
  if self.args[1] and self.args[1] == "--help" then
    return self:print_help()
  end

  -- print("Received " .. #self.args .. " arguments, required: " .. #self.required)

  local args = {} -- returned set

  -- set up defaults
  for _,entry in ipairs(self.optional) do
    args[ entry.ref ] = entry.default
  end

  local req_idx = 1

  for arg_idx, arg in ipairs(arg) do
    repeat
      if skip then
        skip = false
        break
      end

      local entry, uses_expanded = self:locate_entry(arg)

      -- if it's an optional argument (starts with '-'), it must be listed
      if arg:find('-') == 1 and not entry then
        return self:error("unknown option " .. arg)
      end

      -- it's a required argument
      if not entry then
        -- or it's one too many arguments
        if not self.required[req_idx] then
          return self:error("too many arguments! Can't map '" .. arg .. "'")
        end

        args[ self.required[req_idx].ref ] = arg
        req_idx = req_idx + 1
      
      -- it's an optional argument, determine its type and which notation it uses
      else
        local arg_val = nil

        -- it's a flag, using either -f --f notations
        if #entry.value == 0 then
          arg_val = true

        -- an option using the -option VALUE notation:
        elseif not uses_expanded then
          if #self.args == arg_idx then
            return self:error("missing argument value in '" .. entry.key .. " " .. entry.value .. "'")
          else
            arg_val = self.args[arg_idx+1]
            skip = true
          end

        -- an option using the --option=VALUE notation
        else 
          if not arg:find('=') then
            return 
              self:error("missing argument value in '" .. entry.expanded_key .. 
              "', value must be specified using: " .. entry.expanded_key .. "=" .. entry.value)
          end

          -- local v = split(arg, '=')
          arg_val = arg:sub(#entry.expanded_key+2,#arg)
          -- for i=1,#v do
            -- arg_val = v[i] .. "="
          -- end
          -- table.remove(arg_val, 1)
          -- arg_val = join(arg_val, '=')
          -- print('joined value: ' .. arg_val)
        end

        args[ entry.ref ] = arg_val
      end

    until true
  end

  if req_idx - 1 < #self.required then
    return self:error("missing required arguments")
  end

  if dump then
    for k,v in pairs(args) do print("  " .. k .. " => " .. tostring(v)) end
  end

  return args
end

function cli:print_usage()
  -- print the USAGE heading
  local msg = "Usage: " .. self.name
  if self.optional and #self.optional > 0 then
    msg = msg .. " [OPTIONS] "
  end
  if self.required and #self.required > 0 then
    for _,entry in ipairs(self.required) do
      local arg_key, arg_desc, arg_name =
            entry.key, entry.desc, entry.ref

      msg = msg .. " " .. arg_key .. " "
    end
  end

  print(msg)
end


function cli:print_help()
  self:print_usage()

  local keysz = 20
  local msg = ""

  if self.required and #self.required > 0 then
    msg = msg .. "\nRequired arguments: \n"

    for _,entry in ipairs(self.required) do
      local arg_key, arg_desc, arg_name =
            entry.key, entry.desc, entry.ref

      msg = msg ..
            "  " .. expand(arg_key, keysz) ..
            arg_desc .. "\n"
    end
  end

  if self.optional and #self.optional > 0 then
    msg = msg .. "\nOptional arguments: \n"

    for _,entry in ipairs(self.optional) do
      local arg_key, arg_desc, arg_name, arg_default, arg_ph =
            entry.key, entry.desc, entry.ref, entry.default, entry.value

      if arg_default then
        arg_desc = arg_desc .. " (default: " .. arg_default .. ")"
      end

      local separator = " "
      if #entry.expanded_key > 0 then
        arg_key = (#arg_key > 0 and arg_key .. ", " or "") .. entry.expanded_key
        separator = #entry.value > 0 and "=" or ""
      end
      if arg_ph then
        arg_key = arg_key .. separator .. arg_ph
      end

      msg = msg .. "  " ..
        expand(arg_key, self.colsz[1]) ..
        delimit(arg_desc, self.colsz[2], self.colsz[1] + 2 --[[ margin ]]) .. '\n'
    end
  end

  print(msg)
end

--- Sets the amount of space allocated to the argument keys and descriptions in the help listing.
--- The sizes are used for wrapping long argument keys and descriptions.
--- ### Parameters
--- 1. **key_cols**: the number of columns assigned to the argument keys (default: 20)
--- 1. **desc_cols**: the number of columns assigned to the argument descriptions (default: 45)
function cli:set_colsz(key_cols, desc_cols)
  self.colsz = { key_cols or self.colsz[1], desc_cols or self.colsz[2] }
end

cli.version = "1.1-0"

-- aliases
cli.add_argument = cli.add_arg
cli.add_option = cli.add_opt

return cli:new("")