jsffi

Этот модуль реализует типы и макросы для облегчения обертывания и взаимодействия с JavaScript-библиотеками. Использование предоставленных типов JsObject и JsAssoc вместе с предоставленными макросами позволяет обеспечить более плавное взаимодействие с JavaScript, например, быстрый и простой импорт JavaScript-переменных:

# 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 {.importcpp: "$$(#)".}

# 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!")
  )

Импорты

макросы, таблицы

Типы

JsKey = concept atypeof(T) cstring.toJsKey(T) is T: Исходный код Редактировать
JsObject = ref object of JsRoot: Динамически типизированный оболочкой над JavaScript-объектом. Исходный код Редактировать
JsAssoc[K; V] = ref object of JsRoot: Статически типизированный оболочкой над JavaScript-объектом. Исходный код Редактировать
js = JsObject: Исходный код Редактировать
JsError {...}{.importc: "Error".} = object of JsRoot message*: cstring: Исходный код Редактировать
JsEvalError {...}{.importc: "EvalError".} = object of JsError: Исходный код Редактировать
JsRangeError {...}{.importc: "RangeError".} = object of JsError: Исходный код Редактировать
JsReferenceError {...}{.importc: "ReferenceError".} = object of JsError: Исходный код Редактировать
JsSyntaxError {...}{.importc: "SyntaxError".} = object of JsError: Исходный код Редактировать
JsTypeError {...}{.importc: "TypeError".} = object of JsError: Исходный код Редактировать
JsURIError {...}{.importc: "URIError".} = object of JsError: Исходный код Редактировать

Переменные

jsArguments: JsObject: Псевдопеременная аргументов JavaScript Исходный код Редактировать
jsNull: JsObject: Литерал null JavaScript Исходный код Редактировать
jsUndefined: JsObject: Литерал undefined JavaScript Исходный код Редактировать
jsDirname: cstring: Псевдопеременная __dirname JavaScript Исходный код Редактировать
jsFilename: cstring: Псевдопеременная __filename JavaScript Исходный код Редактировать

Процедуры

