Модуль Arg

module Arg: sig .. end

Разбор аргументов командной строки.

Этот модуль предоставляет общий механизм для извлечения опций и аргументов из командной строки в программу. Например:

     let usage_msg = "append [-verbose] <file1> [<file2>] ... -o <output>"
     let verbose = ref false
     let input_files = ref []
     let output_file = ref ""

     let anon_fun filename =
       input_files := filename::!input_files

     let speclist =
       [("-verbose", Arg.Set verbose, "Output debug information");
        ("-o", Arg.Set_string output_file, "Set output file name")]

     let () =
       Arg.parse speclist anon_fun usage_msg;
       (* Main functionality here *)

Синтаксис командной строки: Ключевое слово — это строка символов, начинающаяся с -. Опция — это ключевое слово, взятое в одиночку или с аргументом. Типы ключевых слов: Unit, Bool, Set, Clear, String, Set_string, Int, Set_int, Float, Set_float, Tuple, Symbol, Rest, Rest_all и Expand.

Ключевые слова Unit, Set и Clear не принимают аргументов.

Ключевое слово Rest или Rest_all принимает оставшуюся часть командной строки в качестве аргументов. (Подробнее ниже.)

Всякое другое ключевое слово принимает следующее слово в командной строке в качестве аргумента. Для совместимости с GNU getopt_long также разрешено keyword=arg. Аргументы, не предваряемые ключевым словом, называются анонимными аргументами.

Примеры (cmd предполагается именем команды):

cmd -flag (опция unit)
cmd -int 1 (опция int с аргументом 1)
cmd -string foobar (опция string с аргументом "foobar")
cmd -float 12.34 (опция float с аргументом 12.34)
cmd a b c (три анонимных аргумента: "a", "b", и "c")
cmd a b -- c d (два анонимных аргумента и опция rest с двумя аргументами)

Rest принимает функцию, которая вызывается многократно для каждого оставшегося аргумента командной строки. Rest_all принимает функцию, которая вызывается один раз, со списком всех оставшихся аргументов.

Обратите внимание, что если за ключевым словом Rest не следуют аргументы, то функция не вызывается вообще, в то время как функция для ключевого слова Rest_all вызывается со списком пустым списком.

Предупреждение unsynchronized_access. Модуль Arg опирается на изменчивое глобальное состояние, функции парсинга должны вызываться только из одного домена.

type spec =

`\|`	`Unit of (unit -> unit)`	`(*`	Вызов функции с аргументом unit	`*)`
`\|`	`Bool of (bool -> unit)`	`(*`	Вызов функции с аргументом bool	`*)`
`\|`	`Set of bool ref`	`(*`	Установить ссылку на true	`*)`
`\|`	`Clear of bool ref`	`(*`	Установить ссылку на false	`*)`
`\|`	`String of (string -> unit)`	`(*`	Вызов функции с аргументом string	`*)`
`\|`	`Set_string of string ref`	`(*`	Установить ссылку на строковый аргумент	`*)`
`\|`	`Int of (int -> unit)`	`(*`	Вызов функции с аргументом int	`*)`
`\|`	`Set_int of int ref`	`(*`	Установить ссылку на целочисленный аргумент	`*)`
`\|`	`Float of (float -> unit)`	`(*`	Вызов функции с аргументом float	`*)`
`\|`	`Set_float of float ref`	`(*`	Установить ссылку на аргумент float	`*)`
`\|`	`Tuple of spec list`	`(*`	Принять несколько аргументов в соответствии со списком спецификаций	`*)`
`\|`	`Symbol of string list * (string -> unit)`	`(*`	Принять один из символов в качестве аргумента и вызвать функцию с этим символом	`*)`
`\|`	`Rest of (string -> unit)`	`(*`	Прекратить интерпретацию ключевых слов и вызвать функцию с каждым оставшимся аргументом	`*)`
`\|`	`Rest_all of (string list -> unit)`	`(*`	Прекратить интерпретацию ключевых слов и вызвать функцию со всеми оставшимися аргументами	`*)`
`\|`	`Expand of (string -> string array)`	`(*`	Если оставшиеся аргументы для обработки имеют вид `["-foo"; "arg"] @ rest`, где "foo" зарегистрирован как `Expand f`, то обрабатываются аргументы `f "arg" @ rest`. Разрешено только в `parse_and_expand_argv_dynamic`.	`*)`

Конкретный тип, описывающий поведение, связанное с ключевым словом.

type key = string

type doc = string

type usage_msg = string

type anon_fun = string -> unit

val parse : (key * spec * doc) list -> anon_fun -> usage_msg -> unit

Arg.parse speclist anon_fun usage_msg анализирует командную строку. speclist представляет собой список троек (key, spec, doc). key — это ключевое слово опции, оно должно начинаться с символа '-'. spec задаёт тип опции и функцию, которая должна быть вызвана, когда эта опция обнаружена в командной строке. doc — это однострочное описание этой опции. anon_fun вызывается для анонимных аргументов. Функции в spec и anon_fun вызываются в том же порядке, что и их аргументы, в котором они появляются в командной строке.

