package yojson

  1. Overview
  2. Docs

Module Yojson.SafeSource

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.

This module is recommended for intensive use or OCaml-friendly use of JSON.

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. | `String of string
  7. | `Assoc of (string * json) list
  8. | `List of json list
  9. | `Tuple of json list
  10. | `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>.
Sourceval to_basic : json -> Basic.json

Tuples are converted to JSON arrays, Variants are converted to JSON strings or arrays of a string (constructor) and a json value (argument). Long integers are converted to JSON strings.

Examples:

`Tuple [ `Int 1; `Float 2.3 ]   ->    `List [ `Int 1; `Float 2.3 ]
`Variant ("A", None)            ->    `String "A"
`Variant ("B", Some x)          ->    `List [ `String "B", x ]
`Intlit "12345678901234567890"  ->    `String "12345678901234567890"

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.

Sourceval prettify : ?std:bool -> string -> string

Combined parser and pretty-printer. See to_string for the role of the optional std argument.

Sourceval compact : ?std:bool -> string -> string

Combined parser and printer. See to_string for the role of the optional std argument.

JSON readers

Sourceexception Finally of exn * exn

Exception describing a failure in both finalizer and parsing.

Sourceval from_string : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> string -> json

Read a JSON value from a string.

  • parameter buf

    use this buffer at will during parsing instead of creating a new one.

  • parameter fname

    data file name to be used in error messages. It does not have to be a real file.

  • parameter lnum

    number of the first line of input. Default is 1.

Sourceval from_channel : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> in_channel -> json

Read a JSON value from a channel. See from_string for the meaning of the optional arguments.

Sourceval from_file : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> string -> json

Read a JSON value from a file. See from_string for the meaning of the optional arguments.

Sourcetype lexer_state = Lexer_state.t = {
  1. buf : Bi_outbuf.t;
  2. mutable lnum : int;
  3. mutable bol : int;
  4. mutable fname : string option;
}

This alias is provided for backward compatibility. New code should refer to Yojson.lexer_state directly.

Sourceval init_lexer : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> unit -> lexer_state

This alias is provided for backward compatibility. New code should use Yojson.init_lexer directly.

Sourceval from_lexbuf : lexer_state -> ?stream:bool -> Lexing.lexbuf -> json

Read a JSON value from a lexbuf. A valid initial lexer_state can be created with init_lexer. See from_string for the meaning of the optional arguments.

  • parameter stream

    indicates whether more data may follow. The default value is false and indicates that only JSON whitespace can be found between the end of the JSON value and the end of the input.

Sourceval stream_from_string : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> string -> json Stream.t

Input a sequence of JSON values from a string. Whitespace between JSON values is fine but not required. See from_string for the meaning of the optional arguments.

Sourceval stream_from_channel : ?buf:Bi_outbuf.t -> ?fin:(unit -> unit) -> ?fname:string -> ?lnum:int -> in_channel -> json Stream.t

Input a sequence of JSON values from a channel. Whitespace between JSON values is fine but not required.

  • parameter fin

    finalization function executed once when the end of the stream is reached either because there is no more input or because the input could not be parsed, raising an exception.

  • raises Finally

    When the parsing and the finalizer both raised, Finally (exn, fin_exn) is raised, exn being the parsing exception and fin_exn the finalizer one.

See from_string for the meaning of the other optional arguments.

Sourceval stream_from_file : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> string -> json Stream.t

Input a sequence of JSON values from a file. Whitespace between JSON values is fine but not required.

See from_string for the meaning of the optional arguments.

Sourceval stream_from_lexbuf : lexer_state -> ?fin:(unit -> unit) -> Lexing.lexbuf -> json Stream.t

Input a sequence of JSON values from a lexbuf. A valid initial lexer_state can be created with init_lexer. Whitespace between JSON values is fine but not required.

  • raises Finally

    When the parsing and the finalizer both raised, Finally (exn, fin_exn) is raised, exn being the parsing exception and fin_exn the finalizer one.

See stream_from_channel for the meaning of the optional fin argument.

Sourcetype json_line = [
  1. | `Json of json
  2. | `Exn of exn
]

The type of values resulting from a parsing attempt of a JSON value.

Sourceval linestream_from_channel : ?buf:Bi_outbuf.t -> ?fin:(unit -> unit) -> ?fname:string -> ?lnum:int -> in_channel -> json_line Stream.t

Input a sequence of JSON values, one per line, from a channel. Exceptions raised when reading malformed lines are caught and represented using `Exn.

See stream_from_channel for the meaning of the optional fin argument. See from_string for the meaning of the other optional arguments.

Sourceval linestream_from_file : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> string -> json_line Stream.t

Input a sequence of JSON values, one per line, from a file. Exceptions raised when reading malformed lines are caught and represented using `Exn.

See stream_from_channel for the meaning of the optional fin argument. See from_string for the meaning of the other optional arguments.

Sourcemodule Util : sig ... end

This module provides combinators for extracting fields from JSON values. This approach is recommended for reading a few fields from data returned by public APIs. However for more complex applications we recommend Atdgen.