Ppx syntax extension for Js_of_ocaml

To migrate from the camlp4 extension, it is advised to use camlp4-to-ppx which provides built-in support for Js_of_ocaml syntax.

A ppx rewriter (syntax extension) is available for manipulating object properties, invoking methods and creating objects.

The syntax and typing rules are as follows:

• Getting a property

obj : <m : u Js.prop> Js.t
--------------------------
     obj##.m : u

• Setting a property

obj : <m : u Js.prop> Js.t
     e : u
--------------------------
  obj##.m := e : unit

• Invoking a method

obj : <m : t_1 -> ... -> t_n -> u Js.meth; ..> Js.t
e_i : t_i               (1 <= i <= n)
----------------------------------------------------
        obj##m e_1 ... e_n : u

For easier chaining, the following alternative syntax is also possible: [ obj(m e_1 ... e_n) ].

Beware, partial application is not allowed.

• Using an object constructor

constr : (t_1 -> ... -> t_n -> u Js.t) Js.constr
   e_i : t_i               (1 <= i <= n)
------------------------------------------------
          new%js constr e1 ... en : u Js.t

[ constr ] here must be an identifier. For constructors that are not identifiers, bind them first:

let a = Js.Unsafe.global##.A in
  new%js a

• Creating a literal object

object%js (self) (* Equivalent of this *)
  val x1 = 3 (* read-only prop *)
  val x2 = 3 [@@readonly] (* read-only prop *)

  val mutable y1 = 4 (* read/write prop *)
  val y2 = 4 [@@readwrite] (* read/write prop *)

  val z = 5 [@@writeonly] (* write-only prop *)

  val t1 = Js.undefined [@@jsoo.optdef] (* optdef prop *)

  method foo i = self##.y1 := self##.x1 + i
end

Properties are defined with the [val] keyword. [mutable] makes the property writable. Properties can be annotated with attributes to change the default semantic. Attributes can be one of [readwrite], [readonly], [writeonly], [optdef].

[self] can be any identifier and will be bind to [this] in javascript.

In this case, the object has the following type:

< foo : int -> unit Js.meth;
      t1 : 'a Js.optdef_prop;
      x1 : int Js.readonly_prop;
      x2 : int Js.readonly_prop;
      y1 : int Js.prop;
      y2 : int Js.prop;
      z : int Js.writeonly_prop >
    Js.t