/tryocaml/js_of_ocaml-patched/lib/js.mli

  1(* Js_of_ocaml library
  2 * http://www.ocsigen.org/js_of_ocaml/
  3 * Copyright (C) 2010 Jérôme Vouillon
  4 * Laboratoire PPS - CNRS Université Paris Diderot
  5 *
  6 * This program is free software; you can redistribute it and/or modify
  7 * it under the terms of the GNU Lesser General Public License as published by
  8 * the Free Software Foundation, with linking exception;
  9 * either version 2.1 of the License, or (at your option) any later version.
 10 *
 11 * This program is distributed in the hope that it will be useful,
 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 14 * GNU Lesser General Public License for more details.
 15 *
 16 * You should have received a copy of the GNU Lesser General Public License
 17 * along with this program; if not, write to the Free Software
 18 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 19 *)
 20
 21(** Javascript binding
 22
 23    This module provides types and functions to interoperate with
 24    Javascript values, and gives access to Javascript standard
 25    objects.
 26*)
 27
 28(** {2 Dealing with [null] and [undefined] values.} *)
 29
 30type +'a opt
 31  (** Type of possibly null values. *)
 32type +'a optdef
 33  (** Type of possibly undefined values. *)
 34
 35val null : 'a opt
 36  (** The [null] value. *)
 37val some : 'a -> 'a opt
 38  (** Consider a value into a possibly null value. *)
 39val undefined : 'a optdef
 40  (** The [undefined] value *)
 41val def : 'a -> 'a optdef
 42  (** Consider a value into a possibly undefined value. *)
 43
 44(** Signatures of a set of standard functions for manipulating
 45    optional values. *)
 46module type OPT = sig
 47  type 'a t
 48  val empty : 'a t
 49    (** No value. *)
 50  val return : 'a -> 'a t
 51    (** Consider a value as an optional value. *)
 52  val map : 'a t -> ('a -> 'b) -> 'b t
 53    (** Apply a function to an optional value if it is available.
 54        Returns the result of the application. *)
 55  val bind : 'a t -> ('a -> 'b t) -> 'b t
 56    (** Apply a function returning an optional value to an optional value *)
 57  val test : 'a t -> bool
 58    (** Returns [true] if a value is available, [false] otherwise. *)
 59  val iter : 'a t -> ('a -> unit) -> unit
 60    (** Apply a function to an optional value if it is available. *)
 61  val case : 'a t -> (unit -> 'b) -> ('a -> 'b) -> 'b
 62    (** Pattern matching on optional values. *)
 63  val get : 'a t -> (unit -> 'a) -> 'a
 64    (** Get the value.  If no value available, an alternative function
 65        is called to get a default value. *)
 66  val option : 'a option -> 'a t
 67    (** Convert option type. *)
 68  val to_option : 'a t -> 'a option
 69    (** Convert to option type. *)
 70end
 71
 72module Opt : OPT with type 'a t = 'a opt
 73  (** Standard functions for manipulating possibly null values. *)
 74module Optdef : OPT with type 'a t = 'a optdef
 75  (** Standard functions for manipulating possibly undefined values. *)
 76
 77(** {2 Types for specifying method and properties of Javascript objects} *)
 78
 79type +'a t
 80  (** Type of Javascript objects.  The type parameter is used to
 81      specify more precisely an object.  *)
 82type +'a meth
 83  (** Type used to specify method types:
 84      a Javascript object
 85        [<m : t1 -> t2 -> ... -> tn -> t Js.meth> Js.t]
 86      has a Javascript method [m] expecting {i n} arguments
 87      of types [t1] to [tn] and returns a value of type [t]. *)
 88type +'a gen_prop
 89  (** Type used to specify the properties of Javascript
 90      objects.  In practice you should rarely need this type directly,
 91      but should rather use the type abbreviations below instead. *)
 92type 'a readonly_prop = <get : 'a> gen_prop
 93  (** Type of read-only properties:
 94      a Javascript object
 95        [<p : t Js.readonly_prop> Js.t]
 96      has a read-only property [p] of type [t]. *)
 97type 'a writeonly_prop = <set : 'a -> unit> gen_prop
 98  (** Type of write-only properties:
 99      a Javascript object
100        [<p : t Js.writeonly_prop> Js.t]
101      has a write-only property [p] of type [t]. *)
102type 'a prop = <get : 'a; set : 'a -> unit> gen_prop
103  (** Type of read/write properties:
104      a Javascript object
105        [<p : t Js.writeonly_prop> Js.t]
106      has a read/write property [p] of type [t]. *)
107type 'a optdef_prop = <get : 'a optdef; set : 'a -> unit> gen_prop
108  (** Type of read/write properties that may be undefined:
109      you can set them to a value of some type [t], but if you read
110      them, you will get a value of type [t optdef] (that may be
111      [undefined]). *)
112type float_prop = <get : float t; set : float -> unit> gen_prop
113  (** Type of float properties:
114      you can set them to an OCaml [float], but you will get back a
115      native Javascript number of type [float t]. *)
116
117(** {2 Object constructors} *)
118
119type +'a constr
120  (** A value of type [(t1 -> ... -> tn -> t Js.t) Js.constr] is a
121      Javascript constructor expecting {i n} arguments of types [t1]
122      to [tn] and returning a Javascript object of type [t Js.t].  Use
123      the syntax extension [jsnew c (e1, ..., en)] to build an object
124      using constructor [c] and arguments [e1] to [en]. *)
125
126(** {2 Callbacks to OCaml} *)
127
128type (-'a, +'b) meth_callback
129   (** Type of callback functions.  A function of type
130       [(u, t1 -> ... -> tn -> t) meth_callback] can be called
131       from Javascript with [this] bound to a value of type [u]
132       and up to {i n} arguments of types [t1] to [tn].  The system
133       takes care of currification, so less than {i n} arguments can
134       be provided.  As a special case, a callback of type
135       [(t, unit -> t) meth_callback] can be called from Javascript
136       with no argument.  It will behave as if it was called with a
137       single argument of type [unit]. *)
138type 'a callback = (unit, 'a) meth_callback
139  (** Type of callback functions intended to be called without a
140      meaningful [this] implicit parameter. *)
141
142external wrap_callback : ('a -> 'b) -> ('c, 'a -> 'b) meth_callback =
143    "caml_js_wrap_callback"
144  (** Wrap an OCaml function so that it can be invoked from
145      Javascript. *)
146external wrap_meth_callback :
147  ('c -> 'a -> 'b) -> ('c, 'a -> 'b) meth_callback =
148    "caml_js_wrap_meth_callback"
149  (** Wrap an OCaml function so that it can be invoked from
150      Javascript.  The first parameter of the function will be bound
151      to the value of the [this] implicit parameter. *)
152
153(** {2 Javascript standard objects} *)
154
155val _true : bool t
156  (** Javascript [true] boolean. *)
157val _false : bool t
158  (** Javascript [false] boolean. *)
159
160type match_result_handle
161  (** A handle to a match result.  Use function [Js.match_result]
162      to get the corresponding [MatchResult] object.
163      (This type is used to resolved the mutual dependency between
164       string and array type definitions.) *)
165type string_array
166  (** Opaque type for string arrays.  You can get the actual [Array]
167      object using function [Js.str_array].
168      (This type is used to resolved the mutual dependency between
169       string and array type definitions.) *)
170
171(** Specification of Javascript string objects. *)
172class type js_string = object
173  method toString : js_string t meth
174  method valueOf : js_string t meth
175  method charAt : int -> js_string t meth
176  method charCodeAt : int -> float t meth        (* This may return NaN... *)
177  method concat : js_string t -> js_string t meth
178  method concat_2 : js_string t -> js_string t -> js_string t meth
179  method concat_3 :
180    js_string t -> js_string t -> js_string t -> js_string t meth
181  method concat_4 :
182    js_string t -> js_string t -> js_string t -> js_string t ->
183    js_string t meth
184  method indexOf : js_string t -> int meth
185  method indexOf_from : js_string t -> int -> int meth
186  method lastIndexOf : js_string t -> int meth
187  method lastIndexOf_from : js_string t -> int -> int meth
188  method localeCompare : js_string t -> float t meth
189  method _match : regExp t -> match_result_handle t opt meth
190  method replace : regExp t -> js_string t -> js_string t meth
191  (* FIX: version of replace taking a function... *)
192  method replace_string : js_string t -> js_string t -> js_string t meth
193  method search : regExp t -> int meth
194  method slice : int -> int -> js_string t meth
195  method slice_end : int -> js_string t meth
196  method split : js_string t -> string_array t meth
197  method split_limited : js_string t -> int -> string_array t meth
198  method split_regExp : regExp t -> string_array t meth
199  method split_regExpLimited : regExp t -> int -> string_array t meth
200  method substring : int -> int -> js_string t meth
201  method substring_toEnd : int -> js_string t meth
202  method toLowerCase : js_string t meth
203  method toLocaleLowerCase : js_string t meth
204  method toUpperCase : js_string t meth
205  method toLocaleUpperCase : js_string t meth
206  method length : int readonly_prop
207end
208
209(** Specification of Javascript regular expression objects. *)
210and regExp = object
211  method exec : js_string t -> match_result_handle t opt meth
212  method test : js_string t -> bool t meth
213  method toString : js_string t meth
214  method source : js_string t readonly_prop
215  method global : bool t readonly_prop
216  method ignoreCase : bool t readonly_prop
217  method multiline : bool t readonly_prop
218  method lastIndex : int prop
219end
220
221val regExp : (js_string t -> regExp t) constr
222  (** Constructor of [RegExp] objects.  The expression [jsnew regExp (s)]
223      builds the regular expression specified by string [s]. *)
224val regExp_withFlags : (js_string t -> js_string t -> regExp t) constr
225  (** Constructor of [RegExp] objects.  The expression
226      [jsnew regExp (s, f)] builds the regular expression specified by
227      string [s] using flags [f]. *)
228val regExp_copy : (regExp t -> regExp t) constr
229  (** Constructor of [RegExp] objects.  The expression
230      [jsnew regExp (r)] builds a copy of regular expression [r]. *)
231
232(** Specification of Javascript regular arrays. *)
233class type ['a] js_array = object
234  method toString : js_string t meth
235  method toLocaleString : js_string t meth
236  method concat : 'a js_array t -> 'a js_array t meth
237  method join : js_string t -> js_string t meth
238  method pop : 'a optdef meth
239  method push : 'a -> int meth
240  method push_2 : 'a -> 'a -> int meth
241  method push_3 : 'a -> 'a -> 'a -> int meth
242  method push_4 : 'a -> 'a -> 'a -> 'a -> int meth
243  method reverse : 'a js_array t meth
244  method shift : 'a optdef meth
245  method slice : int -> int -> 'a js_array t meth
246  method slice_end : int -> 'a js_array t meth
247  method sort : ('a -> 'a -> float) callback -> 'a js_array t meth
248  method sort_asStrings : 'a js_array t meth
249  method splice : int -> int -> 'a js_array t meth
250  method splice_1 : int -> int -> 'a -> 'a js_array t meth
251  method splice_2 : int -> int -> 'a -> 'a -> 'a js_array t meth
252  method splice_3 : int -> int -> 'a -> 'a -> 'a -> 'a js_array t meth
253  method splice_4 : int -> int -> 'a -> 'a -> 'a -> 'a -> 'a js_array t meth
254  method unshift : 'a -> int meth
255  method unshift_2 : 'a -> 'a -> int meth
256  method unshift_3 : 'a -> 'a -> 'a -> int meth
257  method unshift_4 : 'a -> 'a -> 'a -> 'a -> int meth
258  method length : int prop
259end
260
261val array_empty : 'a js_array t constr
262  (** Constructor of [Array] objects.  The expression
263      [jsnew array_empty ()] returns an empty array. *)
264val array_length : (int -> 'a js_array t) constr
265  (** Constructor of [Array] objects.  The expression
266      [jsnew array_empty (l)] returns an array of length [l]. *)
267
268val array_get : 'a #js_array t -> int -> 'a optdef
269  (** Array access: [array_get a i] returns the element at index [i]
270      of array [a].  Returns [undefined] if there is no element at
271      this index. *)
272val array_set : 'a #js_array t -> int -> 'a -> unit
273  (** Array update: [array_set a i v] puts [v] at index [i] in
274      array [a]. *)
275
276(** Specification of match result objects *)
277class type match_result = object
278  inherit [js_string t] js_array
279  method index : int readonly_prop
280  method input : js_string t readonly_prop
281end
282
283val str_array : string_array t -> js_string t js_array t
284  (** Convert an opaque [string_array t] object into an array of
285      string.  (Used to resolved the mutual dependency between string
286      and array type definitions.) *)
287val match_result : match_result_handle t -> match_result t
288  (** Convert a match result handle into a [MatchResult] object.
289      (Used to resolved the mutual dependency between string
290      and array type definitions.) *)
291
292(** Specification of Javascript number objects. *)
293class type number = object
294  method toString : js_string t meth
295  method toString_radix : int -> js_string t meth
296  method toLocaleString : js_string t meth
297  method toFixed : int -> js_string t meth
298  method toExponential : js_string t meth
299  method toExponential_digits : int -> js_string t meth
300  method toPrecision : int -> js_string meth t
301end
302
303external number_of_float : float -> number t = "caml_js_from_float"
304  (** Conversion of OCaml floats to Javascript number objects. *)
305external float_of_number : number t -> float = "caml_js_to_float"
306  (** Conversion of Javascript number objects to OCaml floats. *)
307
308(** Specification of Javascript date objects. *)
309class type date = object
310  method toString : js_string t meth
311  method toDateString : js_string t meth
312  method toTimeString : js_string t meth
313  method toLocaleString : js_string t meth
314  method toLocaleDateString : js_string t meth
315  method toLocaleTimeString : js_string t meth
316  method valueOf : float t meth
317  method getTime : float t meth
318  method getFullYear : int meth
319  method getUTCFullYear : int meth
320  method getMonth : int meth
321  method getUTCMonth : int meth
322  method getDate : int meth
323  method getUTCDate : int meth
324  method getDay : int meth
325  method getUTCDay : int meth
326  method getHours : int meth
327  method getUTCHours : int meth
328  method getMinutes : int meth
329  method getUTCMinutes : int meth
330  method getSeconds : int meth
331  method getUTCSeconds : int meth
332  method getMilliseconds : int meth
333  method getUTCMilliseconds : int meth
334  method getTimezoneOffset : int meth
335  method setTime : float -> float t meth
336  method setFullYear : int -> float t meth
337  method setUTCFullYear : int -> float t meth
338  method setMonth : int -> float t meth
339  method setUTCMonth : int -> float t meth
340  method setDate : int -> float t meth
341  method setUTCDate : int -> float t meth
342  method setDay : int -> float t meth
343  method setUTCDay : int -> float t meth
344  method setHours : int -> float t meth
345  method setUTCHours : int -> float t meth
346  method setMinutes : int -> float t meth
347  method setUTCMinutes : int -> float t meth
348  method setSeconds : int -> float t meth
349  method setUTCSeconds : int -> float t meth
350  method setMilliseconds : int -> float t meth
351  method setUTCMilliseconds : int -> float t meth
352  method toUTCString : js_string t meth
353  method toISOString : js_string t meth
354  method toJSON : 'a -> js_string t meth
355end
356
357val date_now : date t constr
358  (** Constructor of [Date] objects: [new date_now ()] returns a
359      [Date] object initialized with the current date. *)
360val date_fromTimeValue : (float -> date t) constr
361  (** Constructor of [Date] objects: [new date_fromTimeValue (t)] returns a
362      [Date] object initialized with the time value [t]. *)
363val date_month : (int -> int -> date t) constr
364  (** Constructor of [Date] objects: [new date_fromTimeValue (y, m)]
365      returns a [Date] object corresponding to year [y] and month [m]. *)
366val date_day : (int -> int -> int -> date t) constr
367  (** Constructor of [Date] objects: [new date_fromTimeValue (y, m, d)]
368      returns a [Date] object corresponding to year [y], month [m] and
369      day [d]. *)
370val date_hour : (int -> int -> int -> int -> date t) constr
371  (** Constructor of [Date] objects: [new date_fromTimeValue (y, m, d, h)]
372      returns a [Date] object corresponding to year [y] to hour [h]. *)
373val date_min : (int -> int -> int -> int -> int -> date t) constr
374  (** Constructor of [Date] objects: [new date_fromTimeValue (y, m, d, h, m')]
375      returns a [Date] object corresponding to year [y] to minute [m']. *)
376val date_sec : (int -> int -> int -> int -> int -> int -> date t) constr
377  (** Constructor of [Date] objects:
378      [new date_fromTimeValue (y, m, d, h, m', s)]
379      returns a [Date] object corresponding to year [y] to second [s]. *)
380val date_ms : (int -> int -> int -> int -> int -> int -> int -> date t) constr
381  (** Constructor of [Date] objects:
382      [new date_fromTimeValue (y, m, d, h, m', s, ms)]
383      returns a [Date] object corresponding to year [y]
384      to millisecond [ms]. *)
385
386(** Specification of the date constructor, considered as an object. *)
387class type date_constr = object
388  method parse : js_string t -> float t meth
389  method _UTC_month : int -> int -> float t meth
390  method _UTC_day : int -> int -> float t meth
391  method _UTC_hour : int -> int -> int -> int -> float t meth
392  method _UTC_min : int -> int -> int -> int -> int -> float t meth
393  method _UTC_sec : int -> int -> int -> int -> int -> int -> float t meth
394  method _UTC_ms :
395    int -> int -> int -> int -> int -> int -> int -> float t meth
396(* This method is not available on Internet Explorer...
397  method now : float t meth
398*)
399end
400
401val date : date_constr t
402  (** The date constructor, as an object. *)
403
404(** Specification of Javascript math object. *)
405class type math = object
406  method random : float t meth
407end
408
409val math : math t
410  (** The Math object *)
411
412(** {2 Standard Javascript functions} *)
413
414val decodeURI : js_string t -> js_string t
415  (** Decode a URI: replace by the corresponding byte all escape
416      sequences but the ones corresponding to a URI reserved character
417      and convert the string from UTF-8 to UTF-16. *)
418val decodeURIComponent : js_string t -> js_string t
419  (** Decode a URIComponent: replace all escape sequences by the
420      corresponding byte and convert the string from UTF-8 to
421      UTF-16. *)
422val encodeURI : js_string t -> js_string t
423  (** Encode a URI: convert the string to UTF-8 and replace all unsafe
424      bytes by the corresponding escape sequence. *)
425val encodeURIComponent : js_string t -> js_string t
426  (** Same as [encodeURI], but also encode URI reserved characters. *)
427val escape : js_string t -> js_string t
428  (** Escape a string: unsafe UTF-16 code points are replaced by
429      2-digit and 4-digit escape sequences. *)
430val unescape : js_string t -> js_string t
431  (** Unescape a string: 2-digit and 4-digit escape sequences are
432      replaced by the corresponding UTF-16 code point. *)
433
434(** {2 Conversion functions between Javascript and OCaml types} *)
435
436external bool : bool -> bool t = "caml_js_from_bool"
437  (** Conversion of booleans from OCaml to Javascript. *)
438external to_bool : bool t -> bool = "caml_js_to_bool"
439  (** Conversion of booleans from Javascript to OCaml. *)
440external string : string -> js_string t = "caml_js_from_string"
441  (** Conversion of strings from OCaml to Javascript.  (The OCaml
442      string is considered to be encoded in UTF-8 and is converted to
443      UTF-16.) *)
444external to_string : js_string t -> string = "caml_js_to_string"
445  (** Conversion of strings from Javascript to OCaml. *)
446external float : float -> float t = "caml_js_from_float"
447  (** Conversion of OCaml floats to Javascript numbers. *)
448external to_float : float t -> float = "caml_js_to_float"
449  (** Conversion of Javascript numbers to OCaml floats. *)
450external array : 'a array -> 'a js_array t = "caml_js_from_array"
451  (** Conversion of arrays from OCaml to Javascript. *)
452external to_array : 'a js_array t -> 'a array = "caml_js_to_array"
453  (** Conversion of arrays from Javascript to OCaml. *)
454external bytestring : string -> js_string t = "caml_js_from_byte_string"
455  (** Conversion of strings of bytes from OCaml to Javascript.
456      (Each byte will be converted in an UTF-16 code point.) *)
457external to_bytestring : js_string t -> string = "caml_js_to_byte_string"
458  (** Conversion of strings of bytes from Javascript to OCaml.  (The
459      Javascript string should only contain UTF-16 code points below
460      255.) *)
461
462(** {2 Convenience coercion functions} *)
463
464val coerce : 'a -> ('a -> 'b Opt.t) -> ('a -> 'b) -> 'b
465  (** Apply a possibly failing coercion function.
466      [coerce v c f] attempts to apply coercion [c] to value [v].
467      If the coercion returns [null], function [f] is called. *)
468val coerce_opt : 'a Opt.t -> ('a -> 'b Opt.t) -> ('a -> 'b) -> 'b
469  (** Apply a possibly failing coercion function.
470      [coerce_opt v c f] attempts to apply coercion [c] to value [v].
471      If [v] is [null] or the coercion returns [null], function [f] is
472      called.
473      Typical usage is the following:
474      {[Js.coerce_opt (Dom_html.getElementById id)
475      Dom_html.CoerceTo.div (fun _ -> assert false)]} *)
476
477(** {2 Type checking operators.} *)
478
479external typeof : < .. > t -> js_string t = "caml_js_typeof"
480  (** Returns the type of a Javascript object. *)
481
482external instanceof : < .. > t -> _ constr -> bool = "caml_js_instanceof"
483  (** Tests whether a Javascript object is an instance of a given class. *)
484
485(** {2 Unsafe operations.} *)
486
487(** Unsafe Javascript operations *)
488module Unsafe : sig
489  external variable : string -> 'a = "caml_js_var"
490    (** Access a Javascript variable.  [variable "foo"] will
491        return the current value of variable [foo]. *)
492
493  type any
494    (** Top type.  Used for putting values of different types
495        in a same array. *)
496  external inject : 'a -> any = "%identity"
497    (** Coercion to top type. *)
498  external coerce : < .. > t -> < ..> t = "%identity"
499    (** Unsafe coercion between to Javascript objects. *)
500  external get : 'a -> 'b -> 'c = "caml_js_get"
501    (** Get the value of an object property.  The expression [get o s]
502        returns the value of property [s] of object [o]. *)
503  external set : 'a -> 'b -> 'c -> unit = "caml_js_set"
504    (** Set an object property.  The expression [set o s v]
505        set the property [s] of object [o] to value [v]. *)
506  external call : 'a -> 'b -> any array -> 'c = "caml_js_call"
507    (** Performs a Javascript function call.  The expression
508        [call f o a] calls the Javascript function [f] with the
509        arguments given by the array [o], and binding [this] to [o]. *)
510  external fun_call : 'a -> any array -> 'b = "caml_js_fun_call"
511    (** Performs a Javascript function call.  The expression
512        [fun_call f a] calls the Javascript function [f] with the
513        arguments given by the array [o]. *)
514  external meth_call : 'a -> string -> any array -> 'b = "caml_js_meth_call"
515    (** Performs a Javascript method call.  The expression
516        [meth_call o m a] calls the Javascript method [m] of object [o]
517        with the arguments given by the array [a]. *)
518  external new_obj : 'a -> any array -> 'b = "caml_js_new"
519    (** Create a Javascript object.  The expression [new_obj c a]
520        creates a Javascript object with constructor [c] using the
521        arguments given by the array [a]. *)
522
523  external pure_expr : (unit -> 'a) -> 'a = "caml_js_pure_expr"
524    (** Asserts that an expression is pure, and can therefore be
525        optimized away by the compiler if unused. *)
526
527  external eval_string : string -> 'a = "caml_js_eval_string"
528    (** Evaluate Javascript code *)
529
530(*FIX also, object/array literals *)
531end