otoml 1.0.5 · OCaml Package

OTOML is a TOML parsing, manipulation, and pretty-printing library.

Fully compliant with the TOML 1.0.0 specification
Makes it easy to look up and modify deeply nested table fields
Provides user-friendly syntax error reporting
Avoids external dependencies, but provides a way for everyone to bring their own

Usage example:

(* Parsing a TOML document with syntax errors. *)
utop # let t = Otoml.Parser.from_string_result "foo.bar.baz = " ;;
val t : (Otoml.t, string) result = Error
  "Syntax error on line 1, character 15: Malformed key-value pair (missing value?)"

(* Parsing a valid document. *)
utop# let t = Otoml.Parser.from_string "foo.bar.baz = 42" ;;
val t : Otoml.t = Otoml.TomlTable [("foo",
  Otoml.TomlTable [("bar",
    Otoml.TomlTable [("baz", Otoml.TomlInteger 42)])])]

(* Retrieving a nested field, exact type match is expected by detault. *)
utop # Otoml.find_result t (Otoml.get_string) ["foo"; "bar"; "baz"] ;;
- : (string, string) result =
Error "Unexpected TOML value type at key foo.bar.baz: value must be a string, found integer"

(* Retrieving a field in non-strict mode (automatic type conversion). *)
utop # Otoml.find_result t (Otoml.get_string ~strict:false) ["foo"; "bar"; "baz"] ;;
- : (string, string) result = Ok "42"

(* Updating a field. *)
utop # Otoml.update_result t ["foo"; "bar"; "baz"] (Some (Otoml.string "quux")) ;;
- : (Otoml.t, string) result = Ok
 (Otoml.TomlTable [("foo",
   Otoml.TomlTable [("bar", Otoml.TomlTable [("baz", Otoml.TomlString "quux")])])])

(* Deleting a field. *)
utop # Otoml.update_result t ["foo"; "bar"; "baz"] None ;;
- : (Otoml.t, string) result =
Ok (Otoml.TomlTable [("foo", Otoml.TomlTable [("bar", Otoml.TomlTable [])])])

Default TOML implementation

The default implementation is meant to cover the majority of use cases without using any dependencies outside of the OCaml standard library.

Numeric values are represented as native 31/63-bit integers and floats.

Dates are represented as strings, with only superficial validation. For example, a completely implausible date like 1993-09-935 is rejected by the parser, but 1993-02-29 is accepted despite the fact that 1993 wasn't a leap year.

If your use case requires big numbers or full-fledged datetime support, you can build a custom implementation using the functorial interface (Base.Make).

type toml_integer = int

type toml_float = float

type toml_date = string

Exceptions

exception Key_error of string

Raised when a table field does not exist.

exception Type_error of string

Raised when a TOML value type is not what an accessor or another function expects.

exception Parse_error of (int * int) option * string

Raised when the parser encounters invalid TOML syntax. The first member of the tuple is the source file position (line and column).

exception Duplicate_key of string

Raised when a table field or a table name is defined twice, which is prohibited to the TOML standard.

type t =

| TomlString of string
| TomlInteger of toml_integer
| TomlFloat of toml_float
| TomlBoolean of bool
| TomlOffsetDateTime of toml_date
| TomlLocalDateTime of toml_date
| TomlLocalDate of toml_date
| TomlLocalTime of toml_date
| TomlArray of t list
| TomlTable of (string * t) list
| TomlInlineTable of (string * t) list
| TomlTableArray of t list

module Printer : sig ... end

module Parser : sig ... end

Constructors

Constructors create TOML values from OCaml values.

val string : string -> t

val integer : toml_integer -> t

val float : toml_float -> t

val boolean : bool -> t

val offset_datetime : toml_date -> t

val local_datetime : toml_date -> t

val local_date : toml_date -> t

val local_time : toml_date -> t

val array : t list -> t

val table : (string * t) list -> t

val inline_table : (string * t) list -> t

Accessors

Accessors can be used by themselves on TOML values, or passed to high-level interface functions such as find.

By default they expect a strict match, e.g. get_string fails on values other than TomlString _. However, they all provide a boolean ~strict argument that enables type conversion when set to false. Not all types can be converted between each other, so ~strict:false does not prevent all type errors.

All accessors will raise Type_error exception if type conversion is disabled or fails. High-level interface functions handle those exceptions, so you don't need to handle it.

If you want to use accessors directly on TOML values and you want option or result values instead of exceptions, you can use get_opt and get_result combinators.

val get_value : t -> t

The trivial accessor that returns the unwrapped TOML value.

val get_table : t -> (string * t) list

