/tryocaml/js_of_ocaml-patched/lib/js.mli
OCaml | 531 lines | 242 code | 47 blank | 242 comment | 0 complexity | 54d809ef205c8779fa41007bf6d5a613 MD5 | raw file
Possible License(s): GPL-2.0
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