Building an Environment

module shen

This is the top-level module. The exports of this module is a function that constructs a full populated ShenScript environment object.

(options) => $
Parameters

options (object) – Can have all of the same properties as the options object accepted by the backend function.

Returns

A complete ShenScript environment.

The default configuration options for this environment are specified in the config module and environment-derived properties are in the config.node and config.web modules. Any of these can be overwritten by specifying them in the options to the shen function.

The Kernel Sandwich

A full ShenScript environment is created by initialising a new backend with the options passed into the top-level, running that through the pre-rendered kernel and then applying the frontend decorator for whichever node or web environment is specified in the options. The composition looks like frontend(kernel(backend(options))). I call this “The Kernel Sandwich”.

The Backend

module backend

The backend module contains the KLambda-to-JavaScript transpiler, global function and symbol indexes and proto-primitives for conses, trampolines, equality and partial application.

The exports of this module is just a function that constructs a new ShenScript environment object, which is conventionally named $.

(options = {}) => $
Parameters

  • options (Object) – Environment config and overrides.

  • options.clock (function) – Provides current time in fractional seconds from the Unix epoch. Defaults to () => Date.now.

  • options.homeDirectory (string) – Initial working directory in file system. Defaults to "/".

  • options.implementation (string) – Name of JavaScript platform in use. Defaults to "Unknown".

  • options.InStream (class) – Class used for input streams. Not required if isInStream and openRead are specified.

  • options.OutStream (class) – Class used for output streams. Not required if isInStream and openRead are specified.

  • options.isInStream (function) – Returns true if argument is an InStream. Defaults to a function that returns false.

  • options.isOutStream (function) – Returns true if argument is an OutStream. Defaults to a function that returns false.

  • options.openRead (function) – Opens an InStream for the given file path. Defaults to a function that raises an error.

  • options.openWrite (function) – Opens an OutStream for the given file path. Defaults to a function that raises an error.

  • options.os (string) – Name of operating system in use. Defaults to "Unknown".

  • options.port (string) – Current version of ShenScript. Defaults to "Unknown".

  • options.porters (string) – Author(s) of ShenScript. Defaults to "Unknown".

  • options.release (string) – Current version of JavaScript platform in use. Defaults to "Unknown".

  • options.sterror (string) – OutStream for error messages. Defaults to stdoutput.

  • options.stinput (string) – InStream for standard input. Defaults to an object that raises an error.

  • options.stoutput (string) – OutStream for standard output. Defaults to an object that raises an error.

Returns

An object conforming to the Backend class description.

class Backend

This class is a description of object returned by the backend function and does not actually exist. It contains an initial ShenScript environment, without the Shen kernel loaded.

Parameters

  • assemble (function) – Composes a sequence of JavaScript ASTs and Fabrications into a single Fabrication.

  • assign (function) – Initialize or set a global symbol.

  • bounce (function) – Creates a trampoline from function and rest arguments.

  • compile (function) – Turns KLambda expression array tree into JavaScript AST.

  • construct (function) – Turns KLambda expression array tree into Fabrication.

  • cons (function) – Creates a Cons from a head and tail.

  • defun (function) – Adds function to the global function registry.

  • equate (function) – Determines if two values are equal according to the semantics of Shen.

  • evalJs (function) – Evalutes a JavaScript AST in isolated scope with access to $.

  • evalKl (function) – Builds and evaluates a KLambda expression tree in isolated scope with access to $.

  • globals (Map) – Map of symbol names to lookup Cells.

  • inline (function) – Registers an inlining rule.

  • lookup (function) – Looks up Cell in globals, adding one if it doesn’t exist yet.

  • settle (function) – If value is a Trampoline, runs Trampoline and repeats.

  • show (function) – toString function. Returns string representation of any value.

  • valueOf (function) – Returns the value of the given global symbol. Raises an error if it is not defined.

The Kernel

module kernel

The kernel module contains a JavaScript rendering of the Shen kernel that can be installed into a ShenScript environment.

The exports of this module is just a function that augments an environment and returns it.

($) => $
Parameters

$ (object) – A ShenScript environment to add functions to.

Returns

Same $ that was passed in, conforming to the Kernel class.

Kernel extends Backend

This class is a description of object returned by the kernel module and does not actually exist. It contains a primitive ShenScript environment along with the Shen kernel and it adequate to run standard Shen programs.

The Kernel virtual class adds no members, but does imply additional entries in the globals map.

The Frontend

module frontend

The frontend module augments a ShenScript environment with JavaScript- and ShenScript-specific functionality.

Functionality provided includes:

  • js package functions that allow access to common JavaScript types, objects and functions.

  • js.ast package functions that allow generation, rendering and evaluation of JavaScript code.

  • shen-script package functions that allow access to ShenScript environment internals.

The exports of this module is just a function that augments an environment and returns it.

($) => $
Parameters

$ (object) – A ShenScript environment to add functions to.

Returns

Same $ that was passed in, conforming to the Frontend class.

Frontend extends Kernel

This class is a description of object returned by the frontend function and does not actually exist. It contains a complete ShenScript environment.

Parameters

  • caller (function) – Returns a function that invokes the function by the given name, settling returned Trampolines.

  • define (function) – Defines Shen function that defers to given JavaScript function.

  • defineTyped (function) – Defines Shen function that defers to given JavaScript function and declares with the specified Shen type signature.

  • defmacro (function) – Defines a Shen macro in terms of the given JavaScript function.

  • evalShen (function) – Evaluates Shen expression tree in isolated environment.

  • exec (function) – Parses string as Shen source, evaluates each expression and returns last result.

  • execEach (function) – Parses string as Shen source, evaluates each expression and returns an array of the results.

  • load (function) – Loads Shen code from the given file path.

  • parse (function) – Returns parsed Shen source code as a cons tree.

  • pre (function) – Registers a preprocessor function.

  • symbol (function) – Declares a global symbol with the given value and a function by the same name that retrieves the value.

Returns

Same $ that was passed in.

The Node Frontend

module frontend.node

Further adds node package helpers for interacting with the capabilites of the Node.js runtime.

Functions are described here.

The Web Frontend

module frontend.web

Further adds web package helpers for interacting with the capabilites of a web browser or electron instance.

Functions are described here.