Source Edit

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:

  1. import std/jsffi
  2. # Here, we are using jQuery for just a few calls and do not want to wrap the
  3. # whole library:
  5. # import the document object and the console
  6. var document {.importc, nodecl.}: JsObject
  7. var console {.importc, nodecl.}: JsObject
  8. # import the "$" function
  9. proc jq(selector: JsObject): JsObject {.importjs: "$$(#)".}
  11. # Use jQuery to make the following code run, after the document is ready.
  12. # This uses an experimental `.()` operator for `JsObject`, to emit
  13. # JavaScript calls, when no corresponding proc exists for `JsObject`.
  14. proc main =
  15.   jq(document).ready(proc() =
  16.     console.log("Hello JavaScript!")
  17.   )

Imports

macros, tables

Types

  1. js = JsObject

Source Edit 

  1. JsAssoc[K; V] = ref object of JsRoot

Statically typed wrapper around a JavaScript object. Source Edit 

  1. JsError {.importc: "Error".} = object of JsRoot
  2.   message*: cstring

Source Edit 

  1. JsEvalError {.importc: "EvalError".} = object of JsError

Source Edit 

  1. JsKey = concept atypeof(T)
  2.     cstring.toJsKey(T) is T

Source Edit 

  1. JsObject = ref object of JsRoot

Dynamically typed wrapper around a JavaScript object. Source Edit 

  1. JsRangeError {.importc: "RangeError".} = object of JsError

Source Edit 

  1. JsReferenceError {.importc: "ReferenceError".} = object of JsError

Source Edit 

  1. JsSyntaxError {.importc: "SyntaxError".} = object of JsError

Source Edit 

  1. JsTypeError {.importc: "TypeError".} = object of JsError

Source Edit 

  1. JsURIError {.importc: "URIError".} = object of JsError

Source Edit

Vars

  1. jsArguments {.importc: "arguments", nodecl.}: JsObject

JavaScript’s arguments pseudo-variable. Source Edit 

  1. jsDirname {.importc: "__dirname", nodecl.}: cstring

JavaScript’s __dirname pseudo-variable. Source Edit 

  1. jsFilename {.importc: "__filename", nodecl.}: cstring

JavaScript’s __filename pseudo-variable. Source Edit 

  1. jsNull {.importc: "null", nodecl.}: JsObject

JavaScript’s null literal. Source Edit 

  1. jsUndefined {.importc: "undefined", nodecl.}: JsObject

JavaScript’s undefined literal. Source Edit

