Narcissus/Development

Terminology

Since JavaScript is both the language of the implementation and the language being implemented, it's helpful to distinguish the two levels conceptually:

• host ("host code," "host JS," etc): JS code in the implementation of Narcissus
• user ("user code," "user JS," etc): JS code being interpreted by Narcissus

Narcissus global object

Loading the Narcissus source files creates a global variable Narcissus.

Narcissus.options is an object which can be used to set some global configuration options for Narcissus. Currently there is just one configuration option:

Property	Options
version	185, "harmony"

Narcissus modules

Narcissus is divided into four "modules" (using the module pattern):

• Narcissus.definitions (jsdefs.js): basic definitions shared by the other modules
• Narcissus.lexer (jslex.js): lexer
• Narcissus.parser (jsparse.js): parser
• Narcissus.interpreter (jsexec.js): interpreter

The Narcissus.interpreter module is optional; that is, it's possible to load just the first three files to obtain a JavaScript parser written in portable JavaScript.

Host language versions

These are the host language versions required by each module/source file:

• jsdefs.js: ES3 + const + Object.defineProperty
• jslex.js: ES3 + const + Object.defineProperty
• jsparse.js: ES3 + const + Object.defineProperty
• jsexec.js: SpiderMonkey JS 1.9:
  • const (Harmony)
  • catch guards (replaceable with catch + if)
  • let declarations (Harmony)
  • Proxy (Harmony)
  • Object.defineProperty (ES5)
  • Object.getOwnPropertyDescriptor (ES5)
  • Object.getPrototypeOf (ES5)
  • Object.getOwnPropertyNames (ES5)
  • __proto__ = null (replaceable with Harmony maps)
  • __proto__ = obj (replaceable with Object.create)

The first three modules are web-portable. Only jsexec.js depends on SpiderMonkey extensions.

User language versions

The versions of JavaScript interpreted by Narcissus are under development. Currently, the interpreter works reasonably well on ES3 code, with support for a few SpiderMonkey extensions.

TODO: tighten this up as it stabilizes

Interpreter

Narcissus is a meta-circular JavaScript interpreter with a very direct representation of values: primitives are self-representing, objects are represented as objects (with their properties accessible via usual property access), and functions are represented as functions. The interpreter is designed this way to allow existing JavaScript functions and objects (such as the standard libraries) to interface directly with Narcissus code without following any special protocol or requiring wrapping and unwrapping.

Values

• all values are roughly self-representing
• function proxies

Control flow

• ExecutionContexts
• RETURN, THROW, BREAK, CONTINUE
• __call__
• function proxies