Interop from JavaScript to Shen¶

The environment object, $, comes with additional functions to make JavaScript functions callable from Shen, setting global symbols, declaring types and macros, etc.

Exported Functions¶

Important

Some of these will return a promise since they invoke kernel functions. Recommended practice would be to await any calls made on the environment object.

assign(name, value)¶

Assigns a value to a global symbol, creating that global symbol if necessary.

Parameters

name (string) – Global symbol name.
value (any) – The value to assign.

Returns

The assigned value.

caller(name)¶

Returns a handle to a function in the Shen environment which automatically performs trampoline settling.

Parameters: name (string) – Function name.
Returns: A function to call Shen function by given name. Returned function will be async.

cons(x, y)¶

Creates a new Cons cell with the given head and tail values.

Parameters

x (any) – Any Shen or JavaScript value.
y (any) – Any Shen or JavaScript value.

Returns

A new Cons.

define(name, f)¶

Defines a new global function in the Shen environment by the given name. Function gets wrapped so it automatically handles partial application.

Parameters

name (string) – Name which function will be accessible by, including package prefix(es).
f (function) – JavaScript function to defer fully-applied invocation to.

Returns

Name as a symbol.

defineTyped(name, type, f)¶

Defines a new global function in the Shen environment by the given name and declared Shen type signature. Function gets wrapped so it automatically handles partial application.

Parameters

name (string) – Name which function will be accessible by, including package prefix(es).
type (any) – Shen type signature in array tree form, gets recursively converted to Shen lists.
f (function) – JavaScript function to defer fully-applied invocation to.

Returns

Name as a symbol.

defmacro(name, f)¶

Defines a macro in the Shen environment by the given name. Syntax gets pre-processed with toArrayTree before being passed into wrapped function. Result returned from f gets post-processed with toListTree. If f returns undefined, then it causes the macro to have no effect.

Parameters

name (string) – Name which macro function will be accessible by, including package prefix(es).
f (function) – JavaScript function to defer invocation to.

Returns

Name as a symbol.

equate(x, y)¶

Determines if x and y are equal using Shen-specific semantics.

Parameters

x (any) – Any Shen or JavaScript value.
y (any) – Any Shen or JavaScript value.

Returns

A JavaScript boolean.

evalJs(ast)¶

Converts JavaScript AST to JavaScript syntax string and evaluates in isolated context.

Parameters: ast (ast) – JavaScript AST Node.
Returns: Evaluation result.

evalKl(expr)¶

Invokes the backend eval-kl function which will evaluate the expression tree in the Shen environment.

Parameters: expr (expr) – Parsed KLambda expression tree.
Returns: Evaluation result.

evalShen(expr)¶

Invokes the Shen eval function which will evaluate the expression tree in the Shen environment.

Parameters: expr (expr) – Parsed Shen expression tree.
Returns: Evaluation result.

exec(syntax)¶

Parses and evaluates all Shen syntax forms passed in. Returns final evaluation result.

Parameters: syntax (string) – Shen syntax.
Returns: Final evaluation result.

execEach(syntax)¶

Parses and evaluates all Shen syntax forms passed in. Returns array of evaluation results.

Parameters: syntax (string) – Shen syntax.
Returns: Array of evaluation results.

inline(name, dataType, paramTypes, f)¶

Registers a new inline rule for JavaScript code generation. When the KLambda-to-JavaScript transpilier encounters a form starting with a symbol named name, it will build child forms and then pass the rendered ASTs into f. Whatever f returns gets inserted into the greater JavaScript AST at the relative point where the form was encountered.

Example:

// Renders a `(not X)` call with the JavaScript `!` operator
// and inserts type conversions only as needed
inline('not', 'JsBool', ['JsBool'], x => Unary('!', x));

Parameters

name (string) – Name of symbol that triggers this rule to be applied.
dataType (string) – The type of the whole expression, or null if it is unknown.
paramTypes (array) – The types of argument expressions, each can be null if they are unknown.
f (function) – Function that handles the JavaScript AST transformation for this rule.

Returns

f.

load(path)¶

Invokes the Shen load function which will read the file at the given path and evaluates its contents.

