package kdl

  1. Overview
  2. Docs

Module KdlSource

The definition of a KDL document

Sourcetype value = [
  1. | `String of string
  2. | `Int of int
  3. | `RawInt of string
  4. | `Float of float
  5. | `Bool of bool
  6. | `Null
]

A KDL value.

`String can be either a regular quoted string ("string") or a "raw" string (r#"raw string"#).

Although the KDL spec does not differentiate integers and floats, a number is parsed as `Float if it is written in the e scientific notation or contains a ., same as in OCaml.

If an integer is too large for the OCaml int, the integer is parsed as `RawInt instead of `Int.

Sourcetype annot_value = string option * value

An annotated value: opt_annot * value. For example, (Some "u16", `Int 3201) is an annot_value.

Sourcetype prop = string * annot_value

A KDL property is a key-value pair.

Sourcetype node = {
  1. name : string;
  2. annot : string option;
  3. args : annot_value list;
  4. props : prop list;
  5. children : node list;
}

A KDL node.

props is an association list; the order of props is unspecified.

Sourcetype t = node list

A KDL document is a list of nodes.

Parsing

Note: the positions count unicode code points, not bytes.

Sourcetype error = string * error_loc
Sourceval show_error : error -> string
Sourceexception Parse_error of error
Sourceval from_string : ?fname:string -> string -> (t, error) result

Parse KDL from a string.

Sourceval from_string_exn : ?fname:string -> string -> t
Sourceval from_channel : ?fname:string -> in_channel -> (t, error) result

Parse KDL from a channel.

Sourceval from_channel_exn : ?fname:string -> in_channel -> t
Sourceval of_string : ?fname:string -> string -> (t, error) result

Alias for from_string.

Sourceval of_string_exn : ?fname:string -> string -> t

Alias for from_string_exn.

Helpers

Sourceval node : ?annot:string -> string -> ?args:annot_value list -> ?props:prop list -> node list -> node

node ?annot name ?args ?props children creates a node.

Sourceval arg : ?annot:string -> value -> annot_value

arg ?annot value creates an argument.

Sourceval prop : ?annot:string -> string -> value -> prop

prop ?annot name value creates a property.

Equivalence

Sourceval equal_value : value -> value -> bool
Sourceval equal_annot_value : annot_value -> annot_value -> bool
Sourceval equal_prop : prop -> prop -> bool
Sourceval equal_node : node -> node -> bool
Sourceval equal : t -> t -> bool

Sexp conversions

Sourceval sexp_of_value : [< value ] -> Sexplib0.Sexp.t
Sourceval sexp_of_annot_value : annot_value -> Sexplib0.Sexp.t
Sourceval sexp_of_prop : prop -> Sexplib0.Sexp.t
Sourceval sexp_of_node : node -> Sexplib0.Sexp.t
Sourceval sexp_of_t : t -> Sexplib0.Sexp.t

Pretty-printing

Sourceval indent : int ref

indent is a number of spaces used per indentation level. By default, indent is set to 2.

Sourceval pp_value : Format.formatter -> [< value ] -> unit

Pretty-print a value.

Sourceval pp_annot_value : Format.formatter -> annot_value -> unit

Pretty-print an annotated value.

Sourceval pp_prop : Format.formatter -> prop -> unit

Pretty-print a property.

Sourceval pp_node : Format.formatter -> node -> unit

Pretty-print a node using !indent as the indentation width for children nodes.

Sourceval pp_node_compact : Format.formatter -> node -> unit

Same as pp_node, but outputs the result in one line.

Sourceval pp : Format.formatter -> t -> unit

Pretty-print a list of nodes or a KDL document using !indent as the indentation width for children nodes.

Sourceval pp_compact : Format.formatter -> t -> unit

Same as pp, but outputs the result in one line.

Sourceval to_string : t -> string

Same as pp, but outputs the result into a string.

Sourceval show : t -> string

Alias for to_string.

Type annotations

KDL defines reserved type annotations, some of them are supported out of the box. An annotated value can be interpreted using the interpret function. If the type annotation is unknown, `Other is returned.

You can extend typed_value with custom type annotations e.g. the following way:

  type typed_value = [ Kdl.typed_value
                     | `Date of (* ... *) ]

  let interpret : _ -> typed_value = function
    | Some "date", value -> `Date ((* ... parse ISO 8601 date ... *))
    | x -> Kdl.interpret x
Sourcetype typed_value = [
  1. | `I8 of int
  2. | `I16 of int
  3. | `I32 of int32
  4. | `I64 of int64
  5. | `U8 of int
  6. | `U16 of int
  7. | `U32 of int32
  8. | `U64 of int64
  9. | `Isize of nativeint
  10. | `Usize of nativeint
  11. | `F32 of float
  12. | `F64 of float
  13. | `Base64 of bytes
  14. | `Other of string * value
  15. | `Unannotated of value
]
Sourceval interpret : annot_value -> [> typed_value ]
  • raises Failure

    if a value is invalid. For example, if the value is annotated as "u8" but exceeds the range of u8, Failure is raised.

Sourceval i8 : annot_value -> int option

Interpret a value with the "i8" type annotation as int.

Sourceval i16 : annot_value -> int option

Interpret a value with the "i16" type annotation as int.

Sourceval i32 : annot_value -> int32 option

Interpret a value with the "i32" type annotation as int32.

Sourceval i64 : annot_value -> int64 option

Interpret a value with the "i64" type annotation as int64.

Sourceval u8 : annot_value -> int option

Interpret a value with the "u8" type annotation as int.

Sourceval u16 : annot_value -> int option

Interpret a value with the "u16" type annotation as int.

Sourceval u32 : annot_value -> int32 option

Interpret a value with the "u32" type annotation as int32.

Sourceval u64 : annot_value -> int64 option

Interpret a value with the "u64" type annotation as int64.

Sourceval isize : annot_value -> nativeint option

Interpret a value with the "isize" type annotation as nativeint.

Sourceval usize : annot_value -> nativeint option

Interpret a value with the "usize" type annotation as nativeint.

Sourceval f32 : annot_value -> float option

Interpret a value with the "f32" type annotation as float. This is currently identical to f64.

Sourceval f64 : annot_value -> float option

Interpret a value with the "f64" type annotation as float.

Sourceval base64 : annot_value -> bytes option

Interpret a value with the "base64" type annotation, decoding the base64 string into bytes.

Lenses

Sourcemodule L : sig ... end

Note: These lenses are mostly meant for getting, set is generally inefficient.