ocaml-json-tc-custom /

Filename Size Date modified Message
lib
lib_test
39 B
43 B
54 B
91 B
1.4 KB
311 B
482 B
6.6 KB
1.2 KB
                          json-tc

Introduction
============

json-tc is a syntax extension of OCaml that can make the use of
JSON data easier. From a special type declaration, the camlp4
preprocessor generates the code that converts between a JSON "abstract
syntax tree" and specialized OCaml data structures such as objects,
polymorphic variants, lists, arrays, tuples, etc.

It will at the same time check that the structure of the JSON
document is correct and produce OCaml data which is statically
typed.  For example, the following declaration defines the type of
a point object:

  type point = < x: float; y: float > with json

This automatically makes two functions available, with the following
signature:

  val json_of_point : point -> Json_type.t
  val point_of_json : Json_type.t -> point

Json_type.t is the type of parsed JSON data, which is provided by
the json-wheel library.

Function json_of_point would convert an OCaml object of type point
into a JSON object. point_of_json works the other way around, and
fails by raising the Json_type.Json_error exception if the input
JSON data doesn't have the right format.


Installation
============

Installation:
  make
  make install

Uninstallation:

  make uninstall


Usage
=====

Basically, you must preprocess your OCaml file(s) with 
camlp4o pa_json_tc.cmo. Once installed using the standard
procedure (ocamlfind), you can compile a file using these commands:

# compile
ocamlfind ocamlopt -c yourfile.ml -syntax camlp4o -package json-tc.syntax

# link
ocamlfind ocamlopt -o yourprog yourfile.cmx -linkpkg -package json-tc.syntax

Build tools like OCamlMakefile take care of this nicely.


Syntax
======

You must write a special type declaration that describes the expected
format of the JSON data. There is a predefined mapping from OCaml types
to JSON:

OCaml type              JSON type         Properties of JSON data
----------              ---------         -----------------------

string                  String
float                   Number            not an int
int                     Number            an int
number*                 Number            a float or an int
bool                    Boolean

list                    Array             homogenous
array                   Array             homogenous
tuple                   Array             fixed length

(string * 'a) assoc**   Object            an object read as an associative list
(string, 'a) Hashtbl.t  Object
object or record        Object            additional methods/fields are ignored

option                  any               null means None

polymorphic variants    String or Array   a String for constructors without
                                          an argument, 
                                          or an Array of length 2
                                          where the first element is a
                                          String that represents the 
                                          constructor
                                          and the second element is the
                                          argument.

classic variants        String or Array   a String for contructors without 
                                          an argument,
                                          or an Array where the first element
                                          is the String that represents the
                                          constructor and the rest are the
                                          arguments. Unlike polymorphic
                                          variants, there may be several 
                                          arguments (just don't use parentheses
                                          around them in the type definition).

X.t***                  defined by X.of_json and X.to_json


---
*: the number type is an alias for float, but accepts JSON ints and converts
   them to OCaml floats.
**: the assoc type is an alias for list, but converts from a JSON object.
***: X can be any simple module name, but module fields t, of_json and to_json
     are mandatory.

A type definition is done like regular type definitions, but the keyword
"with json" is placed after the type definition, as:

  type t = int * float with json
                       ^^^^^^^^^

The type cannot be polymorphic, i.e. it doesn't support type parameters.
A small set of basic types are supported (see table above). Other type
names can be used only if they are part of the same definition.
This works:

  type a = b
  and b = int list with json

But the following doesn't work:

  type b = int list with json

  type a = b with json (* b is unknown to the preprocessor *)


Example 1
=========

The following definition is correct:

type point = < x: number; y: number >
and coords = point array with json

It can successfully load the following JSON data:

[ { "x": 1, "y": 0.5 },
  { "x": 0, "y": 0.3333333 } ]


Full example:

(* File example1.ml *)

type point = < x: number; y: number >
and coords = point array with json

let json_string = "
  [ { \"x\": 1, \"y\": 0.5 },
    { \"x\": 0, \"y\": 0.3333333 } ]
"

let json_tree = Json_io.json_of_string json_string
let my_coords = coords_of_json json_tree
let _ = Array.iter (fun p -> Printf.printf "(%g, %g)\n" p#x p#y) my_coords

(* EOF *)

Save the example as "example1.ml", compile it and run it:

$ ocamlfind ocamlopt -o example1 -linkpkg -package json-tc -syntax camlp4o example1.ml
$ ./example1
(1, 0.5)
(0, 0.333333)




Example 2
=========

This example shows you the representation that we chose for sum types in JSON:

(* File example2.ml *)

type colors = [ `Black 
                   | `White 
                   | `Rgb of (float * float * float)
                   | `Any "*" ] list with json

let my_colors = [ `Black; `White; `Any;
                  `Rgb (1., 0., 0.);
                  `Rgb (0., 1., 0.);
                  `Rgb (0., 0., 1.) ]

let _ = print_endline (Json_io.string_of_json (json_of_colors my_colors))

(* EOF *)


$ ocamlfind ocamlopt -o example2 -linkpkg -package json-tc -syntax camlp4o example2.ml
$ ./example2
[
  "Black",
  "White",
  "*",
  [ "Rgb",
    [ 1.0,
      0.0,
      0.0 ]
  ],
  [ "Rgb",
    [ 0.0,
      1.0,
      0.0 ]
  ],
  [ "Rgb",
    [ 0.0,
      0.0,
      1.0 ]
  ]
]

Note how we specified that `Any translates into "*" rather than "Any".
The same technique is available to rename object methods, and it is crucial
when some existing JSON format uses method names that are not valid
OCaml identifiers.


Credits
=======

json-tc is based on the json-static/json-wheel libraries by Martin
Jambon, and converted to use the type-conv library so that it can
be used alongside other camlp4 syntax extensions.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.