Parameters: path (string) – Local file system path relative to shen.*home-directory*
Returns: The loaded symbol.

parse(syntax)¶

Parses Shen syntax using the read-from-string function from the Shen kernel.

Parameters: syntax (string) – Shen syntax in string form.
Returns: A Shen list of syntax forms, wrapped in a promise.

pre(name, f)¶

Registers a new pre-processor rule for JavaScript code generation. Similar to inline, but child forms are not rendered and are passed into f as KLambda expression trees. f should then return a JavaScript AST which will get inserted into the greater JavaScript AST at the relative point where the form was encountered.

Example:

// Evaluates math expression at build time and inserts result
// in place of JavaScript AST that would have been built
pre('build-time-math', x => evalShen(x));

Parameters

name (string) – Name of symbol that triggers this rule to be applied.
f (function) – Function that handles the KLambda expression tree to JavaScript AST conversion.

Returns

f.

show(value)¶

Builds Shen-specific string representation of value.

Parameters: value (any) – Value to show.
Returns: String representation of value.

symbol(name, value)¶

Declares Shen global symbol by the given name (with added earmuffs per convention), setting it to given initial value and declaring a function by the given name that accesses it.

Example: symbol('package.thing', 0) declares global symbol package.*thing*, sets it to 0 and declares function package.thing which takes no arguments and returns (value package.*thing*).

Parameters

name (string) – Name of accessor function and basis for name of global symbol.
value (any) – Value to initialise global symbol with.

Returns

value.

toArray(x)¶

Builds a JavaScript array from a Shen list. Elements are not transformed. x is passed through if not a Shen list.

Parameters: x (any) – A Shen list or any other value.
Returns: A JavaScript array or whatever was passed in.

toArrayTree(x)¶

Recursively builds a JavaScript array tree from a Shen list tree. Non-list children are not transformed. x is passed through if not a Shen list.

Parameters: x (any) – A tree of Shen lists or any other value.
Returns: A tree of JavaScript arrays or whatever was passed in.

toList(x[, tail = null])¶

Builds a Shen list from a JavaScript array. Elements are not transformed. x is passed through if not a JavaScript array.

Aliased as r for brevity in generated code.

Parameters

x (any) – A JavaScript array or any other value.
tail (any) – Optional tail value for the final Cons cell, instead of null. Ignored if x is not an array.

Returns

A Shen list or whatever was passed in.

toListTree(x)¶

Recursively builds a Shen list tree from a JavaScript array tree. Non-list children are not transformed. x is passed through if not a JavaScript array.

Parameters: x (any) – A tree of nested JavaScript arrays or any other value.
Returns: A tree of nested Shen lists or whatever was passed in.

valueOf(name)¶

Returns the value of the global symbol with the given name.

Parameters: name (string) – Name of global symbol.
Returns: Global symbol’s value.
Throws: Error if symbol is not bound.

Interop from Shen to JavaScript¶

ShenScript provides functions in the js namespace to access JavaScript standard classes and functionality.

Raw Operators¶

Functions starting with js.raw allow access to underlying JavaScript operators without any additional typechecks or conversions. Operations are inlined when fully applied but can still be partially applied or passed as arguments like any other function.

(js.raw.== X Y)

Applies the JavaScript == operator to arguments without additional typechecks or conversions.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A JavaScript boolean.

(js.raw.=== X Y)

Applies the JavaScript === operator to arguments without additional typechecks or conversions.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A JavaScript boolean.

(js.raw.!= X Y)

Applies the JavaScript != operator to arguments without additional typechecks or conversions.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A JavaScript boolean.

(js.raw.!== X Y)

Applies the JavaScript !== operator to arguments without additional typechecks or conversions.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A JavaScript boolean.

(js.raw.and X Y)

Applies the JavaScript && operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Operator is inlined when fully applied.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever && does based on JavaScript-specific behavior.

(js.raw.or X Y)

Applies the JavaScript || operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Operator is inlined when fully applied.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever || does based on JavaScript-specific behavior.

(js.raw.not X)

Performs JavaScript boolean inversion.

