package kdl

  1. Overview
  2. Docs
package kdl
Legend:
Library
Module
Module type
Parameter
Class
Class type

The definition of a KDL document

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

type annot_value = string option * value

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

type prop = string * annot_value

A KDL property is a key-value pair.

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

type t = node list

A KDL document is a list of nodes.

Parsing

type error_loc = Stdlib.Lexing.position * Stdlib.Lexing.position

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

type error = string * error_loc
val show_error : error -> string
exception Parse_error of error
val from_string : ?fname:string -> string -> (t, error) Stdlib.result

Parse KDL from a string.

val from_string_exn : ?fname:string -> string -> t
val from_channel : ?fname:string -> Stdlib.in_channel -> (t, error) Stdlib.result

Parse KDL from a channel.

val from_channel_exn : ?fname:string -> Stdlib.in_channel -> t
val of_string : ?fname:string -> string -> (t, error) Stdlib.result

Alias for from_string.

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

Alias for from_string_exn.

Helpers

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

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

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

arg ?annot value creates an argument.

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

prop ?annot name value creates a property.

Equivalence

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

Sexp conversions

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

Pretty-printing

val indent : int Stdlib.ref

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

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

Pretty-print a value.

val pp_annot_value : Stdlib.Format.formatter -> annot_value -> unit

Pretty-print an annotated value.

val pp_prop : Stdlib.Format.formatter -> prop -> unit

Pretty-print a property.

val pp_node : Stdlib.Format.formatter -> node -> unit

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

val pp_node_compact : Stdlib.Format.formatter -> node -> unit

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

val pp : Stdlib.Format.formatter -> t -> unit

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

val pp_compact : Stdlib.Format.formatter -> t -> unit

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

val to_string : t -> string

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

val 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
type 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
]
val 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.

val i8 : annot_value -> int option

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

val i16 : annot_value -> int option

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

val i32 : annot_value -> int32 option

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

val i64 : annot_value -> int64 option

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

val u8 : annot_value -> int option

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

val u16 : annot_value -> int option

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

val u32 : annot_value -> int32 option

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

val u64 : annot_value -> int64 option

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

val isize : annot_value -> nativeint option

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

val usize : annot_value -> nativeint option

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

val f32 : annot_value -> float option

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

val f64 : annot_value -> float option

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

val base64 : annot_value -> bytes option

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

Lenses

module L : sig ... end

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