Procs

  1. proc `%`(x, y: JsObject): JsObject {.importjs: "(# % #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `%=`(x, y: JsObject): JsObject {.importjs: "(# %= #)", discardable,
  2.                                       ...raises: [], tags: [], forbids: [].}

Source Edit 

  1. proc `&`(a, b: cstring): cstring {.importjs: "(# + #)", ...raises: [], tags: [],
  2.                                    forbids: [].}

Concatenation operator for JavaScript strings. Source Edit 

  1. proc `*`(x, y: JsObject): JsObject {.importjs: "(# * #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `**`(x, y: JsObject): JsObject {.importjs: "((#) ** #)", ...raises: [],
  2.                                       tags: [], forbids: [].}

Source Edit 

  1. proc `*=`(x, y: JsObject): JsObject {.importjs: "(# *= #)", discardable,
  2.                                       ...raises: [], tags: [], forbids: [].}

Source Edit 

  1. proc `+`(x, y: JsObject): JsObject {.importjs: "(# + #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `++`(x: JsObject): JsObject {.importjs: "(++#)", ...raises: [], tags: [],
  2.                                    forbids: [].}

Source Edit 

  1. proc `+=`(x, y: JsObject): JsObject {.importjs: "(# += #)", discardable,
  2.                                       ...raises: [], tags: [], forbids: [].}

Source Edit 

  1. proc `-`(x, y: JsObject): JsObject {.importjs: "(# - #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `--`(x: JsObject): JsObject {.importjs: "(--#)", ...raises: [], tags: [],
  2.                                    forbids: [].}

Source Edit 

  1. proc `-=`(x, y: JsObject): JsObject {.importjs: "(# -= #)", discardable,
  2.                                       ...raises: [], tags: [], forbids: [].}

Source Edit 

  1. proc `/`(x, y: JsObject): JsObject {.importjs: "(# / #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `/=`(x, y: JsObject): JsObject {.importjs: "(# /= #)", discardable,
  2.                                       ...raises: [], tags: [], forbids: [].}

Source Edit 

  1. proc `<`(x, y: JsObject): JsObject {.importjs: "(# < #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `<=`(x, y: JsObject): JsObject {.importjs: "(# <= #)", ...raises: [],
  2.                                       tags: [], forbids: [].}

Source Edit 

  1. proc `==`(x, y: JsRoot): bool {.importjs: "(# === #)", ...raises: [], tags: [],
  2.                                 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 

  1. proc `>`(x, y: JsObject): JsObject {.importjs: "(# > #)", ...raises: [], tags: [],
  2.                                      forbids: [].}

Source Edit 

  1. proc `>=`(x, y: JsObject): JsObject {.importjs: "(# >= #)", ...raises: [],
  2.                                       tags: [], forbids: [].}

Source Edit 

  1. proc `[]`(obj: JsObject; field: cstring): JsObject {.importjs: "#[#]",
  2.     ...raises: [], tags: [], forbids: [].}

Returns the value of a property of name field from a JsObject obj. Source Edit 

  1. proc `[]`(obj: JsObject; field: int): JsObject {.importjs: "#[#]", ...raises: [],
  2.     tags: [], forbids: [].}

Returns the value of a property of name field from a JsObject obj. Source Edit 

  1. proc `[]`[K: JsKey; V](obj: JsAssoc[K, V]; field: K): V {.importjs: "#[#]",
  2.     ...raises: [], tags: [], forbids: [].}

Returns the value of a property of name field from a JsAssoc obj. Source Edit 

  1. proc `[]`[V](obj: JsAssoc[cstring, V]; field: string): V

Source Edit 

  1. proc `[]=`[K: JsKey; V](obj: JsAssoc[K, V]; field: K; val: V) {.
  2.     importjs: "#[#] = #", ...raises: [], tags: [], forbids: [].}

Sets the value of a property of name field in a JsAssoc obj to v. Source Edit 

  1. proc `[]=`[T](obj: JsObject; field: cstring; val: T) {.importjs: "#[#] = #",
  2.     ...raises: [], tags: [], forbids: [].}

Sets the value of a property of name field in a JsObject obj to v. Source Edit 

  1. proc `[]=`[T](obj: JsObject; field: int; val: T) {.importjs: "#[#] = #",
  2.     ...raises: [], tags: [], forbids: [].}

Sets the value of a property of name field in a JsObject obj to v. Source Edit 

  1. proc `[]=`[V](obj: JsAssoc[cstring, V]; field: string; val: V)

Source Edit 

  1. proc `and`(x, y: JsObject): JsObject {.importjs: "(# && #)", ...raises: [],
  2.                                        tags: [], forbids: [].}

Source Edit 

  1. proc hasOwnProperty(x: JsObject; prop: cstring): bool {.
  2.     importjs: "#.hasOwnProperty(#)", ...raises: [], tags: [], forbids: [].}

Checks, whether x has a property of name prop. Source Edit 

  1. proc `in`(x, y: JsObject): JsObject {.importjs: "(# in #)", ...raises: [],
  2.                                       tags: [], forbids: [].}

Source Edit 

  1. proc isNull[T](x: T): bool {.noSideEffect, importjs: "(# === null)", ...raises: [],
  2.                              tags: [], forbids: [].}

Checks if a value is exactly null. Source Edit 

  1. proc isUndefined[T](x: T): bool {.noSideEffect, importjs: "(# === undefined)",
  2.                                   ...raises: [], tags: [], forbids: [].}

Checks if a value is exactly undefined. Source Edit 

  1. proc jsDelete(x: auto): JsObject {.importjs: "(delete #)", ...raises: [], tags: [],
  2.                                    forbids: [].}

JavaScript’s delete operator. Source Edit 

  1. proc jsNew(x: auto): JsObject {.importjs: "(new #)", ...raises: [], tags: [],
  2.                                 forbids: [].}

Turns a regular function call into an invocation of the JavaScript’s new operator. Source Edit 

  1. proc jsTypeOf(x: JsObject): cstring {.importjs: "typeof(#)", ...raises: [],
  2.                                       tags: [], forbids: [].}

Returns the name of the JsObject’s JavaScript type as a cstring. Source Edit 

  1. proc newJsAssoc[K: JsKey; V](): JsAssoc[K, V] {.importjs: "{@}", ...raises: [],
  2.     tags: [], forbids: [].}

Creates a new empty JsAssoc with key type K and value type V. Source Edit 

  1. proc newJsObject(): JsObject {.importjs: "{@}", ...raises: [], tags: [],
  2.                                forbids: [].}

Creates a new empty JsObject. Source Edit 

  1. proc `not`(x: JsObject): JsObject {.importjs: "(!#)", ...raises: [], tags: [],
  2.                                     forbids: [].}

Source Edit 

  1. proc `or`(x, y: JsObject): JsObject {.importjs: "(# || #)", ...raises: [],
  2.                                       tags: [], forbids: [].}

Source Edit 

  1. proc require(module: cstring): JsObject {.importc, ...raises: [], tags: [],
  2.     forbids: [].}

JavaScript’s require function. Source Edit 

  1. proc to(x: JsObject; T: typedesc): T:type {.importjs: "(#)", ...raises: [],
  2.     tags: [], forbids: [].}

Converts a JsObject x to type T. Source Edit 

  1. proc toJs[T](val: T): JsObject {.importjs: "(#)", ...raises: [], tags: [],
  2.                                  forbids: [].}

Converts a value of any type to type JsObject. Source Edit 

  1. proc toJsKey(text: cstring; t: type cstring): cstring

Source Edit 

  1. proc toJsKey[T: enum](text: cstring; t: type T): T

Source Edit 

  1. proc toJsKey[T: SomeFloat](text: cstring; t: type T): T {.
  2.     importjs: "parseFloat(#)", ...raises: [], tags: [], forbids: [].}

Source Edit 

  1. proc toJsKey[T: SomeInteger](text: cstring; t: type T): T {.
  2.     importjs: "parseInt(#)", ...raises: [], tags: [], forbids: [].}

Source Edit

Iterators

  1. iterator items(obj: JsObject): JsObject {....raises: [], tags: [], forbids: [].}

Yields the values of each field in a JsObject, wrapped into a JsObject. Source Edit 

  1. iterator items[K, V](assoc: JsAssoc[K, V]): V

Yields the values in a JsAssoc. Source Edit 

  1. iterator keys(obj: JsObject): cstring {....raises: [], tags: [], forbids: [].}

Yields the names of each field in a JsObject. Source Edit 

  1. iterator keys[K: JsKey; V](assoc: JsAssoc[K, V]): K

Yields the keys in a JsAssoc. Source Edit 

  1. iterator pairs(obj: JsObject): (cstring, JsObject) {....raises: [], tags: [],
  2.     forbids: [].}

Yields tuples of type (cstring, JsObject), with the first entry being the name of a fields in the JsObject and the second being its value wrapped into a JsObject. Source Edit 

  1. iterator pairs[K: JsKey; V](assoc: JsAssoc[K, V]): (K, V)

Yields tuples of type (K, V), with the first entry being a key in the JsAssoc and the second being its corresponding value. Source Edit

Macros

  1. macro `.`(obj: JsObject; field: untyped): JsObject

Experimental dot accessor (get) for type JsObject. Returns the value of a property of name field from a JsObject x.

Example:

  1. let obj = newJsObject()
  2. obj.a = 20
  3. assert obj.a.to(int) == 20

Source Edit 

  1. macro `.`[K: cstring; V](obj: JsAssoc[K, V]; field: untyped): V

Experimental dot accessor (get) for type JsAssoc. Returns the value of a property of name field from a JsObject x. Source Edit 

  1. 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:

  1. # Let's get back to the console example:
  2. var console {.importc, nodecl.}: JsObject
  3. let res = console.log("I return undefined!")
  4. console.log(res) # This prints undefined, as console.log always returns
  5.                  # undefined. Thus one has to be careful, when using
  6.                  # JsObject calls.

Source Edit 

  1. macro `.()`[K: cstring; V: proc](obj: JsAssoc[K, V]; field: untyped;
  2.                                  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 

  1. macro `.=`(obj: JsObject; field, value: untyped): untyped

Experimental dot accessor (set) for type JsObject. Sets the value of a property of name field in a JsObject x to value. Source Edit 

  1. macro `.=`[K: cstring; V](obj: JsAssoc[K, V]; field: untyped; value: V): untyped

Experimental dot accessor (set) for type JsAssoc. Sets the value of a property of name field in a JsObject x to value. Source Edit 

  1. macro bindMethod(procedure: typed): auto

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:

  1. var obj = {a: 10};
  2. obj.someMethod = function() {
  3.   return this.a + 42;
  4. };

We can achieve this using the bindMethod macro:

  1. let obj = JsObject{ a: 10 }
  2. proc someMethodImpl(that: JsObject): int =
  3.   that.a.to(int) + 42
  4. obj.someMethod = bindMethod someMethodImpl
  6. # Alternatively:
  7. obj.someMethod = bindMethod
  8.   proc(that: JsObject): int = that.a.to(int) + 42

Source Edit 

  1. macro jsFromAst(n: untyped): untyped

Source Edit 

  1. 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:

  1. # Let's say we have a type with a ton of fields, where some fields do not
  2. # need to be set, and we do not want those fields to be set to `nil`:
  3. type
  4.   ExtremelyHugeType = ref object
  5.     a, b, c, d, e, f, g: int
  6.     h, i, j, k, l: cstring
  7.     # And even more fields ...
  9. let obj = ExtremelyHugeType{ a: 1, k: "foo".cstring, d: 42 }
  11. # This generates roughly the same JavaScript as:
  12. {.emit: "var obj = {a: 1, k: "foo", d: 42};".}

Source Edit

Templates

  1. template toJs(s: string): JsObject

Source Edit