Stdlib.Arg(3)

✨ NAME ✨

Stdlib.Arg — and the description is… literally nothing 😭 the docs said "no description" and honestly? iconic of them. Anyway this is the OCaml library's command-line argument parsing module, and we're gonna go through it together, bestie 💅

---

🦋 Module 🦋

Stdlib.Arg

🎀 Documentation 🎀

Module Arg : (module Stdlib__Arg)

Okay so first up, the big one — the type that describes what each keyword does 🫶

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 .
 *)

Let me break those variants down one by one, because you deserve to know 👑

• Unit of (unit -> unit) — calls your function with a unit argument. no data, just vibes.
• Bool of (bool -> unit) — calls your function with a bool argument ✨
• Set of bool ref — sets that reference to true. slay.
• Clear of bool ref — sets that reference to false. the opposite slay.
• String of (string -> unit) — calls your function with a string argument 🍓
• Set_string of string ref — sets the reference to the string argument.
• Int of (int -> unit) — calls your function with an int argument.
• Set_int of int ref — sets the reference to the int argument.
• Float of (float -> unit) — calls your function with a float argument.
• Set_float of float ref — sets the reference to the float argument.
• Tuple of spec list — takes several arguments, following the spec list. group effort 💜
• Symbol of string list * (string -> unit) — takes one of the symbols as the argument, then calls your function with that symbol.
• Rest of (string -> unit) — stops interpreting keywords and calls your function with each remaining argument.
• Rest_all of (string list -> unit) — stops interpreting keywords and calls your function with all the remaining arguments, as a list.
• Expand of (string -> string array) — okay so lowkey the most extra one: if the remaining arguments to process look like ["-foo"; "arg"] @ rest where "foo" is registered as Expand f, then the arguments f "arg" @ rest get processed. Only allowed in parse_and_expand_argv_dynamic. no cap, don't try it anywhere else 🙈

This is the concrete type describing the behavior associated with a keyword. that's the whole point of it, bestie 💫

---

The little helper types, all very demure, all very mindful:

• type key = string
• type doc = string
• type usage_msg = string
• type anon_fun = string -> unit

---

🌸 The parsing functions 🌸

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 — and it must start with a '-' character.
• spec gives the option type plus the function to call when that option shows up on the command line.
• doc is a one-line description of the option.
• anon_fun gets called on anonymous arguments.

The functions inside spec and anon_fun are called in the same order as their arguments appear on the command line. respect the queue ✨

If an error occurs, Arg.parse exits the program, after printing to standard error an error message with these three things in it:

1. The reason for the error: unknown option, invalid or missing argument, etc. 😭
2. usage_msg
3. The list of options, each followed by the corresponding doc string.

Beware: options that have an empty doc string will not be included in that list. empty doc = invisible, fr fr 💀

So that the user can actually specify anonymous arguments that start with a -, include for example ("-", String anon_fun, doc) in speclist. little trick, big payoff 🫶

By default, parse recognizes two unit options, -help and --help, which print to standard output usage_msg and the list of options, and then exit the program. You can override this behaviour by specifying your own -help and --help options in speclist. your house, your rules 👑

---

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

Same as Arg.parse, except the speclist argument is a reference and may be updated during the parsing. main character energy: the list can change itself mid-scene 💅

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

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 if not. 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. set it first, no skipping, bestie 🙈

• 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 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 the argv argument is a reference and may be updated during the parsing of Expand arguments. See Arg.parse_argv_dynamic. this is the only place Expand is allowed, remember that 💅

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

---

😭 Exceptions 😭

exception Help of string

Raised by Arg.parse_argv when the user asks for help. the polite exception, we love her 🫶

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. girlies said "no" and they meant it 💀

---

🌈 Usage & alignment 🌈

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. consistent queen ⭐

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. same energy, just as a string 💜

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 an 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. aesthetics matter, this is a whole look ✨

---

👑 The current position 👑

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. so argument 0 is the main character and everyone else is at the next element, periodt.

---

🍓 Reading and writing arg files 🍓

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. genuinely, don't do it, it will not go well 😭

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

---

That's the whole vibe check, bestie — every variant, every val, every caveat, nothing skipped 🌸💖✨

mwah 💋 — this page was brought to you by OCamldoc (the source/version, doing the Lord's work) and dated 2026-06-22. go forth and parse those args, you gorgeous thing 🎀👑