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 givenhead
andtail
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 fromf
gets post-processed withtoListTree
. Iff
returnsundefined
, 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
andy
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 intof
. Whateverf
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 intof
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 symbolpackage.*thing*
, sets it to0
and declares functionpackage.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 ofnull
. Ignored ifx
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 to3
withjs.raw.eval
where it would fail withjs.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 returnundefined
.- 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
orjs.repeat
.- Parameters
Timeout (js.timeout) – A timeout handle returned by
js.delay
orjs.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 withX is not defined
where withjs.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 withsetTimeout
.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. IfglobalThis
is not defined in this JavaScript environment, thenwindow
,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
orfalse
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 ofParent
.- 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 afreeze
). 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 ofParent
.- 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 ifNode
has no parent.- Parameters
Node (node) – DOM Node to remove.
- Returns
Empty list.
- (dom.replace Target Child)
Removes
Target
from its parent and appendsChild
in its place. Does nothing ifTarget
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 inserting0
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.