Named parameters in Lua

[tarleb]

I find the Lua functions sometimes slightly unpleasant to use, because they require to remember the correct order in which the function parameters have to be passed. I find parameter names often easier to remember than their order, so I wrote a small function that can modify any pandoc Lua function to make it usable with named parameters.

Lua allows to omit the parentheses of a function call if the argument is a table literal. I.e., instead of my_fun({a = 1}) one can write my_fun{ a = 1 }, and the method given here allows to used this feature. The below named_parameters function wraps functions, so that the parameters can be passed via their name mentioned in the documentation. In other words, instead of writing

pandoc.Link('interesting', 'https://example.org')

it becomes possible to write

pandoc.Link{
  content = 'interesting',
  target = 'https://example.org'
}

Using the original function is still possible: if more than one argument is given, or if a required parameter cannot be found in the arguments table, then the unwrapped function is called as it would be normally.

Each function has to be wrapped: pandoc.Link = named_parameters(pandoc.Link), which can be done for all functions in a module via

for name, value in pairs(pandoc) do
  if type(value) == 'function' then
    pandoc[name] = named_parameters(value)
  end
end

Definition for named_parameters:

local function named_parameters (fn)
  local docs = debug.getregistry()['HsLua docs']
  local fndoc = type(docs[fn]) == 'function' and docs[fn]() or docs[fn]
  if not fndoc then
    return fn
  end
  return function (...)
    local args = table.pack(...)
    -- The parameter table must be the only argument
    if args.n ~= 1 or type(args[1]) ~= 'table' then
      return fn(...)
    end

    local argtbl = args[1]

    local paramlist = {}
    for i, param in ipairs(fndoc.parameters) do
      local value = argtbl[param.name]
      if value or param.optional then
        paramlist[i] = value
      else
        -- a required parameter was not specified; bail out.
        return fn(...)
      end
    end
    return fn(table.unpack(paramlist))
  end
end

[bpj]

Synchronicity! The other day after having written a script which creates a lot of tables¹ I was going to ask if something like this was possible but decided not to because I was afraid that my wanting this feature was too niche.

Footnotes

1. From data data imported via YAML > yq > JSON > pandoc.pipe > pandoc.json. I should post my function for doing that! ↩