proc toJsKey[T: SomeInteger](text: cstring; t: type T): T {...}{. importcpp: "parseInt(#)".}: Исходный код Редактировать
proc toJsKey[T: enum](text: cstring; t: type T): T: Исходный код Редактировать
proc toJsKey(text: cstring; t: type cstring): cstring: Исходный код Редактировать
proc toJsKey[T: SomeFloat](text: cstring; t: type T): T {...}{. importcpp: "parseFloat(#)".}: Исходный код Редактировать
proc isNull[T](x: T): bool {...}{.noSideEffect, importcpp: "(# === null)".}: Проверить, является ли значение точно null Исходный код Редактировать
proc isUndefined[T](x: T): bool {...}{.noSideEffect, importcpp: "(# === undefined)".}: Проверить, является ли значение точно undefined Исходный код Редактировать
proc newJsObject(): JsObject {...}{.importcpp: "{@}".}: Создаёт новый пустой JsObject Исходный код Редактировать
proc newJsAssoc[K: JsKey; V](): JsAssoc[K, V] {...}{.importcpp: "{@}".}: Создаёт новый пустой JsAssoc с типом ключа K и типом значения V. Исходный код Редактировать
proc hasOwnProperty(x: JsObject; prop: cstring): bool {...}{. importcpp: "#.hasOwnProperty(#)".}: Проверяет, содержит ли x свойство с именем prop. Исходный код Редактировать
proc jsTypeOf(x: JsObject): cstring {...}{.importcpp: "typeof(#)".}: Возвращает имя JavaScript-типа JsObject в виде cstring. Исходный код Редактировать
proc jsNew(x: auto): JsObject {...}{.importcpp: "(new #)".}: Преобразует обычный вызов функции в вызов JavaScript-оператора new. Исходный код Редактировать
proc jsDelete(x: auto): JsObject {...}{.importcpp: "(delete #)".}: JavaScript-оператор delete. Исходный код Редактировать
proc require(module: cstring): JsObject {...}{.importc.}: JavaScript-функция require. Исходный код Редактировать
proc to(x: JsObject; T: typedesc): T:type {...}{.importcpp: "(#)".}: Преобразует JsObject x к типу T. Исходный код Редактировать
proc toJs[T](val: T): JsObject {...}{.importcpp: "(#)".}: Преобразует значение любого типа к типу JsObject Исходный код Редактировать
proc `&`(a, b: cstring): cstring {...}{.importcpp: "(# + #)".}: Оператор конкатенации для JavaScript-строк Исходный код Редактировать
proc `+`(x, y: JsObject): JsObject {...}{.importcpp: "(# + #)".}: Исходный код Редактировать
proc `-`(x, y: JsObject): JsObject {...}{.importcpp: "(# - #)".}: Исходный код Редактировать
proc `*`(x, y: JsObject): JsObject {...}{.importcpp: "(# * #)".}: Исходный код Редактировать
proc `/`(x, y: JsObject): JsObject {...}{.importcpp: "(# / #)".}: Исходный код Редактировать
proc `%`(x, y: JsObject): JsObject {...}{.importcpp: "(# % #)".}: Исходный код Редактировать
proc `+=`(x, y: JsObject): JsObject {...}{.importcpp: "(# += #)", discardable.}: Исходный код Редактировать
proc `-=`(x, y: JsObject): JsObject {...}{.importcpp: "(# -= #)", discardable.}: Исходный код Редактировать
proc `*=`(x, y: JsObject): JsObject {...}{.importcpp: "(# *= #)", discardable.}: Исходный код Редактировать
proc `/=`(x, y: JsObject): JsObject {...}{.importcpp: "(# /= #)", discardable.}: Исходный код Редактировать
proc `%=`(x, y: JsObject): JsObject {...}{.importcpp: "(# %= #)", discardable.}: Исходный код Редактировать
proc `++`(x: JsObject): JsObject {...}{.importcpp: "(++#)".}: Исходный код Редактировать
proc `--`(x: JsObject): JsObject {...}{.importcpp: "(--#)".}: Исходный код Редактировать
proc `>`(x, y: JsObject): JsObject {...}{.importcpp: "(# > #)".}: Исходный код Редактировать
proc `<`(x, y: JsObject): JsObject {...}{.importcpp: "(# < #)".}: Исходный код Редактировать
proc `>=`(x, y: JsObject): JsObject {...}{.importcpp: "(# >= #)".}: Исходный код Редактировать
proc `<=`(x, y: JsObject): JsObject {...}{.importcpp: "(# <= #)".}: Исходный код Редактировать
proc `and`(x, y: JsObject): JsObject {...}{.importcpp: "(# && #)".}: Исходный код Редактировать
proc `or`(x, y: JsObject): JsObject {...}{.importcpp: "(# || #)".}: Исходный код Редактировать
proc `not`(x: JsObject): JsObject {...}{.importcpp: "(!#)".}: Исходный код Редактировать
proc `in`(x, y: JsObject): JsObject {...}{.importcpp: "(# in #)".}: Исходный код Редактировать
proc `[]`(obj: JsObject; field: cstring): JsObject {...}{.importcpp: "#[#]".}: Возвращает значение свойства с именем field из JsObject obj. Исходный код Редактировать
proc `[]`(obj: JsObject; field: int): JsObject {...}{.importcpp: "#[#]".}: Возвращает значение свойства с именем field из JsObject obj. Исходный код Редактировать
proc `[]=`[T](obj: JsObject; field: cstring; val: T) {...}{.importcpp: "#[#] = #".}: Устанавливает значение свойства с именем field в JsObject obj на v. Исходный код Редактировать
proc `[]=`[T](obj: JsObject; field: int; val: T) {...}{.importcpp: "#[#] = #".}: Устанавливает значение свойства с именем field в JsObject obj на v. Исходный код Редактировать
proc `[]`[K: JsKey; V](obj: JsAssoc[K, V]; field: K): V {...}{.importcpp: "#[#]".}: Возвращает значение свойства с именем field из JsAssoc obj. Исходный код Редактировать
proc `[]=`[K: JsKey; V](obj: JsAssoc[K, V]; field: K; val: V) {...}{. importcpp: "#[#] = #".}

