Pular para o conteúdo principal

API de argumentos

As utilidades de esquema e parse de argumentos de CLI estão disponíveis em ptool.args e p.args.

ptool.args.arg​

v0.1.0 - Introduced.

ptool.args.arg(id, kind, options) cria um builder de argumento para uso em ptool.args.parse(...).schema.args.

  • id (string, obrigatório): O identificador do argumento. Ele também é a chave na tabela retornada.
  • kind (string, obrigatório): O tipo do argumento. Valores suportados:
    • "flag": Um flag booleano.
    • "string": Uma opção string.
    • "int": Uma opção inteira (i64).
    • "positional": Um argumento posicional.
  • options (table, opcional): Os mesmos campos opcionais suportados por tabelas de argumento em ptool.args.parse, como long, short, help, required, multiple e default.

O builder suporta métodos encadeáveis, todos retornando ele mesmo:

  • arg:long(value) define o nome da opção longa. Suportado apenas para argumentos não positional.
  • arg:short(value) define o nome da opção curta. Suportado apenas para argumentos não positional.
  • arg:help(value) define o texto de ajuda.
  • arg:required(value) define se o argumento é obrigatório. Se value for omitido, o padrão é true.
  • arg:multiple(value) define se o argumento pode se repetir. Se value for omitido, o padrão é true.
  • arg:default(value) define o valor padrão. Se value = nil, o padrão é limpo.

Exemplo:

local res = ptool.args.parse({
  args = {
    ptool.args.arg("name", "string"):required(),
    ptool.args.arg("verbose", "flag", { short = "v" }),
    ptool.args.arg("paths", "positional"):multiple(),
  }
})

ptool.args.parse​

v0.1.0 - Introduced.

v0.3.0 - Added subcommands support.

ptool.args.parse(schema) faz o parse dos argumentos do script com clap e retorna uma tabela indexada por id.

Os argumentos do script vêm da parte após -- em ptool run <lua_file> -- ....

Por exemplo:

ptool.use("v0.1.0")

local res = ptool.args.parse({
    name = "test",
    about = "The test command",
    args = {
        { id = "name", kind = "string" }
    }
})

print("Hello, " .. res.name .. "!")

Estrutura do esquema​

  • name (string, opcional): O nome do comando, usado na saída de ajuda. O padrão é o nome do arquivo do script.
  • about (string, opcional): Descrição de ajuda.
  • args (table, opcional): Um array de definições de argumento. Cada item suporta duas formas:
    • Uma tabela de argumento.
    • Um objeto builder retornado por ptool.args.arg(...).
  • subcommands (table, opcional): Um mapa de nome de subcomando para esquema de subcomando. Cada esquema de subcomando suporta about, args e subcommands recursivamente.

Pelo menos um de args ou subcommands precisa ser fornecido.

Campos da tabela de argumento:

  • id (string, obrigatório): O identificador do argumento. Ele também é a chave na tabela retornada.
  • kind (string, obrigatório): O tipo do argumento. Valores suportados:
    • "flag": Um flag booleano.
    • "string": Uma opção string.
    • "int": Uma opção inteira (i64).
    • "positional": Um argumento posicional.
  • long (string, opcional): O nome da opção longa, como "name" para --name. Para argumentos não positional, o padrão pode ser derivado de id.
  • short (string, opcional): O nome da opção curta, um único caractere como "v" para -v.
  • help (string, opcional): Texto de ajuda do argumento.
  • required (boolean, opcional): Se o argumento é obrigatório. O padrão é false.
  • multiple (boolean, opcional): Se o argumento pode se repetir. O padrão é false.
  • default (string/integer, opcional): O valor padrão.

Quando subcommands está presente, args do comando atual age como opções compartilhadas para aquela árvore de comandos e é aceito antes ou depois do subcomando selecionado.

Exemplo com subcomandos:

local res = ptool.args.parse({
  name = "demo",
  args = {
    ptool.args.arg("verbose", "flag", { short = "v" }),
    ptool.args.arg("config", "string"),
  },
  subcommands = {
    build = {
      args = {
        ptool.args.arg("release", "flag"),
      },
      subcommands = {
        web = {
          args = {
            ptool.args.arg("out", "string"):required(),
          },
        },
      },
    },
    clean = {
      args = {
        ptool.args.arg("all", "flag"),
      },
    },
  },
})

Restrições​

  • As seguintes restrições se aplicam tanto a tabelas de argumento quanto à sintaxe de builder.
  • Argumentos não positional podem omitir long e short. Se long for omitido, id é usado automaticamente.
  • Argumentos positional não podem definir long, short ou default.
  • Quando positional.multiple = true, ele precisa ser o último argumento em args.
  • multiple = true só é suportado para string e positional.
  • default só é suportado para string e int, e não pode ser usado junto com multiple = true.
  • Quando subcommands está presente, argumentos positional não são permitidos nesse mesmo esquema.
  • Quando subcommands está presente no nível superior, os ids de argumento command_path e args ficam reservados.
  • Ao longo de um mesmo caminho de subcomando selecionado, subcomandos ancestrais e descendentes não podem reutilizar o mesmo id de argumento, porque seus valores são mesclados em uma única tabela args.

Valor de retorno​

Uma tabela Lua é retornada, em que as chaves são id e os tipos de valor são:

  • flag -> boolean
  • string -> string (ou string[] quando multiple = true)
  • int -> integer
  • positional -> string (ou string[] quando multiple = true)

Quando subcommands não está presente, o valor de retorno permanece plano como acima.

Quando subcommands está presente, o valor de retorno tem este formato:

  • Valores de args do nível superior são retornados diretamente na tabela de nível superior.
  • command_path -> string[]: O caminho de subcomando correspondente, por exemplo {"build", "web"}.
  • args -> table: Os valores de argumento mesclados do caminho de subcomando correspondente.

Por exemplo:

{
  verbose = true,
  config = "cfg.toml",
  command_path = { "build", "web" },
  args = {
    release = true,
    out = "dist",
  },
}