---@alias core.cli.flag_type
---|>'"empty"'   # Does not needs a value
---| '"number"'  # A numerical value
---| '"string"'  # Any string value
---| '"boolean"' # 0,1,false,true
---| '"list"'    # Comma separated values

---Representation of a command line flag.
---@class core.cli.flag
---Long name of the flag eg: my-flag for --my-flag
---@field name string
---Short name eg: m for -m
---@field short_name string
---Description used for the flag when running `app help mycommand`
---@field description string
---Data type of the flag if an argument/value can be given to it
---@field type? core.cli.flag_type
---Value assigned to the flag
---@field value? number|string|boolean|table

---Representation of a command line subcommand.
---@class core.cli.command
---Subcommand name invoked with `app mycommand`
---@field command string
---Description used for the command when running `app help`
---@field description string
---Optional more detailed description that shows how to use the command
---@field long_description? string
---Description of the arguments printed on command help.
---@field arguments? table<string,string>
---Single line brief of using the command, eg: [options] [<argument>]
---@field usage? string
---The minimum amount of arguments required for the command
---@field min_arguments? integer
---The maximum amount of arguments required for the command where -1 is any
---@field max_arguments? integer
---Flag true by default which causes the editor to not launch when command is executed
---@field exit_editor? boolean
---Optional list of flags that can be used as part of the command
---@field flags? core.cli.flag[]
---Optional list of subcommands that belong to the parent subcommand
---@field subcommands? core.cli.command[]
---Function called when the command is invoked by the user
---@field execute? fun(flags:core.cli.flag[], arguments:string[])

---@class core.cli
---Application name
---@field app_name string
---Application version
---@field app_version string
---Application description
---@field app_description string
---List of registered commands
---@field commands table<string,core.cli.command>

---Add a new command to the cli parser.
---@param command core.cli.command
---@param overwrite? boolean
function cli.register(command, overwrite) end

---Removes an existing command from the cli parser.
---@param command string
function cli.unregister(command) end

---Get the default command used by the CLI parser.
---@return core.cli.command?
function cli.get_default() end

---Set the default command used by the CLI parser.
---@param command core.cli.command
function cli.set_default(command) end

---Adds color to given text on non windows systems.
---@param text string
---@param color "red" | "green" | "yellow" | "purple" | "blue" | "liteblue" | "gray"
---@return string colorized_text
function cli.colorize(text, color) end

---Display the generated application help or a specific command help.
---@param command core.cli.command?
function cli.print_help(command) end

---Parse the command line arguments and execute the applicable commands.
---@param args string[]
function cli.parse(args) end

local cli = require "core.cli"

-- Register greet command
cli.register {
  command = "greet",
  description = "A custom command to print a hello message.",
  usage = "[--name=some_name] [<extra_names...>]",
  flags = {
    {
      type = "string",
      name = "name",
      short_name = "n",
      description = "The name to greet"
    }
  },
  subcommands = {
    {
      command = "love",
      description = "A subcommand of greet with a love touch.",
      usage = "[--name=some_name] [<extra_names...>]",
      flags = {
        {
          type = "string",
          name = "name",
          short_name = "n",
          description = "The name to greet"
        }
      },
      usage = "[--name=some_name] [<extra_names...>]",
      execute = function(flags, arguments)
        local name = "stranger"
        for _, flag in ipairs(flags) do
          if flag.name == "name" then
            name = flag.value
          end
        end
        for _, arg in ipairs(arguments) do
          name = name .. " and " .. arg
        end
        print("Hello beautiful " .. name .. "!")
      end
    }
  },
  execute = function(flags, arguments)
    local name = "stranger"
    for _, flag in ipairs(flags) do
      if flag.name == "name" then
        name = flag.value
      end
    end
    for _, arg in ipairs(arguments) do
      name = name .. " and " .. arg
    end
    print("Hello " .. name .. "!")
  end
}