Accessing ShenScript Internals from JavaScript¶
Note
Some of these functions and classes are exported, but they are primarily referred to internally. They are exported so generated JavaScript code will have access to them. Or, in rare cases, they are exported in case your Shen code needs to work around something.
Data¶
Warning
These objects are not meant to be tampered with by user or client code. Tinker with them if you must, but it will void the warranty.
- globals¶
A
Map
ofCell
objects, indexed by string name. Used to hold references to both global functions and global symbol values. If a function and a global symbol have the same name, they will be referred to by the same entry in this map.
Classes¶
- class Cell(name)¶
Contains mutable pointers to the function and/or the global symbol value by the given name. Should only be created by the
lookup
function.- Parameters
name (string) – The name of the global.
- class Cons(head, tail)¶
The classic Lisp cons cell.
head
andtail
are akin tocar
andcdr
.When a chain of
Cons
is used to build a list, the lastCons
in the chain has atail
ofnull
.- Parameters
head (any) – Named
head
because it’s typically the head of a list.tail (any) – Named
tail
because it’s typically the tail of a list.
- class Context(options)¶
Context
objects are passed between calls to thebuild
function to track syntax context and rendering options.- Parameters
options (object) – Collection of code generation options.
options.async (boolean) –
true
if code should be generated in async mode.options.head (boolean) –
true
if current expression is in head position.options.locals (Map) – Used as an immutable map of local variables and their known types.
options.inlines (object) – Map containing code inlining rules.
- class Fabrication(ast, subs)¶
Returned by the
build
function, containing the resulting AST and a substitution map of hoisted references.- Parameters
ast (ast) – The AST result of building a KL expression.
subs (object) – Has string keys and AST values.
- class Trampoline(f, args)¶
A
Trampoline
represents a deferred tail call.- Parameters
f (function) – A JavaScript function.
args (array) – A JavaScript array of arguments that
f
will get applied to.
Functions¶
- as___(x)¶
There are several functions following this naming pattern which first check if their argument passes the related
is___
function and returns it if it does. If it does not pass the type check, an error is raised.- Parameters
x (any) – Whatever.
- Returns
The same value.
- Throws
If argument does not pass the type check.
- assemble(f, ...xs)¶
Composes a series of fabrications into a single fabrication.
- Parameters
f (function) – A function that combines a sequence of ASTs into an AST (or fabrication).
xs (array) – A sequence of fabrications/ASTs.
- Returns
The composed fabrication.
- bounce(f, args)¶
Creates a
Trampoline
.Aliased as
b
for brevity in generated code.- Parameters
f (function) – A JavaScript function.
args – A variadic parameter containing any values.
- Returns
A
Trampoline
.
- compile(expr)¶
Builds a KLambda expression tree in the root context.
- Parameters
expr (expr) – Expression to build.
- Returns
Rendered JavaScript AST.
- construct(expr)¶
Like
compile
, but returns a fabrication, not an AST.- Parameters
expr (expr) – Expression to build.
- Returns
Rendered fabrication.
- lookup(name)¶
Retrieves the
Cell
for the given name, creating it and adding it toglobals
if it did not already exist.Aliased as
c
for brevity in generated code.- Parameters
name (string) – Name of a global function or symbol.
- Returns
A
Cell
for that name.
- fun(f)¶
Takes a function that takes a precise number of arguments and returns a wrapper that automatically applies partial and curried application.
Aliased as
l
for brevity in generated code.- Parameters
f (function) – Function wrap with partial application logic.
- Returns
Wrapper function.
- is___(x)¶
There are several functions following this naming pattern which checks if the argument qualifies as the type it’s named for.
- Parameters
x (any) – Whatever.
- Returns
A JavaScript boolean.
- nameOf(symbol)¶
Returns string name of given symbol. Symbol does not have to have been declared.
- Parameters
symbol (symbol) – A symbol.
- Returns
Symbol name.
- raise(message)¶
Throws an Error with the given message.
- Parameters
message (string) – Error message.
- Returns
Doesn’t.
- Throws
Error with the given message.
- settle(x)¶
If given a trampoline, runs trampoline and checks if result is a trampoline, in which case that is then run. Process repeats until result is not a trampoline. Never returns a trampoline. Potentially any function in
functions
will need to be settled after being called to get a useful value.Handles async trampolines by branching off to unexported
future
function when encountering a promise.future
will automatically thread trampoline settling through promise chains.Aliased as
t
for brevity in generated code.- Parameters
x (any) – May be a
Trampoline
(or aPromise
), which will be run, or any other value, which will be returned immediately.- Returns
Final non-trampoline result.
- symbolOf(name)¶
Returns the interned symbol by the given name.
Aliased as
s
for brevity in generated code.- Parameters
name (string) – Symbol name.
- Returns
Symbol by that name.
Accessing ShenScript Internals from Shen¶
Functions in the shen-script
namespace are for directly accessing ShenScript internals.
Functions¶
These functions are callable from Shen to give access to the implementation details of ShenScript.
- (shen-script.$)
Provides access to the ShenScript environment object, which when combined with
js
interop functions, allows arbitrary manipulation of the port’s implementation details from Shen.- Returns
ShenScript environment object.
- (shen-script.ast)
Returns a JavaScript object with all the JavaScript AST constructor functions.
- Returns
The
exports
of theast
module.
- (shen-script.lookup-function Name)
Allows lookup of global function by name instead of building wrapper lambdas or the like.
- Parameters
Name (symbol) – Name of function to lookup.
- Returns
Shen function by that name, or
[]
when function does not exist.
- (shen-script.boolean.js->shen X)
Converts a JavaScript boolean to a Shen boolean. Any truthy value counts as JavaScript
true
and any falsy value counts as JavaScriptfalse
.- Parameters
X (any) – Accepts any value as an argument.
- Returns
A Shen boolean.
- (shen-script.boolean.shen->js X)
Converts a Shen boolean to a JavaScript boolean.
- Parameters
X (boolean) – A Shen boolean.
- Returns
A JavaScript boolean.
- Throws
Error if argument is not a Shen boolean.
- (shen-script.array->list X)
Converts a JavaScript array to a cons list.
- Parameters
X (array) – A JavaScript array.
- Returns
A Shen list.
- (shen-script.array->list+ X Tail)
Converts a JavaScript array to a cons list with a specified value for the tail of the last cons.
- Parameters
X (array) – A JavaScript array.
Tail (any) – Specific final tail value.
- Returns
A Shen list.
- (shen-script.array->list-tree X)
Converts a tree of nested JavaScript arrays to a tree of nested cons lists.
- Parameters
X (array) – A JavaScript array with elements that may be arrays.
- Returns
A Shen list with elements that will be lists.
- (shen-script.list->array X)
Converts cons list to JavaScript array.
- Parameters
X (array) – A Shen list.
- Returns
A JavaScript array.
- (shen-script.list->array-tree X)
Converts tree of nested cons lists to tree of nested JavaScript arrays.
- Parameters
X (array) – A Shen list with elements that may be lists.
- Returns
A JavaScript array with elements that will be arrays.
AST Construction Functions¶
Functions in the js.ast namespace are used to construct, emit and evaluate arbitrary JavaScript code. All of the AST builder functions return JavaScript objects conforming to the informal ESTree standard ESTree.
- (js.ast.arguments)
Constructs a reference to the
arguments
object.- Returns
An
Identifier
AST node.
- (js.ast.array Values)
Constructs array literal syntax.
Example:
[x, y, z]
.- Parameters
Values (list) – A Shen list of value AST’s to initialise a JavaScript array with.
- Returns
An
ArrayExpression
AST node.
- (js.ast.arrow Parameters Body)
Constructs a lambda expression.
Example:
x => …
- Parameters
Parameters (list) – A Shen list of parameter identifiers.
Body (ast) – A body expression.
- Returns
A
ArrowFunctionExpression
AST Node.
- (js.ast.assign Target Value)
Constructs an assignment expression.
Example
x = y
- Parameters
Target (ast) – The variable to assign to.
Value (ast) – The value to assign.
- Returns
An
AssignmentExpression
AST Node.
- (js.ast.async Ast)
Makes function or class member async.
Examples:
async (x, y) => …
,async function(x, y) { … }
,async method(x, y) { … }
- Parameters
Ast (ast) – Ast to make async.
- Returns
The same AST after setting the
async
property totrue
.
- (js.ast.await Argument)
Constructs an await expression for use in an async function.
Example:
await x
- Parameters
Argument (ast) – Expression to await.
- Returns
An
AwaitExpression
AST Node.
- (js.ast.binary Operator Left Right)
Constructs a binary operator application.
Examples:
x && y
,x + y
- Parameters
Operator (string) – Name of operator to apply.
Left (ast) – Expression on the left side.
Right (ast) – Expression on the right side.
- Returns
A
BinaryExpression
AST Node.
- (js.ast.block Statements)
Constructs a block that groups statements into a single statement and provides isolated scope for
const
andlet
bindings.Example:
{ x; y; z; }
- Parameters
Statements (list) – A Shen list of statement AST’s.
- Returns
A
BlockStatement
AST Node.
- (js.ast.call Function Args)
Constructs a function call expression.
Example:
f(x, y)
- Parameters
Function (ast) – An expression AST that evaluates to a function.
Args (list) – A Shen list of argument AST’s.
- Returns
A
CallExpression
AST Node.
- (js.ast.catch Parameter Body)
Constructs a catch clause.
Example:
catch (e) { … }
- Parameters
Parameter (ast) – An identifer for the error that was caught.
Body (ast) – A block of statements that get run when the preceeding try has failed.
- Returns
A
CatchClause
AST Node.
- (js.ast.class Name SuperClass Slots)
Constructs ES6 class syntax. Members are constructed using
js.ast.constructor
,js.ast.method
,js.ast.getter
,js.ast.setter
or the more general functionjs.ast.slot
.Example:
class Class extends SuperClass { constructor(...) { ... } method(...) { ... } }
- Parameters
Name (ast) – Identifier naming the class.
SuperClass (ast) – Identifier node of super class, can be undefined or null.
Slots (list) – A Shen list of slot AST’s.
- Returns
A
ClassExpression
AST Node.
- (js.ast.const Id Value)
Constructs
const
variable declaration.- Parameters
Id (ast) – Variable name.
Value (ast) – Value to initialise variable with.
- Returns
A
VariableDeclaration
AST node.
- (js.ast.constructor Body)
Specialisation of
js.ast.slot
for class constructors.Example:
constructor(…) { … }
- (js.ast.debugger)
Constructs a
debugger;
statement.- Returns
A
DebuggerStatement
AST node.
- (js.ast.do-while Test Body)
Constructs a do-while loop.
Example:
do { … } while (condition);
- Parameters
Test (ast) – Conditional expression that determines if the loop will run again.
Body (ast) – Block of statements to run each time the loop repeats or the first time.
- Returns
A
DoWhileStatement
AST Node.
- (js.ast.empty)
Constructs an empty statement.
Example:
;
- Returns
An
EmptyStatement
AST Node.
- (js.ast.for Init Test Update Body)
Constructs a for loop.
Example:
for (let x = 0; x < i; ++x) { … }
- Parameters
Init (ast) – Declarations and initial statements. This can be a sequence expression.
Test (ast) – Conditional expression that determines if the loop will run again or for the first time.
Update (ast) – Update expressions to evaluate at the end of each iteration. This can be a sequence expression.
Body (ast) – Block of statements to run each time the loop repeats.
- Returns
A
ForStatement
AST Node.
- (js.ast.for-await-of Left Right Body)
Constructs an asynchronous for-of loop. Each value iterated from
Right
gets awaited before being bound to the variable or pattern declared inLeft
.Example:
for await (let x of xs) { … }
- Parameters
Left (ast) – Declaration of local variable that each value from the iterable on the right side gets assigned to.
Right (ast) – Expression that evaluates to an iterable value.
Body (ast) – Block of statements to run each time the loop repeats.
- Returns
A
ForOfStatement
AST Node.
- (js.ast.for-in Left Right Body)
Constructs a for-in loop.
Example:
for (let x in xs) { … }
- Parameters
Left (ast) – Declaration of local variable that each key from the object on the right side gets assigned to.
Right (ast) – Expression that evaluates to some object.
Body (ast) – Block of statements to run each time the loop repeats.
- Returns
A
ForInStatement
AST Node.
- (js.ast.for-of Left Right Body)
Constructs a for-of loop.
Example:
for (let x of xs) { … }
- Parameters
Left (ast) – Declaration of local variable that each value from the iterable on the right side gets assigned to.
Right (ast) – Expression that evaluates to an iterable value.
Body (ast) – Block of statements to run each time the loop repeats.
- Returns
A
ForOfStatement
AST Node.
- (js.ast.function Name Parameters Body)
Constructs a function expression.
Example:
function name(x, y) { … }
- Parameters
Name (ast) – Optional identifier naming the function.
Parameters (list) – A Shen list of parameter expression.
Body (ast) – A block of statements that make of the body of the function.
- Returns
A
FunctionExpression
AST Node.
- (js.ast.function* Name Parameters Body)
Constructs a generator function expression.
Example:
function* name(x, y) { … }
- Parameters
Name (ast) – Optional identifier naming the function.
Parameters (list) – A Shen list of parameter expression.
Body (ast) – A block of statements that make of the body of the function.
- Returns
A
FunctionExpression
AST Node.
- (js.ast.getter Name Body)
Specialisation of
js.ast.slot
for class getters.Example:
get thing(…) { … }
- (js.ast.id Name)
Constructs an identifier - the name of a function or variable. Identifier is named exactly as the given argument.
Example:
x
- Parameters
Name (string) – Name of identifier.
- Returns
An
Identifier
AST node.
- (js.ast.if Condition Consequent Alternate)
Constructs an if statement with optional else clause.
Examples:
if (condition) { ... } else { ... }
if (condition) { ... }
- Parameters
Condition (ast) – Conditional expression that determines which clause to step into.
Consequent (ast) – The then clause.
Alternate (ast) – Optional else clause.
- Returns
An
IfStatement
AST Node.
- (js.ast.let Id Value)
Constructs
let
variable declaration.- Parameters
Id (ast) – Variable name.
Value (ast) – Value to initialise variable with.
- Returns
A
VariableDeclaration
AST node.
- (js.ast.literal Value)
Constructs literal value syntax.
- Parameters
Value – JavaScript value that can be a literal (number, string, boolean, null).
- Returns
A
Literal
AST node.
- (js.ast.member Object Member)
Constructs a member access expression with the dot operator.
Examples:
x.y
,x[y]
- Parameters
Object (ast) – Expression AST to access member of.
Member (ast) – Expression that computes member name to access. If non-string, will automatically be wrapped in square brackets.
- Returns
A
MemberExpression
AST Node.
- (js.ast.method Name Body)
Specialisation of
js.ast.slot
for class methods.Example:
method(…) { … }
- (js.ast.new-target)
Constructs a reference to the
new.target
meta-property.- Returns
A
MetaProperty
AST node.
- (js.ast.object Properties)
Constructs object literal syntax.
Example:
{ a: b, c: d }
- Parameters
Properties (list) – A flat Shen list of property names and values.
- Returns
An
ObjectExpression
AST Node.
- (js.ast.return Argument)
Constructs a return statement.
Example:
return x;
- Parameters
Argument (ast) – Expression to return.
- Returns
A
ReturnStatement
AST Node.
- (js.ast.safe-id Name)
Constructs an identifier where the name is escaped to make it valid in JavaScript and to not collide with reserved names in ShenScript.
- Parameters
Name (string) – Name of identifier.
- Returns
An
Identifier
AST node.
- (js.ast.setter Name Body)
Specialisation of
js.ast.slot
for class setters.Example:
set thing(…) { … }
- (js.ast.sequence Expressions)
Constructs a compound expression using the comma operator.
Example:
(x, y, z)
- Parameters
Expressions (list) – A Shen list of expression AST’s.
- Returns
A
SequenceExpresssion
AST Node.
- (js.ast.slot Kind Name Body)
Constructs a class property of the given kind.
- Parameters
Kind (string) – “constructor”, “method”, “get” or “set”.
Name (ast) – Identifier naming the property.
Body (ast) – Expression representing the function or value assigned to the property.
- Returns
A
MethodDefinition
AST Node.
- (js.ast.statement Expression)
Constructs a wrapper that allows an expression to be a statement.
- Parameters
Expression (ast) – The expression in question.
- Returns
An
ExpressionStatement
AST Node.
- (js.ast.static Ast)
Makes class member static.
Example:
static method(x, y) { … }
- Parameters
Ast (ast) – Ast to make static.
- Returns
The same AST after setting the
static
property totrue
.
- (js.ast.spread Argument)
Constructs spread operator/pattern syntax.
Example:
…x
- Parameters
Argument (ast) – Identifier or pattern that are gathered or spread.
- Returns
A
SpreadElement
AST Node.
- (js.ast.super Arguments)
Constructs a call to the super (prototype) constructor.
Example:
super(x, y);
- Parameters
Arguments (list) – A Shen list of argument AST’s.
- Returns
A
Super
AST Node.
- (js.ast.ternary Condition Consequent Alternate)
Constructs an application of the ternary operator.
Example
x ? y : z
- Parameters
Condition (ast) – True/false expression on the left of the
?
.Consequent (ast) – Expression that gets evaluated if the condition is true.
Alternate (ast) – Expression that gets evaluated if the condition is false.
- Returns
A
ConditionalExpression
AST Node.
- (js.ast.this)
Constructs a reference to the
this
keyword.- Returns
A
ThisExpression
AST node.
- (js.ast.try Body Handler)
Constructs a try statement.
Example:
try { ... } catch (e) { ... }
- Parameters
Body (ast) – A block of statements that get tried.
Handler (ast) – A catch clause as constructed by
js.ast.catch
.
- Returns
A
TryStatement
AST Node.
- (js.ast.unary Operator Argument)
Construts a unary operator application.
Examples:
!x
,-x
- Parameters
Operator (string) – Name of operator to apply.
Argument (ast) – Argument to apply operator to.
- Returns
A
UnaryExpression
AST Node.
- (js.ast.update Operator Target Value)
Constructs an assignment expression with a specific operator.
Examples
x += y
,x *= y
- Parameters
Operator (string) – The update operator without the
=
, so+
,-
, etc.Target (ast) – The variable to assign to.
Value (ast) – The value to assign.
- Returns
An
AssignmentExpression
AST Node.
- (js.ast.var Id Value)
Constructs
var
variable declaration.- Parameters
Id (ast) – Variable name.
Value (ast) – Value to initialise variable with.
- Returns
A
VariableDeclaration
AST node.
- (js.ast.while Test Body)
Constructs a while loop.
Example:
while (condition) { … }
- Parameters
Test (ast) – Conditional expression that determines if the loop will run again or for the first time.
Body (ast) – Block of statements to run each time the loop repeats.
- Returns
A
WhileStatement
AST Node.
- (js.ast.yield Argument)
Constructs a yield expression for use in a generator function.
Example:
yield x
- Parameters
Argument (ast) – Expression to yield.
- Returns
A
YieldExpression
AST Node.
- (js.ast.yield* Argument)
Constructs a yield delegate expression for use in a generator function.
Example:
yield* x
- Parameters
Argument (ast) – Iterable or generator expression to yield.
- Returns
A
YieldExpression
AST Node.
AST Evaluation Functions¶
- (js.ast.compile Expr)
Builds a JavaScript AST from given KLambda expression. Any hoisted references will be enclosed per the backend
hoist
function.- Parameters
Ast (expr) – KLambda expression.
- Returns
JavaScript AST.
- (js.ast.eval Ast)
Takes a JavaScript AST as built by the
js.ast
functions, renders it to JavaScript and evaluates it in the current environment.- Parameters
Ast (ast) – JavaScript AST.
- Returns
Whatever the code the AST represents evaluates to.
- (js.ast.render Ast)
Renders the string source code representation of a JavaScript AST.
- Parameters
Ast (ast) – Code to be rendered.
- Returns
String representation of that
Ast
.