cpdf 2.7 · OCaml Package

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 (31 or 63 bits depending on the platform).

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

Type of the JSON tree

type t = [

| `Null
| `Bool of bool
| `Int of int
| `Intlit of string
| `Float of float
| `String of string
| `Assoc of (string * t) list
| `List of t list
| `Tuple of t list
| `Variant of string * t 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>.

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

Pretty printer, useful for debugging

val show : t -> string

Convert value to string, useful for debugging

val equal : t -> t -> bool

equal a b is the monomorphic equality. Determines whether two JSON values are considered equal. In the case of JSON objects, the order of the keys does not matter, except for duplicate keys which will be considered equal as long as they are in the same input order.

val to_basic : t -> Basic.t

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

val to_string : 
  ?buf:Stdlib.Buffer.t ->
  ?len:int ->
  ?suf:string ->
  ?std:bool ->
  t ->
  string

Write a compact JSON value to a string.

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

parameter len
initial length of the output buffer.

parameter suf
appended to the output as a suffix, defaults to empty string.

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.

raises Json_error
if float value is not allowed in standard JSON.

val to_channel : 
  ?buf:Stdlib.Buffer.t ->
  ?len:int ->
  ?suf:string ->
  ?std:bool ->
  Stdlib.out_channel ->
  t ->
  unit

Write a compact JSON value to a channel. Note: the out_channel is not flushed by this function.

See to_string for the role of the optional arguments and raised exceptions.

val to_output : 
  ?buf:Stdlib.Buffer.t ->
  ?len:int ->
  ?suf:string ->
  ?std:bool ->
  < output : string -> int -> int -> int.. > ->
  t ->
  unit

Write a compact JSON value to an OO channel.

See to_string for the role of the optional arguments and raised exceptions.

val to_file : ?len:int -> ?std:bool -> ?suf:string -> string -> t -> unit

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

parameter suf
is a suffix appended to the output Newline by default for POSIX compliance.

val to_buffer : ?suf:string -> ?std:bool -> Stdlib.Buffer.t -> t -> unit

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

val seq_to_string : 
  ?buf:Stdlib.Buffer.t ->
  ?len:int ->
  ?suf:string ->
  ?std:bool ->
  t Stdlib.Seq.t ->
  string

Write a sequence of suf-suffixed compact one-line JSON values to a string.

parameter suf
is the suffix ouf each value written. Newline by default. See to_string for the role of the optional arguments and raised exceptions.

val seq_to_channel : 
  ?buf:Stdlib.Buffer.t ->
  ?len:int ->
  ?suf:string ->
  ?std:bool ->
  Stdlib.out_channel ->
  t Stdlib.Seq.t ->
  unit

Write a sequence of suf-suffixed compact one-line JSON values to a channel.

parameter suf
is the suffix of each value written. Newline by default. See to_channel for the role of the optional arguments and raised exceptions.

val seq_to_file : 
  ?len:int ->
  ?suf:string ->
  ?std:bool ->
  string ->
  t Stdlib.Seq.t ->
  unit

Write a sequence of suf-suffixed compact one-line JSON values to a file.

parameter suf
is the suffix of each value written. Newline by default. See to_string for the role of the optional arguments and raised exceptions.

val seq_to_buffer : 
  ?suf:string ->
  ?std:bool ->
  Stdlib.Buffer.t ->
  t Stdlib.Seq.t ->
  unit

Write a sequence of suf-suffixed compact one-line JSON values to an existing buffer.

parameter suf
is the suffix of each value written. Newline by default. See to_string for the role of the optional arguments and raised exceptions.

val write_t : Stdlib.Buffer.t -> t -> unit

Write the given JSON value to the given buffer. Provided as a writer function for atdgen.

Miscellaneous

val sort : t -> t

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

JSON pretty-printing

val pretty_print : ?std:bool -> Stdlib.Format.formatter -> t -> unit

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

raises Json_error
if float value is not allowed in standard JSON.

since 1.3.1

val pretty_to_string : ?std:bool -> t -> string

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

val pretty_to_channel : ?std:bool -> Stdlib.out_channel -> t -> unit

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

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

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

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

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

JSON readers

exception Finally of exn * exn

Exception describing a failure in both finalizer and parsing.

val from_string : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  string ->
  t

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.

raises Json_error
if parsing fails.

val from_channel : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  Stdlib.in_channel ->
  t

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

val from_file : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  string ->
  t

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

type lexer_state = Lexer_state.t = {

buf : Stdlib.Buffer.t;
mutable lnum : int;
mutable bol : int;
mutable fname : string option;

}

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

val init_lexer : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  unit ->
  lexer_state

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

val from_lexbuf : lexer_state -> ?stream:bool -> Stdlib.Lexing.lexbuf -> t

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 and raised exceptions.

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.

val seq_from_string : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  string ->
  t Stdlib.Seq.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 and raised exceptions.

val seq_from_channel : 
  ?buf:Stdlib.Buffer.t ->
  ?fin:(unit -> unit) ->
  ?fname:string ->
  ?lnum:int ->
  Stdlib.in_channel ->
  t Stdlib.Seq.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 sequence 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 and other raised exceptions.

val seq_from_file : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  string ->
  t Stdlib.Seq.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 and raised exceptions.

val seq_from_lexbuf : 
  lexer_state ->
  ?fin:(unit -> unit) ->
  Stdlib.Lexing.lexbuf ->
  t Stdlib.Seq.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 seq_from_channel for the meaning of the optional fin argument and other raised exceptions.

type json_line = [

| `Json of t
| `Exn of exn

]

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

val lineseq_from_channel : 
  ?buf:Stdlib.Buffer.t ->
  ?fin:(unit -> unit) ->
  ?fname:string ->
  ?lnum:int ->
  Stdlib.in_channel ->
  json_line Stdlib.Seq.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 seq_from_channel for the meaning of the optional fin argument. See from_string for the meaning of the other optional arguments and raised exceptions.

val lineseq_from_file : 
  ?buf:Stdlib.Buffer.t ->
  ?fname:string ->
  ?lnum:int ->
  string ->
  json_line Stdlib.Seq.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 seq_from_channel for the meaning of the optional fin argument. See from_string for the meaning of the other optional arguments and raised exceptions.

val read_t : lexer_state -> Stdlib.Lexing.lexbuf -> t

Read a JSON value from the given lexer_state and lexing buffer and return it. Provided as a reader function for atdgen.

module Util : sig ... end

This module provides combinators for extracting fields from JSON values.

package cpdf

Type of the JSON tree

JSON writers

Miscellaneous

JSON pretty-printing

JSON readers