Parameters: X (any) – Value to invert.
Returns: A JavaScript boolean.

(js.raw.+ X Y)

Applies the JavaScript + operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever + does based on JavaScript-specific behavior.

(js.raw.- X Y)

Applies the JavaScript - operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever - does based on JavaScript-specific behavior.

(js.raw.* X Y)

Applies the JavaScript * operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever * does based on JavaScript-specific behavior.

(js.raw./ X Y)

Applies the JavaScript / operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever / does based on JavaScript-specific behavior.

(js.raw.** X Y)

Applies the JavaScript ** operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever ** does based on JavaScript-specific behavior.

(js.raw.< X Y)

Applies the JavaScript < operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever < does based on JavaScript-specific behavior.

(js.raw.> X Y)

Applies the JavaScript > operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever > does based on JavaScript-specific behavior.

(js.raw.<= X Y)

Applies the JavaScript <= operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever <= does based on JavaScript-specific behavior.

(js.raw.>= X Y)

Applies the JavaScript >= operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever >= does based on JavaScript-specific behavior.

(js.raw.bitwise.not X)

Applies the JavaScript ! operator to argument without additional typechecks, perserving JavaScript coercion behavior.

Parameters: X (any) – Whatever.
Returns: Whatever ! does based on JavaScript-specific behavior.

(js.raw.bitwise.and X Y)

Applies the JavaScript & operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever & does based on JavaScript-specific behavior.

(js.raw.bitwise.or X Y)

Applies the JavaScript | operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever | does based on JavaScript-specific behavior.

(js.raw.bitwise.xor X Y)

Applies the JavaScript ^ operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

Whatever ^ does based on JavaScript-specific behavior.

(js.raw.<< X Y)

Applies the JavaScript << operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Value to shift.
Y (any) – Amount to shift by.

Returns

Whatever << does based on JavaScript-specific behavior.

(js.raw.>> X Y)

Applies the JavaScript >> operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Value to shift.
Y (any) – Amount to shift by.

Returns

Whatever >> does based on JavaScript-specific behavior.

(js.raw.>>> X Y)

Applies the JavaScript >>> operator to arguments without additional typechecks, perserving JavaScript coercion behavior.

Parameters

X (any) – Value to shift.
Y (any) – Amount to shift by.

Returns

Whatever >>> does based on JavaScript-specific behavior.

(js.raw.delete Object Key)

Removes a key from an object.

Parameters

Object (object) – Object to remove key from.
Key (any) – String or symbol name of key to remove.

Returns

JavaScript true if the delete was successful.

(js.raw.eval Code)

Warning

Using eval is even more dangerous than usual in ShenScript because it will be difficult to know what indentifiers will be in scope and how their names might have been aliased when code is evaluated.

Note

With js.raw.eval, the call does get inlined when fully applied, which might help a bit with the scoping issues.

So, for instance, (let X 2 (js.raw.eval "1 + X")) would successfully evaluate to 3 with js.raw.eval where it would fail with js.eval.

Calls the built-in JavaScript eval function.

Parameters: Code (string) – JavaScript code in string form.
Returns: The result of evaluating the code.

(js.raw.in Key Object)

Determines if value is a key in an object.

Parameters

Key (any) – String or symbol name of a property.
Object (object) – Object that might contain a property by that key.

Returns

A JavaScript boolean.

(js.raw.instanceof X Class)

Determines if value is the product of a constructor, class or anything higher up its prototype chain.

Parameters

X (any) – The value to inspect.
Class (class) – A class or constructor function.

Returns

A JavaScript boolean.

(js.raw.typeof X)

Applies the JavaScript typeof operator to a value.

Parameters: X (any) – Anything.
Returns: A string identifying the basic type of the value: object, number, string, symbol, undefined, boolean.

(js.raw.void X)

Applies the JavaScript void operator to argument, which will always return undefined.

Parameters: X (any) – Anything.
Returns: undefined.

Typed Operators¶

js.== : A --> B --> boolean

Applies the JavaScript == operator to arguments without additional typechecks, and converts result to a Shen boolean.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A Shen boolean.

