Module Jsonm

module Jsonm: sig .. end

JSON data model

type lexeme = [ `Ae
       | `As
       | `Bool of bool
       | `Float of float
       | `Name of string
       | `Null
       | `Oe
       | `Os
       | `String of string ] 

  json = object / array
object = `Os *member `Oe
member = (`Name s) value 
 array = `As *value `Ae
 value = `Null / `Bool b / `Float f / `String s / object / array  

val pp_lexeme : Format.formatter -> [< lexeme ] -> unit

Decode

type error = [ `Expected of
           [ `Aval of bool
           | `Comment
           | `Eoi
           | `Json
           | `Name
           | `Name_sep
           | `Omem of bool
           | `Value ]
       | `Illegal_BOM
       | `Illegal_bytes of string
       | `Illegal_escape of
           [ `Lone_hi_surrogate of int
           | `Lone_lo_surrogate of int
           | `Not_esc_uchar of int
           | `Not_hex_uchar of int
           | `Not_lo_surrogate of int ]
       | `Illegal_literal of string
       | `Illegal_number of string
       | `Illegal_string_uchar of int
       | `Unclosed of [ `As | `Comment | `Os | `String ] ] 

val pp_error : Format.formatter -> [< error ] -> unit

type encoding = [ `UTF_16 | `UTF_16BE | `UTF_16LE | `UTF_8 ] 

type src = [ `Channel of Pervasives.in_channel | `Manual | `String of string ] 

type decoder 

val decoder : ?encoding:[< encoding ] -> [< src ] -> decoder

val decode : decoder ->
       [> `Await | `End | `Error of error | `Lexeme of lexeme ]

val decoded_range : decoder -> (int * int) * (int * int)

val decoder_encoding : decoder -> encoding

val decoder_src : decoder -> src

Encode

type dst = [ `Buffer of Buffer.t | `Channel of Pervasives.out_channel | `Manual ] 

type encoder 

val encoder : ?minify:bool -> [< dst ] -> encoder

val encode : encoder ->
       [< `Await | `End | `Lexeme of lexeme ] -> [ `Ok | `Partial ]

val encoder_dst : encoder -> dst

val encoder_minify : encoder -> bool

Manual sources and destinations

module Manual: sig .. end

Uncut codec

module Uncut: sig .. end

Limitations

Decode

Decoders parse valid JSON with the following limitations:

• JSON numbers are represented with OCaml float values. This means that it can only represent integers exactly in the in the interval [-2⁵³;2⁵³]. This is equivalent to the contraints JavaScript has.
• A superset of JSON numbers is parsed. After having seen a minus or a digit, including zero, Pervasives.float_of_string, is used. In particular this parses number with leading zeros, which are specifically prohibited by the standard.
• Strings returned by `String, `Name, `White and `Comment are limited by Sys.max_string_length. There is no built-in protection against the fact that the internal OCaml Buffer.t value may raise Failure on Jsonm.decode. This should however only be a problem on 32-bits platforms if your strings are greater than 16Mo.

Position tracking assumes that each decoded Unicode scalar value has a column width of 1. The same assumption may not be made by the display program (e.g. for emacs' compilation mode you need to set compilation-error-screen-columns to nil).

The newlines LF (U+000A), CR (U+000D), and CRLF are all normalized to LF internally. This may have an impact in some corner `Error cases. For example the invalid escape sequence <U+005C,U+000D> in a string will be reported as being `Illegal_escape (`Not_esc_uchar 0x000A).

Encode

Encoders produce valid JSON provided the client ensures that the following holds.

• All the strings given to the encoder must be valid UTF-8 and immutable. Characters that need to be escaped are automatically escaped by Jsonm.
• `Float lexemes must not be, Pervasives.nan, Pervasives.infinity or Pervasives.neg_infinity. They are encoded with the format string "%.16g", this allows to roundtrip all the integers that can be precisely represented in OCaml float values, i.e. the integers in the interval [-2⁵³;2⁵³]. This is equivalent to the constraints JavaScript has.
• If the uncut codec is used `White must be made of JSON whitespace and `Comment must never be encoded.

Error recovery

After a decoding error, if best-effort decoding is performed. The following happens before continuing:

• `Illegal_BOM, the initial BOM is skipped.
• `Illegal_bytes, `Illegal_escape, `Illegal_string_uchar, a Unicode replacement character (U+FFFD) is substituted to the illegal sequence.
• `Illegal_literal, `Illegal_number the corresponding `Lexeme is skipped.
• `Expected r, input is discarded until a synchronyzing lexeme that depends on r is found.
• `Unclosed, the end of input is reached, further decodes will be `End

Examples

Trip

The result of trip src dst has the JSON from src written on dst.

let trip ?encoding ?minify 
    (src : [`Channel of in_channel | `String of string])
    (dst : [`Channel of out_channel | `Buffer of Buffer.t])
  = 
  let rec loop d e = match Jsonm.decode d with 
  | `Lexeme _ as v -> ignore (Jsonm.encode e v); loop d e 
  | `End -> ignore (Jsonm.encode e `End); `Ok
  | `Error err -> `Error (Jsonm.decoded_range d, err)
  | `Await -> assert false
  in
  let d = Jsonm.decoder ?encoding src in 
  let e = Jsonm.encoder ?minify dst in
  loop d e

let trip_fd ?encoding ?minify
    (fdi : Unix.file_descr) 
    (fdo : Unix.file_descr) 
  = 
  let rec encode fd s e v = match Jsonm.encode e v with `Ok -> () 
  | `Partial -> 
      let rec unix_write fd s j l = 
        let rec write fd s j l = try Unix.single_write fd s j l with 
        | Unix.Unix_error (Unix.EINTR, _, _) -> write fd s j l 
        in
        let wc = write fd s j l in 
        if wc < l then unix_write fd s (j + wc) (l - wc) else ()
      in
      unix_write fd s 0 (String.length s - Jsonm.Manual.dst_rem e); 
      Jsonm.Manual.dst e s 0 (String.length s);
      encode fd s e `Await
  in
  let rec loop fdi fdo ds es d e = match Jsonm.decode d with 
  | `Lexeme _ as v -> encode fdo es e v; loop fdi fdo ds es d e 
  | `End -> encode fdo es e `End; `Ok
  | `Error err -> `Error (Jsonm.decoded_range d, err)
  | `Await ->
      let rec unix_read fd s j l = try Unix.read fd s j l with 
      | Unix.Unix_error (Unix.EINTR, _, _) -> unix_read fd s j l 
      in
      let rc = unix_read fdi ds 0 (String.length ds) in 
      Jsonm.Manual.src d ds 0 rc; loop fdi fdo ds es d e 
  in
  let ds = String.create 65536 (* UNIX_BUFFER_SIZE in 4.0.0 *) in
  let es = String.create 65536 (* UNIX_BUFFER_SIZE in 4.0.0 *) in
  let d = Jsonm.decoder ?encoding `Manual in 
  let e = Jsonm.encoder ?minify `Manual in
  Jsonm.Manual.dst e es 0 (String.length es);
  loop fdi fdo ds es d e

Member selection

The result of memsel names src is the list of string values of members of src that have their name in names. In this example, decoding errors are silently ignored.

let memsel ?encoding names 
    (src : [`Channel of in_channel | `String of string])
  = 
  let rec loop acc names d = match Jsonm.decode d with 
  | `Lexeme (`Name n) when List.mem n names -> 
      begin match Jsonm.decode d with 
      | `Lexeme (`String s) -> loop (s :: acc) names d
      | _ -> loop acc names d
      end
  | `Lexeme _ | `Error _ -> loop acc names d
  | `End -> List.rev acc 
  | `Await -> assert false
  in
  loop [] names (Jsonm.decoder ?encoding src)

Generic JSON representation

A generic OCaml representation of JSON text is the following one.

type json = 
  [ `Null | `Bool of bool | `Float of float| `String of string
  | `A of json list | `O of (string * json) list ]

exception Escape of ((int * int) * (int * int)) * Jsonm.error

let json_of_src ?encoding 
    (src : [`Channel of in_channel | `String of string])
  =
  let dec d = match Jsonm.decode d with 
  | `Lexeme l -> l
  | `Error e -> raise (Escape (Jsonm.decoded_range d, e))
  | `End | `Await -> assert false
  in
  let rec value v k d = match v with 
  | `Os -> obj [] k d  | `As -> arr [] k d
  | `Null | `Bool _ | `String _ | `Float _ as v -> k v d 
  | _ -> assert false
  and arr vs k d = match dec d with 
  | `Ae -> k (`A (List.rev vs)) d
  | v -> value v (fun v -> arr (v :: vs) k) d
  and obj ms k d = match dec d with 
  | `Oe -> k (`O (List.rev ms)) d
  | `Name n -> value (dec d) (fun v -> obj ((n, v) :: ms) k) d
  | _ -> assert false
  in
  let d = Jsonm.decoder ?encoding src in
  try `JSON (value (dec d) (fun v _ -> v) d) with 
  | Escape (r, e) -> `Error (r, e)

let json_to_dst ~minify 
    (dst : [`Channel of out_channel | `Buffer of Buffer.t ]) 
    (json : json)
  =
  let enc e l = ignore (Jsonm.encode e (`Lexeme l)) in
  let rec value v k e = match v with 
  | `A vs -> arr vs k e 
  | `O ms -> obj ms k e 
  | `Null | `Bool _ | `Float _ | `String _ as v -> enc e v; k e
  and arr vs k e = enc e `As; arr_vs vs k e
  and arr_vs vs k e = match vs with 
  | v :: vs' -> value v (arr_vs vs' k) e 
  | [] -> enc e `Ae; k e
  and obj ms k e = enc e `Os; obj_ms ms k e
  and obj_ms ms k e = match ms with 
  | (n, v) :: ms -> enc e (`Name n); value v (obj_ms ms k) e
  | [] -> enc e `Oe; k e
  in
  let e = Jsonm.encoder ~minify dst in
  let finish e = ignore (Jsonm.encode e `End) in
  match json with `A _ | `O _ as json -> value json finish e
  | _ -> invalid_arg "invalid json text"