package yojson

  1. Overview
  2. Docs

Module YojsonSource

The Yojson library provides runtime functions for reading and writing JSON data from OCaml. It addresses a few shortcomings of its predecessor json-wheel and is about twice as fast (2.7x reading, 1.3x writing; results may vary). The design goals of Yojson are the following:

  • Reducing inter-package dependencies by the use of polymorphic variants for the JSON tree type.
  • Allowing type-aware serializers/deserializers to read and write directly without going through a generic JSON tree, for efficiency purposes. Readers and writers of all JSON syntaxic elements are provided but are undocumented and meant to be used by generated OCaml code.
  • Distinguishing between ints and floats.
  • Providing optional extensions of the JSON syntax. These extensions include comments, arbitrary strings, optional quotes around field names, tuples and variants.
  • author Martin Jambon

Shared types and functions

Sourceval version : string
Sourceexception Json_error of string
Sourceval json_error : string -> 'a
Sourcetype lexer_state = {
  1. buf : Bi_outbuf.t;
    (*

    Buffer used to accumulate substrings

    *)
  2. mutable lnum : int;
    (*

    Current line number (counting from 1)

    *)
  3. mutable bol : int;
    (*

    Absolute position of the first character of the current line (counting from 0)

    *)
  4. mutable fname : string option;
    (*

    Name referencing the input file in error messages

    *)
}
Sourcemodule Lexer_state : sig ... end
Sourceval init_lexer : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> unit -> lexer_state

Create a fresh lexer_state record.

Basic JSON tree type

Sourcemodule Basic : sig ... end

This module supports standard JSON nodes only, i.e. no special syntax for variants or tuples as supported by Yojson.Safe. Arbitrary integers are not supported as they must all fit within the standard OCaml int type (31 or 63 bits depending on the platform).

Multipurpose JSON tree type

Sourcemodule Safe : sig ... end

This module supports a specific syntax for variants and tuples in addition to the standard JSON nodes. Arbitrary integers are supported and represented as a decimal string using `Intlit when they cannot be represented using OCaml's int type.

JSON tree type with literal int/float/string leaves

Sourcemodule Raw : sig ... end

Ints, floats and strings literals are systematically preserved using `Intlit, `Floatlit and `Stringlit. This module also supports the specific syntax for variants and tuples supported by Yojson.Safe.

Supertype of all JSON tree types

Type of the JSON tree

Sourcetype json = [
  1. | `Null
  2. | `Bool of bool
  3. | `Int of int
  4. | `Intlit of string
  5. | `Float of float
  6. | `Floatlit of string
  7. | `String of string
  8. | `Stringlit of string
  9. | `Assoc of (string * json) list
  10. | `List of json list
  11. | `Tuple of json list
  12. | `Variant of string * json option
]

All possible cases defined in Yojson:

  • `Null: JSON null
  • `Bool of bool: JSON boolean
  • `Int of int: JSON number without decimal point or exponent.
  • `Intlit of string: JSON number without decimal point or exponent, preserved as a string.
  • `Float of float: JSON number, Infinity, -Infinity or NaN.
  • `Floatlit of string: JSON number, Infinity, -Infinity or NaN, preserved as a string.
  • `String of string: JSON string. Bytes in the range 128-255 are preserved as-is without encoding validation for both reading and writing.
  • `Stringlit of string: JSON string literal including the double quotes.
  • `Assoc of (string * json) list: JSON object.
  • `List of json list: JSON array.
  • `Tuple of json list: Tuple (non-standard extension of JSON). Syntax: ("abc", 123).
  • `Variant of (string * json option): Variant (non-standard extension of JSON). Syntax: <"Foo"> or <"Bar":123>.
Sourcetype json_max = json

JSON writers

Sourceval to_string : ?buf:Bi_outbuf.t -> ?len:int -> ?std:bool -> json -> string

Write a compact JSON value to a string.

  • parameter buf

    allows to reuse an existing buffer created with Bi_outbuf.create. The buffer is cleared of all contents before starting and right before returning.

  • parameter len

    initial length of the output buffer.

  • parameter std

    use only standard JSON syntax, i.e. convert tuples and variants into standard JSON (if applicable), refuse to print NaN and infinities, require the root node to be either an object or an array. Default is false.

Sourceval to_channel : ?buf:Bi_outbuf.t -> ?len:int -> ?std:bool -> out_channel -> json -> unit

Write a compact JSON value to a channel.

  • parameter buf

    allows to reuse an existing buffer created with Bi_outbuf.create_channel_writer on the same channel. buf is flushed right before to_channel returns but the out_channel is not flushed automatically.

See to_string for the role of the other optional arguments.

Sourceval to_output : ?buf:Bi_outbuf.t -> ?len:int -> ?std:bool -> < output : string -> int -> int -> int.. > -> json -> unit

Write a compact JSON value to an OO channel.

  • parameter buf

    allows to reuse an existing buffer created with Bi_outbuf.create_output_writer on the same channel. buf is flushed right before to_output returns but the channel itself is not flushed automatically.

See to_string for the role of the other optional arguments.

Sourceval to_file : ?len:int -> ?std:bool -> string -> json -> unit

Write a compact JSON value to a file. See to_string for the role of the optional arguments.

Sourceval to_outbuf : ?std:bool -> Bi_outbuf.t -> json -> unit

Write a compact JSON value to an existing buffer. See to_string for the role of the optional argument.

Sourceval stream_to_string : ?buf:Bi_outbuf.t -> ?len:int -> ?std:bool -> json Stream.t -> string

Write a newline-separated sequence of compact one-line JSON values to a string. See to_string for the role of the optional arguments.

Sourceval stream_to_channel : ?buf:Bi_outbuf.t -> ?len:int -> ?std:bool -> out_channel -> json Stream.t -> unit

Write a newline-separated sequence of compact one-line JSON values to a channel. See to_channel for the role of the optional arguments.

Sourceval stream_to_file : ?len:int -> ?std:bool -> string -> json Stream.t -> unit

Write a newline-separated sequence of compact one-line JSON values to a file. See to_string for the role of the optional arguments.

Sourceval stream_to_outbuf : ?std:bool -> Bi_outbuf.t -> json Stream.t -> unit

Write a newline-separated sequence of compact one-line JSON values to an existing buffer. See to_string for the role of the optional arguments.

Miscellaneous

Sourceval sort : json -> json

Sort object fields (stable sort, comparing field names and treating them as byte sequences)

JSON pretty-printing

Sourceval pretty_format : ?std:bool -> json -> Easy_format.t

Convert into a pretty-printable tree. See to_string for the role of the optional std argument.

Sourceval pretty_print : ?std:bool -> Format.formatter -> json -> unit

Pretty-print into a Format.formatter. See to_string for the role of the optional std argument.

  • since 1.3.1
Sourceval pretty_to_string : ?std:bool -> json -> string

Pretty-print into a string. See to_string for the role of the optional std argument.

Sourceval pretty_to_channel : ?std:bool -> out_channel -> json -> unit

Pretty-print to a channel. See to_string for the role of the optional std argument.