js.=== : A --> B --> boolean

Applies the JavaScript === operator to arguments without additional typechecks, and converts result to a Shen boolean.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A Shen boolean.

js.!= : A --> B --> boolean

Applies the JavaScript != operator to arguments without additional typechecks, and converts result to a Shen boolean.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A Shen boolean.

js.!== : A --> B --> boolean

Applies the JavaScript !== operator to arguments without additional typechecks, and converts result to a Shen boolean.

Parameters

X (any) – Whatever.
Y (any) – Whatever.

Returns

A Shen boolean.

js.% : number --> number --> number

Checks arguments are numbers and then applies the JavaScript % operator.

Parameters

X (number) – A Shen number.
Y (number) – A Shen number.

Returns

A Shen number.

js.** : number --> number --> number

Checks arguments are numbers and then applies the JavaScript ** operator.

Parameters

X (number) – A Shen number.
Y (number) – A Shen number.

Returns

A Shen number.

js.bitwise.not : number --> number

Checks argument is a number and then applies the JavaScript ~ operator.

Parameters: X (number) – A Shen number.
Returns: A Shen number.

js.bitwise.and : number --> number --> number

Checks arguments are numbers and then applies the JavaScript & operator.

Parameters

X (number) – A Shen number.
Y (number) – A Shen number.

Returns

A Shen number.

js.bitwise.or : number --> number --> number

Checks arguments are numbers and then applies the JavaScript | operator.

Parameters

X (number) – A Shen number.
Y (number) – A Shen number.

Returns

A Shen number.

js.bitwise.xor : number --> number --> number

Checks arguments are numbers and then applies the JavaScript ^ operator.

Parameters

X (number) – A Shen number.
Y (number) – A Shen number.

Returns

A Shen number.

js.<< : number --> number --> number

Checks arguments are numbers and then applies the JavaScript << operator.

Parameters

X (number) – Value to shift.
Y (number) – Amount to shift by.

Returns

A Shen number.

js.>> : number --> number --> number

Checks arguments are numbers and then applies the JavaScript >> operator.

Parameters

X (number) – Value to shift.
Y (number) – Amount to shift by.

Returns

A Shen number.

js.>>> : number --> number --> number

Checks arguments are numbers and then applies the JavaScript >>> operator.

Parameters

X (number) – Value to shift.
Y (number) – Amount to shift by.

Returns

A Shen number.

Typed Standard Functions¶

js.clear : js.timeout --> unit

Cancels or discontinues a task scheduled by js.delay or js.repeat.

Parameters: Timeout (js.timeout) – A timeout handle returned by js.delay or js.repeat.

js.decode-uri : string --> string

Decodes a URI by un-escaping special characters.

Parameters: Uri (string) – URI to decode.
Returns: Decoded URI.

js.decode-uri-component : string --> string

Decodes a URI component by un-escaping special characters.

Parameters: Uri (string) – URI component to decode.
Returns: Decoded URI.

js.delay : number --> (lazy A) --> js.timeout

Calls standard JavaScript setTimeout function, but with arguments reversed.

Parameters

Duration (number) – Time in milliseconds to delay running continuation.
Continuation (function) – Function to run. Expected to take 0 arguments.

Returns

A timeout handle.

js.encode-uri : string --> string

Encodes a URI by escaping special characters.

Parameters: Uri (string) – URI to encode.
Returns: Encoded URI.

js.encode-uri-component : string --> string

Encodes a URI component by escaping special characters.

Parameters: Uri (string) – URI component to encode.
Returns: Encoded URI.

js.eval : string --> A

Warning

Using eval is even more dangerous than usual in ShenScript because it will be difficult to know what indentifiers will be in scope and how their names might have been aliased when code is evaluated.

Note

Unlike js.raw.eval, the never gets inlined, so the code gets evaluated in another scope.

So, for instance, (let X 2 (js.eval "1 + X")) would fail with X is not defined where with js.raw.eval, it would work.

Calls the built-in JavaScript eval function, asserting argument is a string.

Parameters: Code (string) – JavaScript code in string form.
Returns: The result of evaluating the code.

