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:
#
buf
| : Bi_outbuf.t | ; | (* | Buffer used to accumulate substrings | *) |
#
mutable lnum
| : int | ; | (* | Current line number (counting from 1) | *) |
#
mutable bol
| : int | ; | (* | Absolute position of the first character of the current line (counting from 0) | *) |
#
mutable fname
| : string option | ; | (* | Name referencing the input file in error messages | *) |
Create a fresh lexer_state record.
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).
The main advantage of this module is its simplicity.
All possible cases defined in Yojson:
("abc", 123)
.<"Foo">
or <"Bar":123>
.Write a compact JSON value to a string.
Bi_outbuf.create
. The buffer is cleared of all contents
before starting and right before returning.
false
.
Write a compact JSON value to a channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to an OO channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to a file.
See to_string
for the role of the optional arguments.
Write a newline-separated sequence of compact one-line JSON values to
a channel.
See to_channel
for the role of the optional arguments.
Convert into a pretty-printable tree.
See to_string
for the role of the optional std
argument.
Pretty-print into a string.
See to_string
for the role of the optional std
argument.
Pretty-print to a channel.
See to_string
for the role of the optional std
argument.
Combined parser and pretty-printer.
See to_string
for the role of the optional std
argument.
Combined parser and printer.
See to_string
for the role of the optional std
argument.
Read a JSON value from a string.
Read a JSON value from a channel.
See from_string
for the meaning of the optional arguments.
#
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.
This alias is provided for backward compatibility. New code should use Yojson.init_lexer directly.
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.
Input a sequence of JSON values from a channel. Whitespace between JSON values is fine but not required.
from_string
for the meaning of the other optional arguments.
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.
The type of values resulting from a parsing attempt of a JSON value.
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.
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.
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.
Here is some sample JSON data:
{ "id": "398eb027", "name": "John Doe", "pages": [ { "id": 1, "title": "The Art of Flipping Coins", "url": "http://example.com/398eb027/1" }, { "id": 2, "deleted": true }, { "id": 3, "title": "Artichoke Salad", "url": "http://example.com/398eb027/3" }, { "id": 4, "title": "Flying Bananas", "url": "http://example.com/398eb027/4" } ] }
In order to extract the "id" field, assuming it is mandatory, we would use the following OCaml code that operates on single JSON nodes:
open Yojson.Basic.Util ... let id = json |> member "id" |> to_string in ...
In order to extract all the "title" fields, we would write the following OCaml code that operates on lists of JSON nodes, skipping undefined nodes and nodes of unexpected type:
open Yojson.Basic.Util let extract_titles (json : Yojson.Basic.json) : string list = [json] |> filter_member "pages" |> flatten |> filter_member "title" |> filter_string
Raised when the JSON value is not of the correct type to support an
operation, e.g. member
on an `Int
. The string message explains the
mismatch.
Raised when the equivalent JavaScript operation on the JSON value would return undefined. Currently this only happens when an array index is out of bounds.
Forward pipe operator; useful for composing JSON access functions without too many parentheses
Extract Some
boolean value,
return None
if the value is null,
or raise Type_error
otherwise.
Extract Some
number,
return None
if the value is null,
or raise Type_error
otherwise.
Extract a float value or raise Type_error
.
to_number
is generally preferred as it also works with int literals.
Extract Some
float value,
return None
if the value is null,
or raise Type_error
otherwise.
to_number_option
is generally preferred as it also works
with int literals.
Extract Some
int from a JSON int,
return None
if the value is null,
or raise Type_error
otherwise.
Extract Some
string from a JSON string,
return None
if the value is null,
or raise Type_error
otherwise.
The following functions operate on lists of JSON nodes. None of them raises an exception when a certain kind of node is expected but no node or the wrong kind of node is found. Instead of raising an exception, nodes that are not as expected are simply ignored.
filter_map f l
maps each element of the list l
to an optional value
using function f
and unwraps the resulting values.
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.
All possible cases defined in Yojson:
("abc", 123)
.<"Foo">
or <"Bar":123>
.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"
Write a compact JSON value to a string.
Bi_outbuf.create
. The buffer is cleared of all contents
before starting and right before returning.
false
.
Write a compact JSON value to a channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to an OO channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to a file.
See to_string
for the role of the optional arguments.
Write a newline-separated sequence of compact one-line JSON values to
a channel.
See to_channel
for the role of the optional arguments.
Convert into a pretty-printable tree.
See to_string
for the role of the optional std
argument.
Pretty-print into a string.
See to_string
for the role of the optional std
argument.
Pretty-print to a channel.
See to_string
for the role of the optional std
argument.
Combined parser and pretty-printer.
See to_string
for the role of the optional std
argument.
Combined parser and printer.
See to_string
for the role of the optional std
argument.
Read a JSON value from a string.
Read a JSON value from a channel.
See from_string
for the meaning of the optional arguments.
#
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.
This alias is provided for backward compatibility. New code should use Yojson.init_lexer directly.
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.
Input a sequence of JSON values from a channel. Whitespace between JSON values is fine but not required.
from_string
for the meaning of the other optional arguments.
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.
The type of values resulting from a parsing attempt of a JSON value.
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.
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.
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.
All possible cases defined in Yojson:
("abc", 123)
.<"Foo">
or <"Bar":123>
.Write a compact JSON value to a string.
Bi_outbuf.create
. The buffer is cleared of all contents
before starting and right before returning.
false
.
Write a compact JSON value to a channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to an OO channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to a file.
See to_string
for the role of the optional arguments.
Write a newline-separated sequence of compact one-line JSON values to
a channel.
See to_channel
for the role of the optional arguments.
Convert into a pretty-printable tree.
See to_string
for the role of the optional std
argument.
Pretty-print into a string.
See to_string
for the role of the optional std
argument.
Pretty-print to a channel.
See to_string
for the role of the optional std
argument.
Combined parser and pretty-printer.
See to_string
for the role of the optional std
argument.
Combined parser and printer.
See to_string
for the role of the optional std
argument.
Read a JSON value from a string.
Read a JSON value from a channel.
See from_string
for the meaning of the optional arguments.
#
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.
This alias is provided for backward compatibility. New code should use Yojson.init_lexer directly.
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.
Input a sequence of JSON values from a channel. Whitespace between JSON values is fine but not required.
from_string
for the meaning of the other optional arguments.
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.
The type of values resulting from a parsing attempt of a JSON value.
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.
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.
All possible cases defined in Yojson:
("abc", 123)
.<"Foo">
or <"Bar":123>
.Write a compact JSON value to a string.
Bi_outbuf.create
. The buffer is cleared of all contents
before starting and right before returning.
false
.
Write a compact JSON value to a channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to an OO channel.
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.to_string
for the role of the other optional arguments.
Write a compact JSON value to a file.
See to_string
for the role of the optional arguments.
Write a newline-separated sequence of compact one-line JSON values to
a channel.
See to_channel
for the role of the optional arguments.
Convert into a pretty-printable tree.
See to_string
for the role of the optional std
argument.
Pretty-print into a string.
See to_string
for the role of the optional std
argument.
Pretty-print to a channel.
See to_string
for the role of the optional std
argument.