Receitas

Argumentos, opções e a ajuda

Declarar o que o comando aceita — e ganhar a ajuda, a validação e o erro de graça.

Ler OS.argv() à mão funciona para um script de dez linhas e apodrece no primeiro dia em que alguém escreve --formato json em vez de --formato=json. Arcane.Cli inverte isso: você declara o que o comando aceita, e a ajuda, a validação e a mensagem de erro saem da declaração.

dataforge

adopt Arcane.Cli as Cli

cmd := Cli.comando("relatorio", "Gera um relatório de vendas", "1.0.0")
cmd.posicional("entrada", "o CSV de vendas")
cmd.opcao("formato", "texto", "f", "tabela", "tabela, json ou csv", no,
          ["tabela", "json", "csv"])
cmd.opcao("limite", "inteiro", "n", 10, "quantas linhas")
cmd.opcao("cores", "sim_nao", "", no, "colorir a saída")

args := cmd.ler(["vendas.csv", "--formato=json", "-n", "5", "--cores"])
assert args["entrada"] is "vendas.csv"
assert args["formato"] is "json"
assert args["limite"] is 5          // já vem Integer, não texto
assert args["cores"] is yes

A ajuda é gerada, e por isso não mente#

Uma ajuda escrita à mão envelhece na primeira opção nova — e ninguém relê a ajuda do próprio programa. Aqui ela sai da mesma declaração que faz a leitura:

dataforge

adopt Arcane.Cli as Cli

cmd := Cli.comando("relatorio", "Gera um relatório de vendas", "1.0.0")
cmd.posicional("entrada", "o CSV de vendas")
cmd.opcao("formato", "texto", "f", "tabela", "tabela, json ou csv", no,
          ["tabela", "json", "csv"])
cmd.exemplo("relatorio vendas.csv --formato=json", "em JSON")

texto := cmd.ajuda()
assert "uso: relatorio" in texto
assert "--formato" in texto
assert "tabela|json|csv" in texto       // as escolhas aparecem
assert "exemplos:" in texto
out texto

O que a declaração compra#

Você declara	Ganha
`tipo := "inteiro"`	conversão, e erro claro em `--limite=abc`
`escolhas := [...]`	recusa o que não está na lista, e mostra a lista
`exigida := yes`	recusa a falta, dizendo qual falta
`curta := "n"`	`-n 5`, `-n=5` e `--limite 5` passam a ser a mesma coisa
`tipo := "sim_nao"`	`--cores` sem valor vira `yes`
`cmd.exemplo(…)`	a seção de exemplos da ajuda

O erro sai antes do trabalho#

dataforge

adopt Arcane.Cli as Cli

cmd := Cli.comando("relatorio", "")
cmd.opcao("formato", "texto", "f", "tabela", "", no, ["tabela", "json"])

monitor:
    cmd.ler(["--formato=xml"])
    assert no
handle Error as e:
    out e.message

Validar antes de abrir o arquivo é o que separa um erro de uma linha de um traceback no meio do processamento — e o que permite ao programa falhar sem ter escrito nada.

Vários valores para o mesmo posicional#

dataforge

adopt Arcane.Cli as Cli

cmd := Cli.comando("somar", "soma números")
cmd.posicional("numeros", "os números", yes)      // varios := yes

args := cmd.ler(["1", "2", "3"])
assert len(args["numeros"]) is 3
assert [int(n) cycle n in args["numeros"]] >> distill a, v: a + v 0 is 6