Add require attribute.

REQUIRE.md

@@ -0,0 +1,124 @@
+Value bindings using required object in gen_js_api
+=========================================================
+
+It happens sometime that, when writing bindings of js library, there
+is a need to require some modules before using it.
+
+```js
+const myModule = require('myModule')
+/* ... */
+```
+
+There is a support to automatically write bindings and to use the
+required object instead of using the global object.
+
+The _require_ attribute
+--------------------------
+
+### Global ###
+
+The attribute `[@@@js.require "myModule"]` indicate to subsequents
+declarations to use the require module **myModule** during the
+generation phase. This global attribute requires the module name, it
+cannot be inferred.
+
+### Local to a module ###
+
+It's also permitted to attach the require attribute to modules.
+
+```ocaml
+module MyModule : sig
+  ...
+end [@@js.require]
+```
+
+By default, the name of the module is used as the name of the js
+module to require.
+
+### Associated to a variable ###
+
+To use bindings rules describe in [Value section](VALUES.md), it's
+possible to put the annotation to a simple variable.
+
+```ocaml
+type t = private Ojs.t
+
+val module_t : t Lazy.t [@@js.require "myModule"]
+
+val get_x : t -> int
+```
+
+###### Nested requires ######
+
+Actually, it's not possible to nest requires.
+
+How is it translated ?
+-------------------------
+
+First, it creates a definition which call lazily the requires
+function:
+
+```ocaml
+let (_require : Ojs.t Lazy.t) = lazy (Ojs.require "...")
+```
+
+Then, wherever the normal binding starts the access from the global
+object, the require annotation modifies by forcing the lazy value.
+For example, a method: `val foo: int -> string [@@js.call]`, is
+translated to:
+
+```ocaml
+let (foo : int -> string) =
+  fun x13 ->
+    Ojs.string_of_js
+      (Ojs.call (Lazy.force _require) "foo" [|(Ojs.int_to_js x13)|])
+```
+
+
+Automatic binding
+-------------------
+
+A declaration under a require context also follow conventions as
+explain in the [Value section](VALUES.md). The rules are quite
+similar except that the explicit type  `t` is not required anymore.
+Here are the rules:
+
+- If the type has the form `t -> Ojs.t` and the value name is
+  `t_to_js`, it's still assumed to be a `[@@js.cast]`.
+
+- If the type has the form `Ojs.t -> t` and the value name is
+  `t_of_js`, it's still assumed to be a `[@@js.cast]`.
+
+- If the value is a function with a unit argument `unit -> t`
+  (and `t` is not `unit`), then the declaration is assumed to be
+  a `[@@js.get]` property getter.
+
+- If the value is a function with a single argument (named typed)
+  `t -> unit` and its name starts with `set_`, then the declaration is
+  assumed to be a `[@@js.set]` property setter (on the property whose
+  name is obtained by dropping the `set_` prefix).
+
+- Otherwise, the declaration is assumed to be a `[@@js.call]` value.
+
+
+The scope attribute
+----------------------
+
+When js static objects are nested, there is a need to write nested
+modules in the ocaml code. To indicate when it is necessary to access
+a sub-object, the `[@@js.scope]` attribute is required.
+
+```
+module MyObject : sig
+  val my_method : a -> b -> c
+  module MySubObject : sig
+    val my_other_method : a -> b -> c
+  end [@@js.scope "mySubObject"]
+end [@@js.require]
+```
+
+Without the scope attribute, the method `my_other_method` in module
+`MySubObject` would be translated as if it were
+`require('MyObject').myOtherMethod(a, b);`. The scope attribute change
+this behaviour, by translating the same method as if it were following
+javascript call: `require('MyObject').mySubObject.myOtherMethod(a, b);`

VALUES.md

@@ -241,8 +241,8 @@ declarations in most cases.  Here are the rules, applied in order:
   for a type declaration.
 
 - Similarly, if the type has the form `Ojs.t -> t` (for a local named
-  type `t`) and the value name is `t_to_js` (i.e. the type name
-  followed by `_to_js`), then the function is assumed to be a
+  type `t`) and the value name is `t_of_js` (i.e. the type name
+  followed by `_of_js`), then the function is assumed to be a
   `[@@js.cast]`.
 
 - If the value is a function with a single argument `t1 -> unit` and

examples/require/Makefile

@@ -0,0 +1,18 @@
+# The package gen_js_api is released under the terms of an MIT-like license.
+# See the attached LICENSE file.
+# Copyright 2015, 2016 by LexiFi.
+
+ROOT = ../..
+include $(ROOT)/Makefile.common
+
+.PHONY: all clean
+
+all:
+	$(GENJSAPI) test.mli
+	$(OCAMLC) -c -I $(OJSDIR) test.mli test.ml
+	$(OCAMLC) -c -I $(OJSDIR) -ppx "$(GENJSAPI) -ppx" main.ml
+	$(OCAMLC) -no-check-prims -o main.exe $(OJSDIR)/gen_js_api.cma test.cmo main.cmo
+	$(JSOO) $(OJSDIR)/ojs_runtime.js main.exe
+
+clean:
+	rm -f test_bindings.ml *.cm* main.exe main.js *~

examples/require/main.ml

@@ -0,0 +1,39 @@
+
+let test_show_int () =
+  Format.printf "a.show_int: %!";
+  Test.A.show_int 42
+
+let get_prop () =
+  Format.printf "a.get_prop: %s@." (Test.A.prop ())
+
+let set_prop () =
+  Format.printf "a.set_prop; ";
+  Test.A.set_prop "Hello sweet world!";
+  get_prop ()
+
+let add () =
+  Format.printf "a.add 20 22: %d@." (Test.A.add 20 22)
+
+let test_b () =
+  let b = Test.B.new_b () in
+  Format.printf "b.incr: %d; " (b#incr ());
+  Format.printf "b.decr: %d; " (b#decr ());
+  Format.printf "b.incr: %d; " (b#incr ());
+  Format.printf "b.incr: %d; " (b#incr ());
+  Format.printf "b.incr: %d;@." (b#incr ())
+
+let test_c () =
+  let c = Lazy.force Test.module_c in
+  Format.printf "c.incr(41): %d@." (Test.C.incr c 41);
+  Format.printf "c.show_string: %!";
+  Test.C.show_string c "This is a C!";
+  Format.printf "c.prop: %d@." (Test.C.prop c);
+  Format.printf "c.set_prop;";
+  Test.C.set_prop c 1337;
+  Format.printf "c.prop: %d@." (Test.C.prop c)
+
+let functions =
+  [ test_show_int; get_prop; set_prop; add;
+    test_b; test_c ]
+
+let () = List.iter (fun f -> f ()) functions

examples/require/test.mli

@@ -0,0 +1,28 @@
+
+module A : sig
+  val show_int : int -> unit
+  val prop : unit -> string
+  val set_prop : string -> unit
+  val add : int -> int -> int
+end [@@js.require "./a"]
+
+module B : sig
+  class b : Ojs.t ->
+    object
+      inherit Ojs.obj
+      method incr : unit -> int
+      method decr : unit -> int
+    end
+
+  val new_b : unit -> b
+end [@@js.require "./b"]
+
+module C : sig
+  type t = private Ojs.t
+  val incr : t -> int -> int
+  val show_string : t -> string -> unit
+  val prop : t -> int
+  val set_prop : t -> int -> unit
+end
+
+val module_c : C.t Lazy.t [@@js.require "./c"]