Previous  Up  Next

Module Yojson.Safe


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

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

Type of the JSON tree


type json = [ `Assoc of (string * json) list
       | `Bool of bool
       | `Float of float
       | `Int of int
       | `Intlit of string
       | `List of json list
       | `Null
       | `String of string
       | `Tuple of json list
       | `Variant of string * json option ]
All possible cases defined in Yojson: 
val to_basic : json -> Yojson.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


val to_string : ?buf:Bi_outbuf.t -> ?len:int -> ?std:bool -> json -> string
Write a compact JSON value to a string.
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.
len : initial length of the output buffer.
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.
val to_channel : ?buf:Bi_outbuf.t ->
       ?len:int -> ?std:bool -> Pervasives.out_channel -> json -> unit
Write a compact JSON value to a channel.
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.

val 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.
val 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.
val 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.
val stream_to_channel : ?buf:Bi_outbuf.t ->
       ?len:int ->
       ?std:bool -> Pervasives.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.
val 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.
val 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.

JSON pretty-printing


val 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.
See also Easy-format
val pretty_to_string : ?std:bool -> json -> string
Pretty-print into a string. See to_string for the role of the optional std argument.
val pretty_to_channel : ?std:bool -> Pervasives.out_channel -> json -> unit
Pretty-print to a channel. See to_string for the role of the optional std argument.
val prettify : ?std:bool -> string -> string
Combined parser and pretty-printer. See to_string for the role of the optional std argument.
val compact : ?std:bool -> string -> string
Combined parser and printer. See to_string for the role of the optional std argument.

JSON readers


val from_string : ?buf:Bi_outbuf.t -> ?fname:string -> ?lnum:int -> string -> json
Read a JSON value from a string.
buf : use this buffer at will during parsing instead of creating a new one.
fname : data file name to be used in error messages. It does not have to be a real file.
lnum : number of the first line of input. Default is 1.
val from_channel : ?buf:Bi_outbuf.t ->
       ?fname:string -> ?lnum:int -> Pervasives.in_channel -> json
Read a JSON value from a channel. See from_string for the meaning of the optional arguments.
val 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.
type lexer_state = Yojson.Lexer_state.t = {
   buf : Bi_outbuf.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: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.
val 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.
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 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.
val stream_from_channel : ?buf:Bi_outbuf.t ->
       ?fin:(unit -> unit) ->
       ?fname:string ->
       ?lnum:int -> Pervasives.in_channel -> json Stream.t
Input a sequence of JSON values from a channel. Whitespace between JSON values is fine but not required.
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.

See from_string for the meaning of the other optional arguments.

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

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

See stream_from_channel for the meaning of the optional fin argument.

type json_line = [ `Exn of exn | `Json of json ]
The type of values resulting from a parsing attempt of a JSON value.
val linestream_from_channel : ?buf:Bi_outbuf.t ->
       ?fin:(unit -> unit) ->
       ?fname:string ->
       ?lnum:int -> Pervasives.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.

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