std/jsffi

Source Edit

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

Пример:

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

Импорты

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

Типы

js = JsObject: Source Edit
JsAssoc[K; V] = ref object of JsRoot: Статически типизированная оболочка вокруг JavaScript-объекта. Source Edit
JsError {.importc: "Error".} = object of JsRoot message*: cstring: Source Edit
JsEvalError {.importc: "EvalError".} = object of JsError: Source Edit
JsKey = concept atypeof(T) cstring.toJsKey(T) is T: Source Edit
JsObject = ref object of JsRoot: Динамически типизированная оболочка вокруг JavaScript-объекта. 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

Переменные

jsArguments {.importc: "arguments", nodecl.}: JsObject: Псевдопеременная arguments JavaScript. Source Edit
jsDirname {.importc: "__dirname", nodecl.}: cstring: Псевдопеременная __dirname JavaScript. Source Edit
jsFilename {.importc: "__filename", nodecl.}: cstring: Псевдопеременная __filename JavaScript. Source Edit
jsNull {.importc: "null", nodecl.}: JsObject: Литерал null JavaScript. Source Edit
jsUndefined {.importc: "undefined", nodecl.}: JsObject: Литерал undefined JavaScript. Source Edit

Процедуры

proc `%`(x, y: JsObject): JsObject {.importjs: "(# % #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `%=`(x, y: JsObject): JsObject {.importjs: "(# %= #)", discardable, ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `&`(a, b: cstring): cstring {.importjs: "(# + #)", ...raises: [], tags: [], forbids: [].}: Оператор конкатенации для строк JavaScript. Исходный код Редактировать
proc `*`(x, y: JsObject): JsObject {.importjs: "(# * #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `**`(x, y: JsObject): JsObject {.importjs: "((#) ** #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `*=`(x, y: JsObject): JsObject {.importjs: "(# *= #)", discardable, ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `+`(x, y: JsObject): JsObject {.importjs: "(# + #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `++`(x: JsObject): JsObject {.importjs: "(++#)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `+=`(x, y: JsObject): JsObject {.importjs: "(# += #)", discardable, ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `-`(x, y: JsObject): JsObject {.importjs: "(# - #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `--`(x: JsObject): JsObject {.importjs: "(--#)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `-=`(x, y: JsObject): JsObject {.importjs: "(# -= #)", discardable, ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `/`(x, y: JsObject): JsObject {.importjs: "(# / #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `/=`(x, y: JsObject): JsObject {.importjs: "(# /= #)", discardable, ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `<`(x, y: JsObject): JsObject {.importjs: "(# < #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `<=`(x, y: JsObject): JsObject {.importjs: "(# <= #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `==`(x, y: JsRoot): bool {.importjs: "(# === #)", ...raises: [], tags: [], forbids: [].}: Сравнивает два JsObject или JsAssoc. Однако будьте осторожны, так как это сравнение, как в JavaScript, поэтому, если ваши JsObject фактически являются JavaScript-объектами, а не строками или числами, это сравнение ссылок. Исходный код Редактировать
proc `>`(x, y: JsObject): JsObject {.importjs: "(# > #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `>=`(x, y: JsObject): JsObject {.importjs: "(# >= #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `[]`(obj: JsObject; field: cstring): JsObject {.importjs: "#[#]", ...raises: [], tags: [], forbids: [].}: Возвращает значение свойства с именем field из JsObject obj. Исходный код Редактировать
proc `[]`(obj: JsObject; field: int): JsObject {.importjs: "#[#]", ...raises: [], tags: [], forbids: [].}: Возвращает значение свойства с именем field из JsObject obj. Исходный код Редактировать
proc `[]`[K: JsKey; V](obj: JsAssoc[K, V]; field: K): V {.importjs: "#[#]", ...raises: [], tags: [], forbids: [].}: Возвращает значение свойства с именем field из JsAssoc obj. Исходный код Редактировать
proc `[]`[V](obj: JsAssoc[cstring, V]; field: string): V: Исходный код Редактировать
proc `[]=`[K: JsKey; V](obj: JsAssoc[K, V]; field: K; val: V) {. importjs: "#[#] = #", ...raises: [], tags: [], forbids: [].}: Устанавливает значение свойства с именем field в JsAssoc obj в v. Исходный код Редактировать
proc `[]=`[T](obj: JsObject; field: cstring; val: T) {.importjs: "#[#] = #", ...raises: [], tags: [], forbids: [].}: Устанавливает значение свойства с именем field в JsObject obj в v. Исходный код Редактировать
proc `[]=`[T](obj: JsObject; field: int; val: T) {.importjs: "#[#] = #", ...raises: [], tags: [], forbids: [].}: Устанавливает значение свойства с именем field в JsObject obj в v. Исходный код Редактировать
proc `[]=`[V](obj: JsAssoc[cstring, V]; field: string; val: V): Исходный код Редактировать
proc `and`(x, y: JsObject): JsObject {.importjs: "(# && #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc hasOwnProperty(x: JsObject; prop: cstring): bool {. importjs: "#.hasOwnProperty(#)", ...raises: [], tags: [], forbids: [].}: Проверяет, имеет ли x свойство с именем prop. Исходный код Редактировать
proc `in`(x, y: JsObject): JsObject {.importjs: "(# in #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc isNull[T](x: T): bool {.noSideEffect, importjs: "(# === null)", ...raises: [], tags: [], forbids: [].}: Проверяет, является ли значение точно null. Исходный код Редактировать
proc isUndefined[T](x: T): bool {.noSideEffect, importjs: "(# === undefined)", ...raises: [], tags: [], forbids: [].}: Проверяет, является ли значение точно undefined. Исходный код Редактировать
proc jsDelete(x: auto): JsObject {.importjs: "(delete #)", ...raises: [], tags: [], forbids: [].}: Оператор delete JavaScript. Исходный код Редактировать

proc jsNew(x: auto): JsObject {.importjs: "(new #)", ...raises: [], tags: [], forbids: [].}: Преобразует обычный вызов функции в вызов оператора new JavaScript. Исходный код Редактировать
proc jsTypeOf(x: JsObject): cstring {.importjs: "typeof(#)", ...raises: [], tags: [], forbids: [].}: Возвращает имя типа JavaScript объекта JsObject в виде cstring. Исходный код Редактировать
proc newJsAssoc[K: JsKey; V](): JsAssoc[K, V] {.importjs: "{@}", ...raises: [], tags: [], forbids: [].}: Создаёт новый пустой JsAssoc с типом ключа K и типом значения V. Исходный код Редактировать
proc newJsObject(): JsObject {.importjs: "{@}", ...raises: [], tags: [], forbids: [].}: Создаёт новый пустой JsObject. Исходный код Редактировать
proc `not`(x: JsObject): JsObject {.importjs: "(!#)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc `or`(x, y: JsObject): JsObject {.importjs: "(# || #)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc require(module: cstring): JsObject {.importc, ...raises: [], tags: [], forbids: [].}: Функция require JavaScript. Исходный код Редактировать
proc to(x: JsObject; T: typedesc): T:type {.importjs: "(#)", ...raises: [], tags: [], forbids: [].}: Преобразует JsObject x в тип T. Исходный код Редактировать
proc toJs[T](val: T): JsObject {.importjs: "(#)", ...raises: [], tags: [], forbids: [].}: Преобразует значение любого типа в тип JsObject. Исходный код Редактировать
proc toJsKey(text: cstring; t: type cstring): cstring: Исходный код Редактировать
proc toJsKey[T: enum](text: cstring; t: type T): T: Исходный код Редактировать
proc toJsKey[T: SomeFloat](text: cstring; t: type T): T {. importjs: "parseFloat(#)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать
proc toJsKey[T: SomeInteger](text: cstring; t: type T): T {. importjs: "parseInt(#)", ...raises: [], tags: [], forbids: [].}: Исходный код Редактировать

Итераторы

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

Макросы

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

let obj = newJsObject() obj.a = 20 assert obj.a.to(int) == 20
Исходный код Редактировать
macro `.`[K: cstring; V](obj: JsAssoc[K, V]; field: untyped): V: Экспериментальный оператор доступа к свойству (получение) для типа JsAssoc. Возвращает значение свойства с именем field из JsObject x. Исходный код Редактировать
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: proc](obj: JsAssoc[K, V]; field: untyped; args: varargs[untyped]): auto: Экспериментальный оператор "вызова метода" для типа JsAssoc. Принимает имя метода JavaScript-объекта (field) и вызывает его с args в качестве аргументов. Здесь всё проверяется по типу, поэтому вам не нужно беспокоиться о undefined значениях возврата. Исходный код Редактировать
macro `.=`(obj: JsObject; field, value: untyped): untyped: Экспериментальный оператор доступа к свойству (установка) для типа JsObject. Устанавливает значение свойства с именем field в JsObject x на значение value. Исходный код Редактировать
macro `.=`[K: cstring; V](obj: JsAssoc[K, V]; field: untyped; value: V): untyped: Экспериментальный оператор доступа к свойству (установка) для типа JsAssoc. Устанавливает значение свойства с именем field в JsObject x на значение value. Исходный код Редактировать
macro bindMethod(procedure: typed): auto {. ...deprecated: "Don\'t use it with closures".}: Устаревшее: Не используйте с замыканиями

Принимает имя процедуры и оборачивает его в лямбду, в которой отсутствует первый аргумент, который передаёт встроенную 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
Исходный код Редактировать
macro jsFromAst(n: untyped): untyped: Исходный код Редактировать
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};".}
Исходный код Редактировать

Шаблоны

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