parseopt

Этот модуль предоставляет стандартный парсер командной строки Nim. Он поддерживает один удобный итератор для всех опций командной строки и некоторые функции низкого уровня.

Поддерживаемый синтаксис

Следующий синтаксис поддерживается, когда аргументы для параметров shortNoVal и longNoVal, которые описаны позже, не указаны:

Короткие опции: -abcd, -e:5, -e=5
Длинные опции: --foo:bar, --foo=bar, --foo
Аргументы: всё, что не начинается с -

Эти три типа маркеров перечислены в перечислении CmdLineKind.

Когда значения опций начинаются с ':' или '=', они должны быть удвоены (как в --delim::) или чередованы (как в --delim=:).

Опция --, обычно используемая для обозначения того, что каждый следующий маркер является аргументом, интерпретируется как длинная опция, а её имя — пустая строка.

Парсинг

Используйте OptParser для парсинга опций командной строки. Он может быть создан с помощью initOptParser, а next продвигает парсер на один маркер.

Для каждого маркера поля парсера kind, key, и val предоставляют информацию об этом маркере. Если маркер — это длинная или короткая опция, key — это имя опции, а val — либо значение опции, если оно предоставлено, либо пустая строка. Для аргументов поле key содержит сам аргумент, а val не используется. Чтобы проверить, достигнут ли конец командной строки, проверьте, равно ли kind cmdEnd.

Вот пример:

import parseopt

var p = initOptParser("-ab -e:5 --foo --bar=20 file.txt")
while true:
  p.next()
  case p.kind
  of cmdEnd: break
  of cmdShortOption, cmdLongOption:
    if p.val == "":
      echo "Option: ", p.key
    else:
      echo "Option and value: ", p.key, ", ", p.val
  of cmdArgument:
    echo "Argument: ", p.key

# Output:
# Option: a
# Option: b
# Option and value: e, 5
# Option: foo
# Option and value: bar, 20
# Argument: file.txt

Итератор getopt, предоставленный для удобства, также может использоваться для итерирования по всем опциям командной строки.

`shortNoVal` и `longNoVal`

Необязательные параметры shortNoVal и longNoVal, присутствующие в initOptParser, предназначены для указания коротких и длинных опций, которые не принимают значения.

Когда shortNoVal не пусто, пользователям не нужно разделять короткие опции и их значения двоеточием или знаком равенства, так как парсер знает, какие опции принимают значения, а какие нет. Это поведение также применяется к длинным опциям, если longNoVal не пусто. Для коротких опций синтаксис -j4 становится поддерживаемым, а для длинных опций — --foo bar. Это в дополнение к ранее упомянутому синтаксису. Пользователи по-прежнему могут разделять опции и их значения двоеточием или знаком равенства, но это становится необязательным.

По мере добавления в вашу программу больше опций, не принимающих значения, помните, чтобы соответствующим образом изменить shortNoVal и longNoVal.

Следующий пример иллюстрирует разницу между пустым shortNoVal и longNoVal, что является значением по умолчанию, и предоставлением аргументов для этих двух параметров:

import parseopt

proc printToken(kind: CmdLineKind, key: string, val: string) =
  case kind
  of cmdEnd: doAssert(false)  # Doesn't happen with getopt()
  of cmdShortOption, cmdLongOption:
    if val == "":
      echo "Option: ", key
    else:
      echo "Option and value: ", key, ", ", val
  of cmdArgument:
    echo "Argument: ", key

let cmdLine = "-j4 --first bar"

var emptyNoVal = initOptParser(cmdLine)
for kind, key, val in emptyNoVal.getopt():
  printToken(kind, key, val)

# Output:
# Option: j
# Option: 4
# Option: first
# Argument: bar

var withNoVal = initOptParser(cmdLine, shortNoVal = {'c'},
                              longNoVal = @["second"])
for kind, key, val in withNoVal.getopt():
  printToken(kind, key, val)

# Output:
# Option and value: j, 4
# Option and value: first, bar

См. также

Модуль os для процедур парсинга командной строки низкого уровня
Модуль parseutils для помощников, которые парсят маркеры, числа, идентификаторы и т. д.
Модуль strutils для общих операций обработки строк
Модуль json для парсера JSON
Модуль parsecfg для парсера файла конфигурации
Модуль parsecsv для простого парсера CSV (значений, разделённых запятыми)
Модуль parsexml для парсера XML / HTML
Другие парсеры для других парсеров

Импорты

Типы

CmdLineKind = enum cmdEnd, ## End of command line reached cmdArgument, ## An argument such as a filename cmdLongOption, ## A long option such as --option cmdShortOption ## A short option such as -c

Обнаруженный маркер командной строки. Исходный код Редактировать

OptParser = object of RootObj pos*: int inShortState: bool allowWhitespaceAfterColon: bool shortNoVal: set[char] longNoVal: seq[string] cmds: seq[string] idx: int kind*: CmdLineKind ## The detected command line token key*, val*: TaintedString ## Key and value pair; the key is the option ## or the argument, and the value is not "" if ## the option was given a value

Реализация парсера командной строки.

Для его инициализации используйте процедуру initOptParser.

Исходный код Редактировать

Процедуры

proc initOptParser(cmdline = ""; shortNoVal: set[char] = {}; longNoVal: seq[string] = @[]; allowWhitespaceAfterColon = true): OptParser {...}{.raises: [], tags: [ReadIOEffect].}

