Argument parser code

[drmikecrowe]

The code below (confession: heavily written by windsurf) can parse arguments for you. Includes comments on how to use.

Please suggest improvements we can make:

-- Function to parse job arguments based on expected definitions
-- Parses arguments passed to the Yazi plugin via `job.args`.
-- Handles:
-- 1. Default values defined in `expected_args`.
-- 2. Named arguments parsed by Yazi (e.g., `--clipboard` becomes `job.args.clipboard = true`).
--    These take precedence.
-- 3. Positional arguments that match an expected argument name or its aliases (e.g., `clipboard` or `-c`).
--    These are treated as boolean flags (set to true) if not already set by a named argument.
--
-- `job`: The job object passed to the plugin's entry function.
-- `expected_args`: A table defining the expected arguments.
--   Format: { arg_name = { default = default_value, aliases = {"alias1", "alias2"} }, ... }
--   `aliases` is optional.
--
-- Assumes `expected_args = { clipboard = { default = false, aliases = {"-c", "clipboard"} } }`.
--
-- | Command                           | `job.args` (Yazi)         | `parsed_args` (Output) | Notes                                                                  |
-- | :-------------------------------- | :------------------------ | :--------------------- | :--------------------------------------------------------------------- |
-- | `plugin what-size -- --clipboard` | `{ clipboard=true }`      | `{ clipboard=true }`   | Yazi parses `--clipboard`. Function uses it.                           |
-- | `plugin what-size -- clipboard`   | `{ args[1]="clipboard" }` | `{ clipboard=true }`   | Yazi parses positional. Function finds alias.                            |
-- | `plugin what-size -- -c`          | `{ args[1]="-c" }`        | `{ clipboard=true }`   | Yazi parses positional. Function finds alias.                            |
-- | `plugin what-size --clipboard`    | `{ }`                     | `{ clipboard=false }`  | Yazi *fails* to parse `--clipboard` due to following `--`. Default used. |
-- | `plugin what-size -c`             | `{ args[1]="-c" }`        | `{ clipboard=true }`   | Yazi parses positional `-c`. Function finds alias.                       |
-- | `plugin what-size clipboard`      | `{ args[1]="clipboard" }` | `{ clipboard=true }`   | Yazi parses positional `clipboard`. Function finds alias.                |
local function parse_args(job, expected_args)
  local parsed_args = {}

  ya.dbg("Parsing args:", { job_args = job.args, expected_args = expected_args })

  -- Set defaults
  for name, config in pairs(expected_args) do
    parsed_args[name] = config.default
  end

  ya.dbg("Args after defaults:", parsed_args)

  -- Check named arguments provided by Yazi (e.g., --clipboard -> job.args.clipboard = true)
  for name, config in pairs(expected_args) do
    -- Prioritize Yazi's named args parsing
    if job.args[name] ~= nil then
      ya.dbg("Found named arg:", { name = name, value = job.args[name], overriding_default = parsed_args[name] })
      parsed_args[name] = job.args[name] -- Handles --arg=value and --arg (sets to true)
    end
  end

  -- Check positional arguments for aliases or full names used as flags
  -- Handles cases like `plugin what-size -- clipboard` or `plugin what-size -- -c`
  for i, arg_val in ipairs(job.args) do
    ya.dbg("Checking positional arg:", { index = i, value = arg_val })
    for name, config in pairs(expected_args) do
      -- Check if the positional arg matches the name or an alias
      local matched = false
      if arg_val == name then
        ya.dbg("Positional arg matches name:", { name = name })
        matched = true
      elseif config.aliases then
        for _, alias in ipairs(config.aliases) do
          if arg_val == alias then
            ya.dbg("Positional arg matches alias:", { alias = alias, for_name = name })
            matched = true
            break
          end
        end
      end

      -- If matched and not already set by a named arg, set to true (treat as flag)
      if matched and job.args[name] == nil then
        ya.dbg("Setting flag from positional arg:", { name = name, value = true })
        parsed_args[name] = true
        goto next_positional -- Avoid matching the same positional arg for multiple expected args
      end
    end
    ::next_positional::
  end

  ya.dbg("Final parsed args:", parsed_args)
  return parsed_args
end