1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
= The Js_of_ocaml library
== Base types ==
Base values are not represented the same way in OCaml and Javascript.
In particular, OCaml strings are mutable arrays of bytes, while
Javascript strings are constant arrays of UTF-16 code points. We list
here the correspondence between base types. Conversion functions are
provided.
|= OCaml values |= Ocaml type of Javascript values |= Actual Javascript type |
| {{{int}}} | {{{int}}} | Number |
| {{{float}}} | {{{float}}} | Number |
| {{{bool}}} | {{{bool Js.t}}} | Boolean |
| {{{string}}} | {{{Js.js_string Js.t}}} | String |
| {{{array}}} | {{{Js.js_array Js.t}}} | Array |
Integers and floats are implemented as Javascript numbers. They can
thus be directly passed to and from Javascript.
== Typing Javascript objects ==
Javascript objects are given types of the shape
{{{<m_1 : t_1; ...; m_n : t_n> Js.t}}},
using a phantom object type. The methods {{{m_i}}} stands for the
field of the Javascript object. For instance, a Javascript object of
type:
{{{
< data : js_string t Js.prop;
appendData : js_string t -> unit Js.meth> Js.t
}}}
has a property {{{data}}} containing a Javascript string, and a method
{{{appendData}}} taking a Javascript string as argument and returning
no value.
=== Method name and underscore
Some overloading is possible using a syntactic trick: names
{{{_foo}}}, {{{foo_abcd}}} and {{{foo}}} are all mapped to a same
Javascript field name {{{foo}}}: when accessing a field of an object,
the name given in the OCaml code is transformed by removing a leading
underscore and then removing all characters starting from the last
underscore; this yields the corresponding Javascript name. For
instance, these three types correspond to the same Javascript method
{{{drawImage}}}:
{{{
drawImage :
imageElement t -> float -> float -> unit meth
drawImage_withSize :
imageElement t -> float -> float -> float -> float -> unit meth
drawImage_fromCanvas :
canvasElement t -> float -> float -> unit meth
}}}
This trick can also be used to refer to Javascript fields {{{type}}} or
{{{Uppercase}}}, for instance as {{{_type}}} and {{{_Uppercase}}}.
==== Example
<<code language="ocaml"|
class type .. = object
(* Refer to [meth] *)
method meth : ..
method meth_int : ..
method _meth_ : ..
method _meth_aa : ..
(* Refer to [meth_a] *)
method meth_a_int : ..
method _meth_a_ : ..
method _meth_a_b : ..
(* Refer to [Meth] *)
method _Meth : ..
(* Refer to [_meth] *)
method __meth : ..
(* Refer to [_] *)
method __ : ..
end
>>
== Syntax extension ==
Two syntax extensions are provided: the <<a_manual chapter="ppx"|Ppx_js>>
one and the <<a_manual chapter="camlp4"|Camlp4>> one. This manual is written
using the ppx extension, which we advise.
== OCaml and Javascript functions ==
OCaml and Javascript do not follow the same calling convention. In
OCaml, functions can be partially applied, returning a function
closure. In Javascript, when only some of the parameters are passed,
the others are set to the {{{undefined}}} value. As a consequence, it
is not possible to call a Javascript function from OCaml as if it was
an OCaml function, and conversely.
=== Calling Javascript functions ===
At the moment, there is no syntactic sugar for calling Javascript
functions. You should use either {{{Js.Unsafe.call}}} or
{{{Js.Unsafe.fun_call}}}, depending whether you want {{{this}}} to be
bound to some particular object in the function body or not.
You can also refer to a Javascript function using an OCaml external
declaration. Then, you need to write stub functions in C so that the
OCaml compiler accept the external declaration:
{{{
Ocaml file:
external foo : t1 -> t2 = "foo"
C file:
#include <stdlib.h>
#define D(f) void f () { exit(1); }
D(foo)
}}}
You can call this function as if it was an OCaml function, as the
Javascript function is appropriately wrapped by the system.
Refer to <<a_manual chapter="linker" |the linker manual>>
to link your program with javascript stubs.
== IO ==
The <<a_api subproject="js_of_ocaml"|module Js_of_ocaml.Json>> module allows to marshal and unmarshal the
javascript representation of OCaml values into the corresponding JSON
string. The unmarshaling is unsafe in the same way the OCaml
{{{Marshal.from_string}}} function is.
Type-safe unmarshaling may be achieved with the
{{{deriving}}} library using either the optional {{{Json}}}
class or the {{{Pickle}}} class.
* The {{{Json}}} class use a Json as external representation and do
not preserve potential sharings in the data representation. See
<<a_api subproject="js_of_ocaml"|module Deriving_Json>> for more information.
* The {{{Pickle}}} class use a binary format as external
representation and preserve sharings in the data representation.
|
