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 of Cell 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 and tail are akin to car and cdr.

When a chain of Cons is used to build a list, the last Cons in the chain has a tail of null.

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 the build 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 to globals 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 a Promise), 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 the ast 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 JavaScript false.

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 to true.

(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 and let 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 function js.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 in Left.

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 to true.

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