js.log : A --> unit

Logs given value using console.log.

Parameters: X (any) – Value to log
Returns: Empty list.

js.parse-float : string --> number

Parses a floating-point number.

Parameters: String (string) – Numeric string to parse.
Returns: Parsed number.
Throws: If string does not represent a valid number.

js.parse-int : string --> number

Parses an integral number with radix specified to be 10 to avoid unusual parsing behavior.

Parameters: String (string) – Numeric string to parse.
Returns: Parsed number.
Throws: If string does not represent a valid number.

js.parse-int-with-radix : string --> number --> number

Parses an integral number with the given radix.

Parameters

String (string) – Numeric string to parse.
Radix (number) – Radix to parse the number with, an integer 2 or greater.

Returns

Parsed number.

Throws

If string does not represent a valid number or invalid radix is passed.

js.repeat : number --> (lazy A) --> js.timeout

Calls standard JavaScript setInterval function, but with arguments reversed.

Parameters

Duration (number) – Time in milliseconds to between calls of continuation.
Continuation (function) – Function to run. Expected to take 0 arguments.

Returns

A timeout handle.

js.sleep : number --> unit

Simulates a blocking Thread.sleep by awaiting a promise resolved with setTimeout.

Returns a promise.

Parameters: Duration (number) – Time in milliseconds to sleep.

JSON Functions¶

(json.parse String)

JSON.parse.

Parameters: String (string) – Serialized JavaScript value.
Returns: Object parsed from String.

(json.str Value)

JSON.stringify.

Parameters: Value (any) – JavaScript value to serialize.
Returns: Value serialized to string.

Object Construction, Member Access¶

Remember that properties on JavaScript object are named with strings, so using Shen strings for property names is recommended for the function below. For example, the JavaScript code x.y would get written like (js.get X "y").

Idle symbols can be used for property names, but they will represented with interned JavaScript symbols.

(js.get Object Property)

Retrieves a property’s value from a JavaScript object.

Parameters

Object (object) – Object to read from.
Property (any) – Property name to get.

Returns

Property value.

js.get-macro: Macro that converts variable-depth accessor syntax like (. X Y Z) to (js.get (js.get X Y) Z).

(js.new Class Args)

Creates new instance of class by calling given constructor on argument list.

Parameters

Class (constructor) – Constructor to call.
Args (list) – Constructor arguments in a Shen list.

Returns

New instance of Class.

(js.obj Values)

Creates new Object with properties of given names and values.

Parameters: Values (list) – A flat Shen list of property names and values, like ["name1" Val1 "name2" Val2].
Returns: New Object.

js.obj-macro: Macro that converts syntax like ({ A B C D }) to (js.obj [A B C D]).

(js.set Object Property Value)

Assigns property on a JavaScript object.

Parameters

Object (object) – Object to write to.
Property (any) – Property name to set.
Value (any) – Value to assign.

Returns

Value, just like the JavaScript assignment operator.

Recognisor Functions¶

js.array? : A --> boolean

Determines if value is a JavaScript array.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.async? : A --> boolean

Determines if value is an asynchronous function.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.boolean? : A --> boolean

Determines if value is a JavaScript boolean.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.defined? : A --> boolean

Determines if value is not undefined.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.false? : A --> boolean

Determines if value is the JavaScript false value.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.falsy? : A --> boolean

Determines if value is coercible to false by JavaScript standards.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.finite? : A --> boolean

Determines if value is a finite number.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.function? : A --> boolean

Determines if value is a function. This test will also work for Shen functions.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.generator? : A --> boolean

Determines if value is a generator function.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.infinite? : A --> boolean

Determines if value is positive or negative infinity.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.+infinity? : A --> boolean

Determines if value is positive infinity.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.-infinity? : A --> boolean

Determines if value is negative infinity.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.integer? : A --> boolean

Determines if value is an integer.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.+integer? : A --> boolean

Determines if value is a positive integer.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.-integer? : A --> boolean

Determines if value is a negative integer.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.nan? : A --> boolean

