--- name: "Arg" section: "3o" platform: "linux" package: "ocaml" version: "5.5.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Arg" --- # Arg(3o) Parsing of command line arguments. ## NAME Arg - Parsing of command line arguments. ## Module Module Arg ## Documentation Module **Arg**\ : **sig end** Parsing of command line arguments. This module provides a general mechanism for extracting options and arguments from the command line to the program. For example: ``` let usage_msg = "append [-verbose] [] ... -o " 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 *) ``` Syntax of command lines: A keyword is a character string starting with a **-** . An option is a keyword alone or followed by an argument. The types of keywords are: **Unit** , **Bool** , **Set** , **Clear** , **String** , **Set\_string** , **Int** , **Set\_int** , **Float** , **Set\_float** , **Tuple** , **Symbol** , **Rest** , **Rest\_all** and **Expand** . **Unit** , **Set** and **Clear** keywords take no argument. A **Rest** or **Rest\_all** keyword takes the remainder of the command line as arguments. (More explanations below.) Every other keyword takes the following word on the command line as argument. For compatibility with GNU getopt\_long, **keyword=arg** is also allowed. Arguments not preceded by a keyword are called anonymous arguments. Examples ( **cmd** is assumed to be the command name): \- **cmd -flag** (a unit option) \- **cmd -int 1** (an int option with argument **1** ) \- **cmd -string foobar** (a string option with argument **"foobar"** ) \- **cmd -float 12.34** (a float option with argument **12.34** ) \- **cmd a b c** (three anonymous arguments: **"a"** , **"b"** , and **"c"** ) \- **cmd a b -- c d** (two anonymous arguments and a rest option with two arguments) **Rest** takes a function that is called repeatedly for each remaining command line argument. **Rest\_all** takes a function that is called once, with the list of all remaining arguments. Note that if no arguments follow a **Rest** keyword then the function is not called at all whereas the function for a **Rest\_all** keyword is called with an empty list. **Alert unsynchronized\_access.** The Arg module relies on a mutable global state, parsing functions should only be called from a single domain. *type spec* =\ \| Unit **of** **(unit -\> unit)** \ (\* Call the function with unit argument\ \*)\ \| Bool **of** **(bool -\> unit)** \ (\* Call the function with a bool argument\ \*)\ \| Set **of** **bool ref** \ (\* Set the reference to true\ \*)\ \| Clear **of** **bool ref** \ (\* Set the reference to false\ \*)\ \| String **of** **(string -\> unit)** \ (\* Call the function with a string argument\ \*)\ \| Set\_string **of** **string ref** \ (\* Set the reference to the string argument\ \*)\ \| Int **of** **(int -\> unit)** \ (\* Call the function with an int argument\ \*)\ \| Set\_int **of** **int ref** \ (\* Set the reference to the int argument\ \*)\ \| Float **of** **(float -\> unit)** \ (\* Call the function with a float argument\ \*)\ \| Set\_float **of** **float ref** \ (\* Set the reference to the float argument\ \*)\ \| Tuple **of** **spec list** \ (\* Take several arguments according to the spec list\ \*)\ \| Symbol **of** **string list \* (string -\> unit)** \ (\* Take one of the symbols as argument and call the function with the symbol\ \*)\ \| Rest **of** **(string -\> unit)** \ (\* Stop interpreting keywords and call the function with each remaining argument\ \*)\ \| Rest\_all **of** **(string list -\> unit)** \ (\* Stop interpreting keywords and call the function with all remaining arguments\ \*)\ \| Expand **of** **(string -\> string array)** \ (\* If the remaining arguments to process are of the form **\["-foo"; "arg"\] @ rest** where "foo" is registered as **Expand f** , then the arguments **f "arg" @ rest** are processed. Only allowed in **parse\_and\_expand\_argv\_dynamic** .\ \*) The concrete type describing the behavior associated with a keyword. *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** parses the command line. **speclist** is a list of triples **(key, spec, doc)** . **key** is the option keyword, it must start with a **'-'** character. **spec** gives the option type and the function to call when this option is found on the command line. **doc** is a one-line description of this option. **anon\_fun** is called on anonymous arguments. The functions in **spec** and **anon\_fun** are called in the same order as their arguments appear on the command line. If an error occurs, **Arg.parse** exits the program, after printing to standard error an error message as follows: \- The reason for the error: unknown option, invalid or missing argument, etc. \- **usage\_msg** \- The list of options, each followed by the corresponding **doc** string. Beware: options that have an empty **doc** string will not be included in the list. For the user to be able to specify anonymous arguments starting with a **-** , include for example **("-", String anon\_fun, doc)** in **speclist** . By default, **parse** recognizes two unit options, **-help** and **--help** , which will print to standard output **usage\_msg** and the list of options, and exit the program. You can override this behaviour by specifying your own **-help** and **--help** options in **speclist** . *val parse\_dynamic* : **(key \* spec \* doc) list ref -\>** **anon\_fun -\> usage\_msg -\> unit** Same as **Arg.parse** , except that the **speclist** argument is a reference and may be updated during the parsing. A typical use for this feature is to parse command lines of the form: \- command subcommand **options** where the list of options depends on the value of the subcommand argument. **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** parses the array **args** as if it were the command line. It uses and updates the value of **~current** (if given), or **Arg.current** . You must set it before calling **parse\_argv** . The initial value of **current** is the index of the program name (argument 0) in the array. If an error occurs, **Arg.parse\_argv** raises **Arg.Bad** with the error message as argument. If option **-help** or **--help** is given, **Arg.parse\_argv** raises **Arg.Help** with the help message as argument. *val parse\_argv\_dynamic* : **?current:int ref -\>** **string array -\>** **(key \* spec \* doc) list ref -\>** **anon\_fun -\> string -\> unit** Same as **Arg.parse\_argv** , except that the **speclist** argument is a reference and may be updated during the parsing. See **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** Same as **Arg.parse\_argv\_dynamic** , except that the **argv** argument is a reference and may be updated during the parsing of **Expand** arguments. See **Arg.parse\_argv\_dynamic** . **Since** 4.05 *val parse\_expand* : **(key \* spec \* doc) list -\> anon\_fun -\> usage\_msg -\> unit** Same as **Arg.parse** , except that the **Expand** arguments are allowed and the **Arg.current** reference is not updated. **Since** 4.05 *exception Help* **of** **string** Raised by **Arg.parse\_argv** when the user asks for help. *exception Bad* **of** **string** Functions in **spec** or **anon\_fun** can raise **Arg.Bad** with an error message to reject invalid arguments. **Arg.Bad** is also raised by **Arg.parse\_argv** in case of an error. *val usage* : **(key \* spec \* doc) list -\> usage\_msg -\> unit** **Arg.usage speclist usage\_msg** prints to standard error an error message that includes the list of valid options. This is the same message that **Arg.parse** prints in case of error. **speclist** and **usage\_msg** are the same as for **Arg.parse** . *val usage\_string* : **(key \* spec \* doc) list -\> usage\_msg -\> string** Returns the message that would have been printed by **Arg.usage** , if provided with the same parameters. *val align* : **?limit:int -\>** **(key \* spec \* doc) list -\> (key \* spec \* doc) list** Align the documentation strings by inserting spaces at the first alignment separator (tab or, if tab is not found, space), according to the length of the keyword. Use a alignment separator as the first character in a doc string if you want to align the whole string. The doc strings corresponding to **Symbol** arguments are aligned on the next line. *val current* : **int ref** Position (in **Sys.argv** ) of the argument being processed. You can change this value, e.g. to force **Arg.parse** to skip some arguments. **Arg.parse** uses the initial value of **Arg.current** as the index of argument 0 (the program name) and starts parsing arguments at the next element. *val read\_arg* : **string -\> string array** **Arg.read\_arg file** reads newline-terminated command line arguments from file **file** . **Since** 4.05 *val read\_arg0* : **string -\> string array** Identical to **Arg.read\_arg** but assumes null character terminated command line arguments. **Since** 4.05 *val write\_arg* : **string -\> string array -\> unit** **Arg.write\_arg file args** writes the arguments **args** newline-terminated into the file **file** . If any of the arguments in **args** contains a newline, use **Arg.write\_arg0** instead. **Since** 4.05 *val write\_arg0* : **string -\> string array -\> unit** Identical to **Arg.write\_arg** but uses the null character for terminator instead of newline. **Since** 4.05