[%%org {| #+TITLE: JSON extraction with Of_json

This library provides an applicative interface for extracting values from JSON objects with an emphasis on readability and error handling, particularly with nested values. It expects to parse values of type Jsonaf.t.

A typical use case: |}] ;;

#verbose true

open Core

module Species = struct type t = | Capybara | Dog | Cat [@@deriving of_string] end

module Kg = struct type t = Bignum.t

let of_string = Bignum.of_string end

module Years = struct type t = int

let of_int = Fn.id end

module Animal = struct type t = { weight : Kg.t ; age : Years.t ; species : Species.t ; name : string }

let of_json = [%map_open.Of_json let weight = "weight" @. number @> Kg.of_string and age = "age" @. int @> Years.of_int and species = "species" @. string @> Species.of_string and name = "name" @. string in { weight; age; species; name }] ;; end

[%%expect {| module Species : sig type t = Capybara | Dog | Cat val of_string : string -> t end module Kg : sig type t = Bignum.t val of_string : string -> t end module Years : sig type t = int val of_int : 'a -> 'a end module Animal : sig type t = { weight : Kg.t; age : int; species : Species.t; name : string; } val of_json : t Of_json.t end |}]

[%%org {| See src/helpers.mli for documentation on the API. This module is opened when you use Let_syntax with map_open or bind_open. We can use this module as follows: |}]

let order = Jsonaf.parse {| { "weight": 42.31, "age": 2, "species": "Capybara", "name": "John Smith" } |} |> Or_error.ok_exn |> Animal.of_json ;;

[%%expect {| val order : Animal.t = {Animal.weight = 42.31; age = 2; species = Species.Capybara; name = "John Smith"} |}]

[%%org {| Note that errors provide context for where the parsing went wrong. |}]

let order = Jsonaf.parse {| { "weight": 5.1234, "age": 5, "species": "Mr. Whiskers", "name": "Cat" } |} |> Or_error.ok_exn |> Animal.of_json ;;

[%%expect {| Exception: (helpers.ml.Of_json_conv_failed ("Of_json failed to convert" ("README.Species.of_string: invalid string" (value "Mr. Whiskers")) ("json context [1]" (String "Mr. Whiskers")) ("json context [0], at key [species]" (Object ((weight (Number 5.1234)) (age (Number 5)) (species (String "Mr. Whiskers")) (name (String Cat))))))) |}]

[%%org {| A popular pattern in some JSON APIs is to use mixed-type arrays to pack information more densly, particularly in websockets where there is no compression. You can use Array_as_tuple to parse information. |}] ;;

#verbose false

module Websocket_animal = struct type t = Animal.t

let of_json = let open Of_json in tuple Array_as_tuple.( let%map weight = shift @@ number @> Kg.of_string and age = shift @@ int @> Years.of_int and species = shift @@ string @> Species.of_string and name = shift @@ string in { Animal.weight; age; species; name }) ;; end ;;

#verbose true

let order = Jsonaf.parse {| [12.34, 7, "Dog", "Fluffy"] |} |> Or_error.ok_exn |> Websocket_animal.of_json ;;

[%%expect {| val order : Websocket_animal.t = {Animal.weight = 12.34; age = 7; species = Species.Dog; name = "Fluffy"} |}]

[%%org {| If the remote API adds extra values to the array, your parse will fail because they were ignored. If this is not important for your app, you can use drop_rest. |}]

let parse_array of_json = Jsonaf.parse {| [100, "hello", true, "extra value!"] |} |> Or_error.ok_exn |> of_json ;;

let result = parse_array @@ let open Of_json in tuple Array_as_tuple.( let%map a = shift int and b = shift string and c = shift bool in a, b, c) ;;

[%%expect {| val parse_array : (Jsonaf_kernel.t -> 'a) -> 'a = Exception: (helpers.ml.Of_json_conv_failed ("Of_json failed to convert" ("array_as_tuple has unparsed elements" (elems ((String "extra value!")))) ("json context [0]" (Array ((Number 100) (String hello) True (String "extra value!")))))) |}]

let result = parse_array @@ let open Of_json in tuple Array_as_tuple.( let%map a = shift int and b = shift string and c = shift bool and () = drop_rest in a, b, c) ;;

[%%expect {| val result : int * string * bool = (100, "hello", true) |}]