Add require attribute.

[Aaylor]

All information about how works the require attribute are in the document REQUIRE.md; it contains three kind of usage, and the meaning of each automatic rules when under the require context.

Related to the discussion #66.

[alainfrisch]

Should this work as well with a non-lazy binding?

[Aaylor]

It will not work with non-lazy bindings yet. I force the use of lazyness to avoid requiring javascript module when they're not necessary.

But i can support both version (one lazy, and one non-lazy) if needed.

[dannywillems]

@Aaylor I didn't read the PR, but is require returning functions (like nightmare, see this partial binding to Node with gen_js_api) supported?

[Aaylor]

Actually it's not supported, but it's just a simple case to add; but it will need a relaxed type for the require function (which is actually string -> Ojs.t).

A first solution would be to declare the require function as unsafe, and give it the type string -> 'a
The second solution should be to split in two part: a safe require and the unsafe one; and detect when the unsafe one should be called.

With one of the two solution above, we would be able to write:

val my_fun_module : (t1 -> ... -> tn) Lazy.t [@@js.require "myModule"]

[Aaylor]

@dannywillems Well infact, with this version, it's possible to have function but it's not convenient. Requiring a function could be written as

val my_fun_module : Ojs.t Lazy.t [@@js.require "myModule"]

and then used as following:

let _ =
  let my_fun_m = Lazy.force my_fun_module in
  let my_result_ojs = Ojs.apply my_fun_m [| (* ... *) |] in
  (* ... *)

I'm not sure that this is a philosophy of gen_js_api to give an unsafe function as I proposed earlier, @alainfrisch ? Is this a better thing to have an unsafe_require with type string -> 'a, or to avoid it ?

[sbriais]

I am not sure it's a good idea that this function returns a pair, since the second projection can be simply obtained from the first component and the require_ctx argument. My guess is that it would simplify the code a bit to move the corresponding logic at call sites (when needed).

[sbriais]

Could you please provide a full example (if I am not mistaken, the js part is missing)?
Ideally, a concrete example would even be better...

[Lupus]

Sad to see this abandoned. Just stumbled across this problem when trying to bind some nodejs to jsoo with gen_js_api myself and hand to resort to defining globals and using @@js.global "...." annotation.