Модуль 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`	`(*`	Установить для ссылки значение аргумента с плавающей точкой	`*)`
`\|`	`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 распознаёт два параметра типа unit: -help и --help. Они выводят в стандартный поток вывода usage_msg и список параметров, после чего завершают программу. Это поведение можно переопределить, указав собственные параметры -help и --help в speclist.

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

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

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

Начиная с версии 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.

Начиная с версии 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.

Начиная с версии 4.05

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

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

Начиная с версии 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 аргументы командной строки, каждый из которых завершается символом новой строки.

Начиная с версии 4.05

val read_arg0 : string -> string array

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

Начиная с версии 4.05

val write_arg : string -> string array -> unit

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

Начиная с версии 4.05

val write_arg0 : string -> string array -> unit

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

Начиная с версии 4.05