Version: 5.0.1
7 Racket to Javascript FFI
| (require (planet dyoo/js-vm:1:12/ffi/ffi)) |
This API provides a foriegn function interface that allows javascript to be
accessed directly and explicitly through racket. This allows
access to native javascript functionality and allows external javascript APIs
to be used in racket code without modifying the source code of
the runtime infrastructure that evaluates the code.
The contents of this module need to run in a Javascript context.
7.1 Type Conversions
These procedures are designed to convert between racket and
javascript types.
| (racket->prim-js v) → js-value? |
| v : (or/c boolean? char? real? string? symbol? vector?) |
Converts a
racket value to a javascript value using the
following rules:
When v is a boolean, string, or inexact number,
racket->prim-js converts directly to the javascript boolean, string,
or number with the same value.
When v is an exact number, racket->prim-js returns a
floating point number equivalent to (racket->prim-js (exact->inexact v)) if v is in [minimum-js-fixnum, maximum-js-fixnum]. Otherwise it will raise an
exn:fail:contract exception.
When v is a char, racket->prim-js returns a
on-character javascript string corresponding to
(racket->prim-js (string v)).
When v is a symbol, racket->prim-js returns a
javascript string corresponding to (racket->prim-js (symbol->string v)).
When v is a vector, racket->prim-js returns a
javascript array whose elements are eq? to the elements of the
vector.
The racket->prim-js procedure cannot convert a procedure because
racket procedures cannot be converted to javascript in a
straightforward manner. When racket procedures are evaluated,
they are evaluated in continuation passing style, and hence any javascript
procedure constructed from a racket procedure must either be in
CPS or must return void.
Converts a
racket procedure to a javascript function. The
javascript function returned is in continuation passing style and takes a
continuation as its first argument. When called, the javascript function passes
the return value of
proc applied to all arguments but the first to the
function’s first argument.
Converts a
racket procedure to a javascript function. The
javascript function will apply
proc to its arguments, and then ignore
proc’s return value and return undefined (javascript’s version of
returning void).
| (prim-js->racket v) |
| → (or/c boolean? inexact-real? string? vector?) |
| v : js-value? |
Converts a javascript value to its corresponding
racket value.
When v is a javascript boolean or string,
prim-js->racket returns the racket equivalent of
that value.
When v is a number, prim-js->racket returns an inexact
number with the same value as the javascript number.
When v is an array, prim-js->racket returns a vector
whose elements are eq? to the elements of v.
If v is not an array, boolean, function, number, or string,
prim-js->racket will raise an exn:fail:contract exception.
7.2 Checking Javascript Types and Values
The following procedures are useful for checking the values and types of
javascript values.
| (js-value? x) → boolean? |
| x : any/c |
Returns #t if x is a javascript value, #f
otherwise.
| (js-object? x) → boolean? |
| x : any/c |
Returns #t if x is a javascript function, #f
otherwise.
| (js-function? x) → boolean? |
| x : any/c |
Returns #t if x is a javascript object, #f
otherwise.
| (js-=== v1 v2) → boolean? |
| v1 : js-value? |
| v2 : js-value? |
Returns #t if v1 and v2 are equal according to
javascript’s ===. Otherwise returns #f.
Returns a string representing the javascript type of v. The string is
obtained by calling javascript’s typeof on v.
| (js-instanceof v type) → boolean? |
| v : js-value? |
| type : js-function? |
Returns #t if v is an instance of the javascript type
type and #f otherwise.
Produces true if v is null.
Produces true if v is undefined.
7.3 Accessing Javascript Values
The following procedures are useful for accessing javascript values from
external APIs as well as constructing new values to pass to other javascript
functions.
Interprets name as an identifier, and returns the javascript value
bound to that identifier in the global scope. If no such value exists, then a
js-value containing javascript’s undefined is returned.
So, for example, (js-get-global-value "setTimeout") would return
javascript’s setTimeout procedure.
| (js-get-field obj selector ...+) → js-value? |
| obj : js-value? |
| selector : string? |
Begins by accessing the field of obj named by the first
selector, then accesses the field named by the second
selector of that object, and so-on until there are no more
selectors.
If at any point this action would result in accessing a field of a
racket value or javascript’s undefined,
js-get-field will raise an exn:fail:contract exception.
| (js-set-field! obj field v) → void? |
| obj : (or/c js-object? js-function?) |
| field : string? |
| v : any/c |
Mutatively sets the field named field of obj to v
and returns #<void>.
| (js-new constructor args ...) → js-object? |
| constructor : js-function? |
| args : any/c |
Constructs a new instance of constructor with args ... as
arguments.
| (js-make-hash [bindings]) → js-object? |
| bindings : (listof (list/c string? any/c)) = empty |
Constructs a new javascript hash table. For each element of bindings,
the element is put into the hash table with the first as the key and
the second as the value. If multiple elements in bindings
have firsts that are equal?, then only the last binding will
exist (the others will be overwritten).
The null value.
The undefined value.
7.4 Calling Javascript Functions
| (js-call f this-arg args ...) → any |
| f : js-function? |
| this-arg : (or/c js-object? false?) |
| args : any/c |
Applies f to args ... with this-arg as the
this object. If this-arg is #f, then
javascript’s null is used. This is equivalent to javascript’s
f.call(this-arg, args ...).