package otoml

  1. Overview
  2. Docs

Module Base.MakeSource

Parameters

module N : TomlNumber
module D : TomlDate

Signature

Sourcetype toml_integer = N.int
Sourcetype toml_float = N.float
Sourcetype toml_date = D.t

Exceptions

Sourceexception Key_error of string

Raised when a table field does not exist.

Sourceexception Type_error of string

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

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

Sourcetype t =
  1. | TomlString of string
  2. | TomlInteger of toml_integer
  3. | TomlFloat of toml_float
  4. | TomlBoolean of bool
  5. | TomlOffsetDateTime of toml_date
  6. | TomlLocalDateTime of toml_date
  7. | TomlLocalDate of toml_date
  8. | TomlLocalTime of toml_date
  9. | TomlArray of t list
  10. | TomlTable of (string * t) list
  11. | TomlInlineTable of (string * t) list
  12. | TomlTableArray of t list
Sourcemodule Printer : sig ... end
Sourcemodule Parser : sig ... end

Constructors

Constructors create TOML values from OCaml values.

Sourceval string : string -> t
Sourceval integer : toml_integer -> t
Sourceval float : toml_float -> t
Sourceval boolean : bool -> t
Sourceval offset_datetime : toml_date -> t
Sourceval local_datetime : toml_date -> t
Sourceval local_date : toml_date -> t
Sourceval local_time : toml_date -> t
Sourceval array : t list -> t
Sourceval table : (string * t) list -> t
Sourceval 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.

Sourceval get_value : t -> t

The trivial accessor that returns the unwrapped TOML value.

Sourceval get_table : t -> (string * t) list
Sourceval 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.

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

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

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

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

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

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

Sourceval get_offset_datetime : t -> toml_date
Sourceval get_local_datetime : t -> toml_date
Sourceval get_datetime : t -> toml_date
Sourceval get_local_date : t -> toml_date
Sourceval get_date : t -> toml_date
Sourceval get_local_time : 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.

Sourceval get_opt : ('a -> 'b) -> 'a -> 'b option
Sourceval get_result : ('a -> 'b) -> 'a -> ('b, string) result

High-level interface

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

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

Sourceval list_table_keys_exn : t -> string list
Sourceval list_table_keys_result : t -> (string list, string) result
Sourceval 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.

Sourceval find_exn : t -> (t -> 'a) -> string list -> 'a
Sourceval find_opt : t -> (t -> 'a) -> string list -> 'a option
Sourceval find_or : default:'a -> t -> (t -> 'a) -> string list -> 'a
Sourceval find_result : t -> (t -> 'a) -> string list -> ('a, string) result
Sourceval 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.

Sourceval update_result : ?use_inline_tables:bool -> t -> string list -> t option -> (t, string) result
Utility functions
Sourceval 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.