This Module implements types and macros to facilitate the wrapping of, and interaction with JavaScript libraries. Using the provided types JsObject and JsAssoc together with the provided macros allows for smoother interfacing with JavaScript, allowing for example quick and easy imports of JavaScript variables:
Example:
import std/jsffi # Here, we are using jQuery for just a few calls and do not want to wrap the # whole library: # import the document object and the console var document {.importc, nodecl.}: JsObject var console {.importc, nodecl.}: JsObject # import the "$" function proc jq(selector: JsObject): JsObject {.importjs: "$$(#)".} # Use jQuery to make the following code run, after the document is ready. # This uses an experimental `.()` operator for `JsObject`, to emit # JavaScript calls, when no corresponding proc exists for `JsObject`. proc main = jq(document).ready(proc() = console.log("Hello JavaScript!") )
Types
JsAssoc[K; V] = ref object of JsRoot
- Statically typed wrapper around a JavaScript object. Source Edit
JsEvalError {.importc: "EvalError".} = object of JsError
- Source Edit
JsRangeError {.importc: "RangeError".} = object of JsError
- Source Edit
JsReferenceError {.importc: "ReferenceError".} = object of JsError
- Source Edit
JsSyntaxError {.importc: "SyntaxError".} = object of JsError
- Source Edit
JsTypeError {.importc: "TypeError".} = object of JsError
- Source Edit
JsURIError {.importc: "URIError".} = object of JsError
- Source Edit
Vars
jsArguments {.importc: "arguments", nodecl.}: JsObject
- JavaScript's arguments pseudo-variable. Source Edit
jsDirname {.importc: "__dirname", nodecl.}: cstring
- JavaScript's __dirname pseudo-variable. Source Edit
jsFilename {.importc: "__filename", nodecl.}: cstring
- JavaScript's __filename pseudo-variable. Source Edit
jsUndefined {.importc: "undefined", nodecl.}: JsObject
- JavaScript's undefined literal. Source Edit
Procs
proc `==`(x, y: JsRoot): bool {.importjs: "(# === #)", ...raises: [], tags: [], forbids: [].}
- Compares two JsObjects or JsAssocs. Be careful though, as this is comparison like in JavaScript, so if your JsObjects are in fact JavaScript Objects, and not strings or numbers, this is a comparison of references. Source Edit
proc `[]`(obj: JsObject; field: cstring): JsObject {.importjs: "#[#]", ...raises: [], tags: [], forbids: [].}
- Returns the value of a property of name field from a JsObject obj. Source Edit
proc `[]`(obj: JsObject; field: int): JsObject {.importjs: "#[#]", ...raises: [], tags: [], forbids: [].}
- Returns the value of a property of name field from a JsObject obj. Source Edit
proc `[]=`[K: JsKey; V](obj: JsAssoc[K, V]; field: K; val: V) {. importjs: "#[#] = #", ...raises: [], tags: [], forbids: [].}
- Sets the value of a property of name field in a JsAssoc obj to v. Source Edit
proc `[]=`[T](obj: JsObject; field: cstring; val: T) {.importjs: "#[#] = #", ...raises: [], tags: [], forbids: [].}
- Sets the value of a property of name field in a JsObject obj to v. Source Edit
proc isUndefined[T](x: T): bool {.noSideEffect, importjs: "(# === undefined)", ...raises: [], tags: [], forbids: [].}
- Checks if a value is exactly undefined. Source Edit
proc newJsAssoc[K: JsKey; V](): JsAssoc[K, V] {.importjs: "{@}", ...raises: [], tags: [], forbids: [].}
- Creates a new empty JsAssoc with key type K and value type V. Source Edit
proc newJsObject(): JsObject {.importjs: "{@}", ...raises: [], tags: [], forbids: [].}
- Creates a new empty JsObject. Source Edit
Iterators
Macros
macro `.()`(obj: JsObject; field: untyped; args: varargs[JsObject, jsFromAst]): JsObject
-
Experimental "method call" operator for type JsObject. Takes the name of a method of the JavaScript object (field) and calls it with args as arguments, returning a JsObject (which may be discarded, and may be undefined, if the method does not return anything, so be careful when using this.)
Example:
# Let's get back to the console example: var console {.importc, nodecl.}: JsObject let res = console.log("I return undefined!") console.log(res) # This prints undefined, as console.log always returns # undefined. Thus one has to be careful, when using # JsObject calls.
Source Edit macro `.()`[K: cstring; V: proc](obj: JsAssoc[K, V]; field: untyped; args: varargs[untyped]): auto
- Experimental "method call" operator for type JsAssoc. Takes the name of a method of the JavaScript object (field) and calls it with args as arguments. Here, everything is typechecked, so you do not have to worry about undefined return values. Source Edit
macro bindMethod(procedure: typed): auto {. ...deprecated: "Don\'t use it with closures".}
-
Takes the name of a procedure and wraps it into a lambda missing the first argument, which passes the JavaScript builtin this as the first argument to the procedure. Returns the resulting lambda.
Example:
We want to generate roughly this JavaScript:
var obj = {a: 10}; obj.someMethod = function() { return this.a + 42; };We can achieve this using the bindMethod macro:
let obj = JsObject{ a: 10 } proc someMethodImpl(that: JsObject): int = that.a.to(int) + 42 obj.someMethod = bindMethod someMethodImpl # Alternatively: obj.someMethod = bindMethod proc(that: JsObject): int = that.a.to(int) + 42
Source Edit macro `{}`(typ: typedesc; xs: varargs[untyped]): auto
-
Takes a typedesc as its first argument, and a series of expressions of type key: value, and returns a value of the specified type with each field key set to value, as specified in the arguments of {}.
Example:
# Let's say we have a type with a ton of fields, where some fields do not # need to be set, and we do not want those fields to be set to `nil`: type ExtremelyHugeType = ref object a, b, c, d, e, f, g: int h, i, j, k, l: cstring # And even more fields ... let obj = ExtremelyHugeType{ a: 1, k: "foo".cstring, d: 42 } # This generates roughly the same JavaScript as: {.emit: "var obj = {a: 1, k: "foo", d: 42};".}
Source Edit