Установите значение свойства с именем field в JsAssoc obj на значение v. Источник Редактировать
proc `[]`[V](obj: JsAssoc[cstring, V]; field: string): V: Источник Редактировать
proc `[]=`[V](obj: JsAssoc[cstring, V]; field: string; val: V): Источник Редактировать
proc `==`(x, y: JsRoot): bool {...}{.importcpp: "(# === #)".}: Сравните два JsObject или JsAssoc. Будьте осторожны, так как это сравнение, как в JavaScript, поэтому, если ваши JsObject — фактически JavaScript-объекты, а не строки или числа, это сравнение ссылок. Источник Редактировать

Итераторы

iterator pairs(obj: JsObject): (cstring, JsObject) {...}{.raises: [], tags: [].}: Возвращает кортежи типа (cstring, JsObject), где первый элемент — name поля в JsObject, а второй — его значение, обернутое в JsObject. Источник Редактировать
iterator items(obj: JsObject): JsObject {...}{.raises: [], tags: [].}: Возвращает values каждого поля в JsObject, обернутое в JsObject. Источник Редактировать
iterator keys(obj: JsObject): cstring {...}{.raises: [], tags: [].}: Возвращает names каждого поля в JsObject. Источник Редактировать
iterator pairs[K: JsKey; V](assoc: JsAssoc[K, V]): (K, V): Возвращает кортежи типа (K, V), где первый элемент — key в JsAssoc, а второй — соответствующее значение. Источник Редактировать
iterator items[K, V](assoc: JsAssoc[K, V]): V: Возвращает values в JsAssoc. Источник Редактировать
iterator keys[K: JsKey; V](assoc: JsAssoc[K, V]): K: Возвращает keys в JsAssoc. Источник Редактировать

Макросы

macro jsFromAst(n: untyped): untyped

Источник Редактировать

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

Экспериментальный оператор доступа (получение) для типа JsObject. Возвращает значение свойства с именем field из JsObject x.

Пример:

let obj = newJsObject()
obj.a = 20
console.log(obj.a) # puts 20 onto the console.

Источник Редактировать

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

Экспериментальный оператор доступа (установка) для типа JsObject. Устанавливает значение свойства с именем field в JsObject x на значение value. Источник Редактировать

macro `.()`(obj: JsObject; field: untyped; args: varargs[JsObject, jsFromAst]): JsObject

Экспериментальный оператор "вызова метода" для типа JsObject. Принимает имя метода JavaScript-объекта (field) и вызывает его с аргументами args, возвращая JsObject (который может быть проигнорирован, и может быть undefined, если метод ничего не возвращает, поэтому будьте осторожны при использовании этого.)

Пример:

# 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.

Источник Редактировать

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

Экспериментальный оператор доступа (получение) для типа JsAssoc. Возвращает значение свойства с именем field из JsObject x. Источник Редактировать

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

Экспериментальный оператор доступа (установка) для типа JsAssoc. Устанавливает значение свойства с именем field в JsObject x на значение value. Источник Редактировать

macro `.()`[K: cstring; V: proc](obj: JsAssoc[K, V]; field: untyped; args: varargs[untyped]): auto

Экспериментальный оператор "вызова метода" для типа JsAssoc. Принимает имя метода JavaScript-объекта (field) и вызывает его с аргументами args. Здесь всё типизировано, так что вам не нужно беспокоиться о undefined значениях возврата. Источник Редактировать

macro `{}`(typ: typedesc; xs: varargs[untyped]): auto

Принимает typedesc в качестве первого аргумента и ряд выражений типа key: value, и возвращает значение указанного типа с каждым полем key установленным на value, как указано в аргументах {}.

Пример:

# 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};".}

Источник Редактировать

macro bindMethod(procedure: typed): auto

Принимает имя процедуры и оборачивает его в лямбда-выражение, в котором отсутствует первый аргумент, который передает JavaScript-встроенную функцию this в качестве первого аргумента процедуре. Возвращает полученное лямбда-выражение.

Пример:

Мы хотим сгенерировать примерно такой JavaScript:

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

Мы можем добиться этого, используя макрос bindMethod.

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

Источник Редактировать

Шаблоны

template toJs(s: string): JsObject: Источник Редактировать