Если возникает ошибка, Arg.parse завершает выполнение программы, выведя сообщение об ошибке в стандартный поток ошибок следующим образом:

Причина ошибки: неизвестная опция, неверный или отсутствующий аргумент и т.д.
usage_msg
Список опций, после каждой из которых следует соответствующая строка doc. Обратите внимание: опции, у которых пустая строка doc, не будут включены в список.

Для того, чтобы пользователь мог указывать анонимные аргументы, начинающиеся с -, включите, например, ("-", String anon_fun, doc) в speclist.

По умолчанию parse распознаёт две опции для единиц, -help и --help, которые выведут в стандартный вывод usage_msg и список опций и завершат выполнение программы. Вы можете переопределить это поведение, указав свои собственные опции -help и --help в speclist.

val parse_dynamic : (key * spec * doc) list ref ->       anon_fun -> usage_msg -> unit

Аналогично Arg.parse, за исключением того, что аргумент speclist является ссылкой и может быть обновлён во время парсинга. Типичное использование этой функции — парсинг командных строк вида:

команда подкоманда options где список опций зависит от значения аргумента подкоманды.

Since 4.01

val parse_argv : ?current:int ref ->       string array ->       (key * spec * doc) list -> anon_fun -> usage_msg -> unit

Arg.parse_argv ~current args speclist anon_fun usage_msg анализирует массив args так, как будто это командная строка. Она использует и обновляет значение ~current (если задано) или Arg.current. Вы должны установить его перед вызовом parse_argv. Начальное значение current — это индекс имени программы (аргумент 0) в массиве. Если возникает ошибка, Arg.parse_argv поднимает Arg.Bad с сообщением об ошибке в качестве аргумента. Если указана опция -help или --help, Arg.parse_argv поднимает Arg.Help с сообщением справки в качестве аргумента.

val parse_argv_dynamic : ?current:int ref ->       string array ->       (key * spec * doc) list ref ->       anon_fun -> string -> unit

Аналогично Arg.parse_argv, за исключением того, что аргумент speclist является ссылкой и может быть обновлён во время парсинга. См. Arg.parse_dynamic.

Since 4.01

val parse_and_expand_argv_dynamic : int ref ->       string array ref ->       (key * spec * doc) list ref ->       anon_fun -> string -> unit

Аналогично Arg.parse_argv_dynamic, за исключением того, что аргумент argv является ссылкой и может быть обновлён во время парсинга аргументов Expand. См. Arg.parse_argv_dynamic.

Since 4.05

val parse_expand : (key * spec * doc) list -> anon_fun -> usage_msg -> unit

Аналогично Arg.parse, за исключением того, что аргументы Expand разрешены, и ссылка Arg.current не обновляется.

Since 4.05

exception Help of string

Вызывается Arg.parse_argv когда пользователь запрашивает справку.

exception Bad of string

Функции в spec или anon_fun могут вызвать Arg.Bad с сообщением об ошибке, чтобы отклонить недопустимые аргументы. Arg.Bad также вызывается Arg.parse_argv в случае ошибки.

val usage : (key * spec * doc) list -> usage_msg -> unit

Arg.usage speclist usage_msg выводит в стандартный поток ошибок сообщение об ошибке, которое включает список допустимых опций. Это то же сообщение, что и Arg.parse выводит в случае ошибки. speclist и usage_msg такие же, как у Arg.parse.

val usage_string : (key * spec * doc) list -> usage_msg -> string

Возвращает сообщение, которое было бы выведено функцией Arg.usage, если бы она получила те же параметры.

val align : ?limit:int ->       (key * spec * doc) list -> (key * spec * doc) list

Выравнивает строки документации, вставляя пробелы в первом разделителе выравнивания (табуляция или, если табуляция не найдена, пробел), в соответствии с длиной ключевого слова. Используйте разделитель выравнивания как первый символ в строке документации, если вы хотите выровнять всю строку. Строки документации, соответствующие аргументам Symbol выравниваются на следующей строке.

limit : опции с ключевым словом и сообщением, длина которых больше limit, не будут использоваться для вычисления выравнивания.

val current : int ref

Позиция (в Sys.argv) обрабатываемого аргумента. Вы можете изменить это значение, например, чтобы заставить Arg.parse пропустить некоторые аргументы. Arg.parse использует начальное значение Arg.current как индекс аргумента 0 (имя программы) и начинает парсинг аргументов со следующего элемента.

val read_arg : string -> string array

Arg.read_arg file считывает аргументы командной строки, завершённые новой строкой, из файла file.

Since 4.05

val read_arg0 : string -> string array

Идентично Arg.read_arg, но предполагает аргументы командной строки, завершённые нулём.

Since 4.05

val write_arg : string -> string array -> unit

Arg.write_arg file args записывает аргументы args, завершённые новой строкой, в файл file. Если какой-либо из аргументов в args содержит новую строку, используйте Arg.write_arg0 вместо этого.

Since 4.05

val write_arg0 : string -> string array -> unit

Идентично Arg.write_arg, но использует нулевой символ в качестве терминатора вместо новой строки.

Since 4.05