CLI-пакет

Пакет CLI предоставляет улучшенную обработку командной строки Posix+GNU с возможностью задания команд иерархически.

См. RFC-0038 для более подробной информации.

Общая EBNF командной строки:

  command_line ::= root_command (option | command)* (option | arg)*
  command ::= alphanum_word
  alphanum_word ::= alphachar(alphachar | numchar | '_' | '-')*
  option ::= longoption | shortoptionset
  longoption ::= '--'alphanum_word['='arg | ' 'arg]
  shortoptionset := '-'alphachar[alphachar]...['='arg | ' 'arg]
  arg := boolarg | intarg | floatarg | stringarg
  boolarg := 'true' | 'false'
  intarg> := ['-'] numchar...
  floatarg ::= ['-'] numchar... ['.' numchar...]
  stringarg ::= anychar

Примеры:

  usage: ls [<options>] [<args> ...]
  usage: make [<options>] <command> [<options>] [<args> ...]
  usage: chat [<options>] <command>  <subcommand> [<options>] [<args> ...]

Использование

Типы в пакете cli разделены на три группы:

Спецификации

Программы Pony используют конструкторы для создания объектов спецификации, чтобы определить синтаксис своей командной строки. Многие аспекты спецификации проверяются на корректность во время компиляции, а результат представляет всё, что парсеру необходимо знать при разборе командной строки или формировании сообщений справки по синтаксису.

Типы значений параметров и аргументов

Параметры и аргументы анализируют значения из командной строки как один из четырёх типов Pony: Bool, String, I64 и F64. Значения каждого из этих типов затем могут быть извлечены с помощью соответствующих функций-акцессоров.

Кроме того, есть тип string_seq, который принимает строковые значения из командной строки и собирает их в последовательность, которую затем можно получить как ReadSeq[String] с помощью функции-акцессора string_seq().

Некоторые особенности:

• Параметры типа bool: имеют значение по умолчанию 'true', если значение не указано. То есть, -f эквивалентно -f=true.

• Параметры типа string_seq: префикс опции должен использоваться каждый раз, например: --file=f1 --file=f2 --file=f3, а результаты собираются в одну последовательность.

• Аргументы типа string_seq: нет способа указать завершение, поэтому аргумент типа string_seq должен быть последним аргументом команды и будет потреблять все оставшиеся аргументы командной строки.

Парсер

Затем программы используют созданную ими спецификацию команды CommandSpec для создания парсера, чтобы проанализировать заданную командную строку. Часто это env.args(), но также это могут быть команды из файлов или других источников ввода. Результатом разбора является либо проанализированная команда, либо справка по команде, либо объект синтаксической ошибки.

Команды

Затем программы сопоставляют объект, возвращённый парсером, чтобы определить, какой он. Ошибки и запросы справки обычно печатают сообщения и завершают программу. Для команд можно сопоставить полное имя и извлечь эффективные значения параметров и аргументов команды.

Пример программы

Эта программа эхом выводит свои аргументы командной строки с опцией преобразования их в верхний регистр.

use "cli"

actor Main
  new create(env: Env) =>
    let cs =
      try
        CommandSpec.leaf("echo", "A sample echo program", [
          OptionSpec.bool("upper", "Uppercase words"
            where short' = 'U', default' = false)
        ], [
          ArgSpec.string_seq("words", "The words to echo")
        ])? .> add_help()?
      else
        env.exitcode(-1)  // some kind of coding error
        return
      end

    let cmd =
      match CommandParser(cs).parse(env.args, env.vars)
      | let c: Command => c
      | let ch: CommandHelp =>
          ch.print_help(env.out)
          env.exitcode(0)
          return
      | let se: SyntaxError =>
          env.out.print(se.string())
          env.exitcode(1)
          return
      end

    let upper = cmd.option("upper").bool()
    let words = cmd.arg("words").string_seq()
    for word in words.values() do
      env.out.write(if upper then word.upper() else word end + " ")
    end
    env.out.print("")

Типы общедоступного использования

• базовые EnvVars
• класс CommandSpec
• класс OptionSpec
• класс ArgSpec
• класс CommandParser
• базовый тип Help
• класс CommandHelp
• класс Command
• класс Option
• класс Arg
• класс SyntaxError