Инициализирует парсер командной строки.

Если cmdline == "", вместо этого извлекается фактическая командная строка, предоставленная модулем os.

shortNoVal и longNoVal используются для указания опций, которые не принимают значения. См. документацию по этим параметрам для получения дополнительной информации о том, как это влияет на парсинг.

См. также:

итератор getopt

Пример:

var p = initOptParser()
p = initOptParser("--left --debug:3 -l -r:2")
p = initOptParser("--left --debug:3 -l -r:2",
                  shortNoVal = {'l'}, longNoVal = @["left"])

Исходный код Редактировать

proc initOptParser(cmdline: seq[TaintedString]; shortNoVal: set[char] = {}; longNoVal: seq[string] = @[]; allowWhitespaceAfterColon = true): OptParser {...}{.raises: [], tags: [ReadIOEffect].}

Инициализирует парсер командной строки.

Если cmdline.len == 0, вместо этого извлекается фактическая командная строка, предоставленная модулем os.

Поведение других параметров остается таким же, как в initOptParser(string, ...).

См. также:

итератор getopt

Пример:

var p = initOptParser()
p = initOptParser(@["--left", "--debug:3", "-l", "-r:2"])
p = initOptParser(@["--left", "--debug:3", "-l", "-r:2"],
                  shortNoVal = {'l'}, longNoVal = @["left"])

Исходный код Редактировать

proc next(p: var OptParser) {...}{.gcsafe, extern: "npo$1", raises: [], tags: [].}

Парсит следующий маркер.

p.kind описывает тип обработанного маркера. p.key и p.val устанавливаются соответственно.

Пример:

var p = initOptParser("--left -r:2 file.txt")
p.next()
doAssert p.kind == cmdLongOption and p.key == "left"
p.next()
doAssert p.kind == cmdShortOption and p.key == "r" and p.val == "2"
p.next()
doAssert p.kind == cmdArgument and p.key == "file.txt"
p.next()
doAssert p.kind == cmdEnd

Исходный код Редактировать

proc cmdLineRest(p: OptParser): TaintedString {...}{.gcsafe, extern: "npo$1", raises: [], tags: [].}

Возвращает остаток командной строки, который еще не был обработан.

См. также:

процедура remainingArgs

Примеры:

var p = initOptParser("--left -r:2 -- foo.txt bar.txt")
while true:
  p.next()
  if p.kind == cmdLongOption and p.key == "":  # Look for "--"
    break
  else: continue
doAssert p.cmdLineRest == "foo.txt bar.txt"

Исходный код Редактировать

proc remainingArgs(p: OptParser): seq[TaintedString] {...}{.gcsafe, extern: "npo$1", raises: [], tags: [].}

Возвращает последовательность аргументов, которые еще не были обработаны.

См. также:

процедура cmdLineRest

Примеры:

var p = initOptParser("--left -r:2 -- foo.txt bar.txt")
while true:
  p.next()
  if p.kind == cmdLongOption and p.key == "":  # Look for "--"
    break
  else: continue
doAssert p.remainingArgs == @["foo.txt", "bar.txt"]

Исходный код Редактировать

Итераторы

iterator getopt(p: var OptParser): tuple[kind: CmdLineKind, key, val: TaintedString] {...}{.raises: [], tags: [].}

Удобный итератор для итерирования по предоставленному OptParser.

При итерировании нет необходимости проверять cmdEnd.

См. также:

процедура initOptParser

Примеры:

# these are placeholders, of course
proc writeHelp() = discard
proc writeVersion() = discard

var filename: string
var p = initOptParser("--left --debug:3 -l -r:2")

for kind, key, val in p.getopt():
  case kind
  of cmdArgument:
    filename = key
  of cmdLongOption, cmdShortOption:
    case key
    of "help", "h": writeHelp()
    of "version", "v": writeVersion()
  of cmdEnd: assert(false) # cannot happen
if filename == "":
  # no filename has been given, so we show the help
  writeHelp()

Исходный код Редактировать

iterator getopt(cmdline: seq[TaintedString] = commandLineParams(); shortNoVal: set[char] = {}; longNoVal: seq[string] = @[]): tuple[ kind: CmdLineKind, key, val: TaintedString] {...}{.raises: [], tags: [ReadIOEffect].}

Удобный итератор для итерирования по аргументам командной строки.

Это создаёт новый OptParser. Если аргументы командной строки не указаны, вместо этого извлекается фактическая командная строка, предоставленная модулем os.

При итерировании нет необходимости проверять cmdEnd.

См. также:

процедура initOptParser

Примеры:

# these are placeholders, of course
proc writeHelp() = discard
proc writeVersion() = discard

var filename: string
let params = @["--left", "--debug:3", "-l", "-r:2"]

for kind, key, val in getopt(params):
  case kind
  of cmdArgument:
    filename = key
  of cmdLongOption, cmdShortOption:
    case key
    of "help", "h": writeHelp()
    of "version", "v": writeVersion()
  of cmdEnd: assert(false) # cannot happen
if filename == "":
  # no filename has been written, so we show the help
  writeHelp()

Исходный код Редактировать

parseopt

Поддерживаемый синтаксис

Парсинг

shortNoVal и longNoVal

См. также

Импорты

Типы

Процедуры

Итераторы

`shortNoVal` и `longNoVal`