Модуль 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 (опция единицы)
cmd -int 1 (опция целого типа с аргументом 1)
cmd -string foobar (строковая опция с аргументом "foobar")
cmd -float 12.34 (опция с плавающей точкой с аргументом 12.34)
cmd a b c (три анонимных аргумента: "a", "b", и "c")
cmd a b -- c d (два анонимных аргумента и опция со списком с двумя аргументами)

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

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

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

type spec =

`\|`	`Unit of (unit -> unit)`	`(*`	Вызвать функцию с аргументом типа unit	`*)`
`\|`	`Bool of (bool -> unit)`	`(*`	Вызвать функцию с логическим аргументом	`*)`
`\|`	`Set of bool ref`	`(*`	Установить ссылку в значение true	`*)`
`\|`	`Clear of bool ref`	`(*`	Установить ссылку в значение false	`*)`
`\|`	`String of (string -> unit)`	`(*`	Вызвать функцию с аргументом типа string	`*)`
`\|`	`Set_string of string ref`	`(*`	Установить ссылку на строковый аргумент	`*)`
`\|`	`Int of (int -> unit)`	`(*`	Вызвать функцию с целочисленным аргументом	`*)`
`\|`	`Set_int of int ref`	`(*`	Установить ссылку на целочисленный аргумент	`*)`
`\|`	`Float of (float -> unit)`	`(*`	Вызвать функцию с аргументом с плавающей точкой	`*)`
`\|`	`Set_float of float ref`	`(*`	Установить ссылку на аргумент с плавающей точкой	`*)`
`\|`	`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.0

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.0

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.0

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

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

Since 4.05.0

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.0

val read_arg0 : string -> string array

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

Since 4.05.0

val write_arg : string -> string array -> unit

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

Since 4.05.0

val write_arg0 : string -> string array -> unit

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

Since 4.05.0