Determines if value is NaN (not-a-number) which will normally not be equal to itself according to the === operator.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.null? : A --> boolean

Determines if value is null.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.object? : A --> boolean

Determines if value is an object with the direct protoype Object which means it is probably the product of object literal syntax.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.symbol? : A --> boolean

Determines if a value is a JavaScript symbol. Shen symbols are represented with JS symbols, so this test will pass for idle symbols as well.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.true? : A --> boolean

Determines if value is the JavaScript true value.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.truthy? : A --> boolean

Determines if value is coercible to true by JavaScript standards.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

js.undefined? : A --> boolean

Determines if value is undefined.

Parameters: X (any) – Value to inspect.
Returns: A Shen boolean.

Global Classes, Objects and Values¶

Functions to retrieve common JavaScript globals. All take zero arguments and return what they’re called. They Shen global symbols name with additional earmuffs (e.g. js.*Array*) where the value is actually held.

Hint

Some of these are not available in all JavaScript environments. You can check if a symbol is defined with (bound? js.*Array*).

(js.Array): Returns the global JavaScript Array class.

(js.ArrayBuffer): Returns the global JavaScript ArrayBuffer class.

(js.AsyncFunction): Returns the global JavaScript AsyncFunction class.

(js.Atomics): Returns the global JavaScript Atomics class. This is not available in Firefox.

(js.Boolean): Returns the global JavaScript Boolean class.

(js.console): Returns the global JavaScript console object.

(js.DataView): Returns the global JavaScript DataView class.

(js.Date): Returns the global JavaScript Date class.

(js.Function): Returns the global JavaScript Function class.

(js.GeneratorFunction): Returns the global JavaScript GeneratorFunction class.

(js.globalThis): Returns the global JavaScript globalThis object. If globalThis is not defined in this JavaScript environment, then window, global, etc is used as appropriate.

(js.Infinity): Returns the JavaScript Infinity value.

(js.JSON): Returns the global JavaScript JSON object.

(js.Map): Returns the global JavaScript Map class.

(js.NaN): Returns the JavaScript NaN value.

(js.Number): Returns the global JavaScript Number class.

(js.null): Returns the JavaScript null value.

(js.Object): Returns the global JavaScript Object class.

(js.Promise): Returns the global JavaScript Promise class.

(js.Proxy): Returns the global JavaScript Proxy class.

(js.Reflect): Returns the global JavaScript Reflect class.

(js.RegExp): Returns the global JavaScript RegExp class.

(js.Set): Returns the global JavaScript Set class.

(js.SharedArrayBuffer): Returns the global JavaScript SharedArrayBuffer class. This is not available in Firefox.

(js.String): Returns the global JavaScript String class.

(js.Symbol): Returns the global JavaScript Symbol class.

(js.undefined): Returns the JavaScript undefined value.

(js.WeakMap): Returns the global JavaScript WeakMap class.

(js.WeakSet): Returns the global JavaScript WeakSet class.

(js.WebAssembly): Returns the global JavaScript WebAssembly class.

Web-specific Interop¶

Only available when running in a browser or browser-based environment like Electron.

(web.atob String)

Converts a string to a base64-encoded string.

Parameters: String (string) – Any string.

(web.btoa Base64)

Converts a base64-encoded string to a string.

Parameters: String (string) – Any base64 string.

(web.confirm? Message)

Shows a synchronous web confirm pop-up with the given message. Returns Shen true or false depending on whether the user hit “OK” or “Cancel”.

Parameters: Message (string) – Message to show on the pop-up.

(web.document): Returns the global document.

(web.fetch-json Url)

Same as web.fetch-text, but parses received value as JSON.

Parameters: Url (string) – URL to GET from.
Returns: A JSON object wrapped in a Promise.

(web.fetch-json* Url)

Same as web.fetch-text*, but parses received values as JSON.

Parameters: Urls (list) – A Shen list of URLs to GET from.
Returns: A Shen list of JSON objects wrapped in :js:`Promise`s.

(web.fetch-text Url)

Does an HTTP GET on the given url and returns the result as a string.

Parameters: Url (string) – URL to GET from.
Returns: A string wrapped in a promise.