val get_table_values : (t -> 'a) -> t -> (string * 'a) list

Unwraps a table and applies an accessor to the values of its fields, useful for unwrapping tables with homogenous field types in a single step.

val get_array : ?strict:bool -> (t -> 'a) -> t -> 'a list

Converts a TOML array to a list of OCaml values by applying an accessor function to each of them.

For example, if you want to retrieve an array of strings, you can use get_array get_string toml_value.

In non-strict mode, forces a value x to a single-item array [x].

Note that the strict flag is not passed to the accessor. If you want the accessor to also attempt type conversion on the array values, you should specify it explicitly: get_array ~strict:false (get_string ~strict:false) toml_value.

val get_string : ?strict:bool -> t -> string

In non-strict mode, converts integer, float, boolean, and datetime values to strings. Trying to convert an array or a table to string will raise Type_error.

val get_integer : ?strict:bool -> t -> toml_integer

In non-strict mode, converts string and boolean values to integers.

Strings are parsed as integers, true is converted to 1, false is converted to 0, and floats are truncated.

val get_float : ?strict:bool -> t -> toml_float

In non-strict mode, converts string, boolean, and integer values to floats.

val get_boolean : ?strict:bool -> t -> bool

In non-strict mode, converts integer, float, and string values to booleans.

The conversion logic mimics "truth values" in dynamically typed languages. Empty strings, numeric values 0 (integer) and 0.0 (float), empty arrays and tables are treated as false, everything else is true.

val get_offset_datetime : ?strict:bool -> t -> toml_date

In non-strict mode, these functions will try to convert strings to dates.

In the default implementation dates are represented as strings, so the conversion is a no-op.

They will handle the Stdlib.Failure exception raised by string to datetime conversion functions. Thus if you supply your own datetime module to the functorial interface, you may want to catch exceptions raised by your library of choice and re-raise them as Failure.

val get_local_datetime : ?strict:bool -> t -> toml_date

val get_local_date : ?strict:bool -> t -> toml_date

val get_local_time : ?strict:bool -> t -> toml_date

val get_datetime : t -> toml_date

val get_date : t -> toml_date

Combinators

These combinators are mainly useful for unwrapping standalong TOML values by hand. They handle the Type_error exception and return None or Error msg when it occurs.

The high-level interface functions handle exceptions raised by accessors themselves.

val get_opt : ('a -> 'b) -> 'a -> 'b option

val get_result : ('a -> 'b) -> 'a -> ('b, string) Stdlib.result

High-level interface

val path_exists : t -> string list -> bool

Returns true if there is a value at the specified path in a table.

For the purpose of this function, an empty table does exist, i.e. if you have foo.bar = {}, then path_exists t ["foo"; "bar"] is true.

val list_table_keys : t -> string list

Returns a list of all keys of a table, in their original order.

raises {!Type_error}
is the value is not a table.

val list_table_keys_exn : t -> string list

val list_table_keys_result : t -> (string list, string) Stdlib.result

val find : t -> (t -> 'a) -> string list -> 'a

Looks up a value in a table and unwraps it using an accessor function.

raises {!Key_error}
if there's no such key path in the table.

raises {!Type_error}
if the value itself is not a table or the field value is not what the accessor expects.

val find_exn : t -> (t -> 'a) -> string list -> 'a

val find_opt : t -> (t -> 'a) -> string list -> 'a option

val find_or : default:'a -> t -> (t -> 'a) -> string list -> 'a

val find_result : t -> (t -> 'a) -> string list -> ('a, string) Stdlib.result

val update : ?use_inline_tables:bool -> t -> string list -> t option -> t

Updates a table field at a specified path.

Passing Some toml_value inserts a new value or replaces an existing value.

If a key path partially does not exist, additional tables are created as needed. For example, update (TomlTable []) ["foo"; "bar"] (Some (TomlString "baz"))] will produce TomlTable [("foo", TomlTable [("bar", TomlString "baz")])].

The use_inline_tables flag determines whether automatically-created missing tables will be normal or inline tables.

Passing None as the argument will delete the field at the specified path. It's safe to attempt deleting values at paths that don't exist: there will be no error and the original TOML will be returned unchanged.

val update_result : 
  ?use_inline_tables:bool ->
  t ->
  string list ->
  t option ->
  (t, string) Stdlib.result

Utility functions

val string_of_path : string list -> string

Makes a printable representation of a table key path, for example, ["foo"; "bar baz"; "quux"] gives foo."bar baz".quux.

module Helpers : sig ... end

The functorial interface

OTOML provides a way to build your own TOML implementation by plugging your own modules for working with numbers and dates into the functor.

module Base : sig ... end

package otoml