(web.fetch-text* Urls)

Does concurrent HTTP GETs on the given URLs and returns the results as a list of strings.

Parameters: Urls (list) – A Shen list of URLs to GET from.
Returns: A Shen list of strings wrapped in a promise.

(web.navigator): Returns the global navigator.

(web.self): Returns the value of the self keyword.

(web.window): Returns the global window.

DOM-specific Interop¶

Functions for building elements and interacting with the DOM.

(dom.append Parent Child)

Adds Child as the last child node of Parent.

Parameters

Parent (node) – DOM Node to append Child to.
Child (node) – DOM Node to append to Parent.

Returns

Empty list.

(dom.build Tree)

Builds a DOM Node out of a Shen list tree. Each node in the tree is represented by a list starting with a key symbol. That symbol is the name of the HTML element to be built (e.g. div, span), with a couple of exceptions:

If the key symbol starts with a @ or !, it is interpreted as an attribute (e.g. @id, @class) or an event listener (e.g. !click, !mouseover), respectively. The 2nd element in that list should be the attribute value or the event handler function. An event handler function should take a single argument, the event object.

String children get built into text nodes.

Child elements, text nodes, attributes and event handlers are all appended or set on enclosing parents in respective order.

[div [@id "example"]
     [p "Click Me!"
        [!click (/. _ (js.log "hi!"))]]]

gets built to:

<div id="example">
  <p onclick="console.log('hi!')">Click Me!</p>
</div>

Parameters: Tree (any) – Tree of Shen lists.
Returns: DOM Node built from Tree.

(dom.onready F)

Calls the function F when the DOM is loaded and ready. Callback takes zero arguments (is a freeze). Value returned by callback is ignored.

Parameters: F (function) – Function that performs operations requiring the DOM.
Returns: Empty list.

(dom.prepend Parent Child)

Adds Child as the first child node of Parent.

Parameters

Parent (node) – DOM Node to prepend Child to.
Child (node) – DOM Node to prepend to Parent.

Returns

Empty list.

(dom.query Selector)

Finds an element matching the given CSS selector in the document.

Parameters: Selector (string) – CSS selector to match with.
Returns: Returns matching node or empty list if not found.

(dom.query* Selector)

Finds all elements matching the given CSS selector in the document.

Parameters: Selector (string) – CSS selector to match with.
Returns: A Shen list of matching elements.

(dom.remove Node)

Removes Node from its parent. Does nothing if Node has no parent.

Parameters: Node (node) – DOM Node to remove.
Returns: Empty list.

(dom.replace Target Child)

Removes Target from its parent and appends Child in its place. Does nothing if Target has no parent.

Parameters

Target (node) – DOM Node to replace with Child.
Child (node) – DOM Node to replace Target with.

Returns

Empty list.

Local Storage Functions¶

Functions for getting and setting keys in Local Storage.

(local-storage.clear)

Removes all entries for the current domain.

Returns: Empty list.

(local-storage.get Key)

Gets value for given string key. Can check local-storage.has? first to make sure value exists.

Parameters: Key (string) – Key to fetch value for.
Returns: Value for key, or empty list if it does not exist.

(local-storage.has? Key)

Returns true if value is set for given key.

Parameters: Key (string) – Key to check.
Returns: A Shen boolean.

(local-storage.remove Key)

Deletes value for given key.

Parameters: Key (string) – Key to delete.
Returns: Empty list.

(local-storage.set Key Value)

Sets value for given key.

Parameters

Key (string) – Key to save value under.
Value (any) – Value to assign.

Returns

The assigned value.

Node-specific Interop¶

Only available when running in a Node environment.

(node.exit Code)

Takes an exit code and terminates the runtime with the process returning that exit code.

Parameters: Code (number) – Exit code for the process to return.
Returns: Doesn’t.

node.exit-macro: Macro to convert node.exit called with no arguments by inserting 0 as the default exit code.

(node.global): Called with no arguments, returns the value of the Node global object.

(node.require Id)

Calls Node’s require function with the given module identifier.

Parameters: Id (string) – Name or path to a Node module.
Returns: exports object returned by the module.