Repository files navigation

Ralph is a Lisp-1 dialect that compiles to JavaScript. It is heavily inspiredby an early version of Dylan (also known as "Prefix Dylan"), as described inDylan – An object-oriented dynamic language.

First, installNode.js and then all necessary modules:

• $ npm install

The directorycore already contains the full Ralph runtime and compileras pre-compiled JavaScript, so you are ready to go.

To start a local, Node.js-based REPL, run:

• $ NODE_PATH=core node repl.js

To start a remote, browser-based REPL, installbrowserify,generate the browser evaluator, start the REPL with the--remote option,and openindex.html in your browser:

• $ NODE_PATH=~/node_modules:core browserify evaluator.js -o evaluator.out.js
• $ NODE_PATH=core node repl.js --remote

To compile a simple "Hello, world!" program:

• Placehello.ralph intosrc:

  (define-module hello  import: (ralph/format-out)  export: (hello))    (define-function hello (name)  (format-out "Hello, %s!" name))

• Compile thehello module. The compiler outputs files intobuild.

  $ NODE_PATH=core node -e "require('ralph/compiler')['compile-module']('hello')"

• Run the program by opening thehello module and calling thehello function:

  $ NODE_PATH=build node -e "require('hello')['hello']('World')"Hello, World!

There is unfortunately no API documentation. The moduleralph/corecontains the core runtime and the standard library.

Themanual of Prefix Dylancan be used as a reference and is a good introduction into the language.

There are alsoslides from a talkgiven atILC 2012,and apaperexplaining the motivation, features and compilation strategy of Ralph.

For performance reasons, Ralph is using JavaScript arrays as its core data structure,instead of implementing its own list data structure based on objects. Arrays can becreated using the[] syntax (e.g.(first [1 2 3])).

The syntax for numbers and strings is that of JavaScript.

Symbols may contain any character which is not otherwise syntactically significant(e.g., introduces a number, an array, etc). The character sequence:: in symbolsis treated as the separator for fully-qualified symbols: The first part isthe module name, the second is the symbol name.

Keywords have the same syntax as symbols and end with a colon (e.g.,foo:).

The syntax for the canonical true value is#t, for the canonical false value#f.

In parameter lists,#rest is used to introduce the name of the variable containingthe additional arguments, and#key is used to introduce keyword parameters.

A single quote is used for quoting. A backquote is used for syntax-quoting (seemacros).

A semicolon indicates the start of a comment.

The special operator%native allows writing inline JavaScript. All strings that arepassed to it are directly emitted as-is. Numbers are first converted to strings, andsymbols are properly renamed. Other forms are not supported.

For example, the following Ralph code

(bind ((delta 3))  (%native "x += " delta " * " 2))

would compile to the following JavaScript code:

var delta__1 = 3;x += delta__1 * 2;

Ralph's compiler knows nothing about the globalx and there is no need todeclare it exists.

The utility macro. can be used for easily writing JavaScript method calls.For example,

(. (%native "console")    (log "Hello, %s" "World"))

would compile to:

console.log("Hello, %s!", "World");

Ralph also integrates well with Node.js. To be able to use a Node.js modulein Ralph, place a.rm file (ralph module definition) insrc that specifiesthe name, it is native (native?: #t) and the definitions it is exporting.

For example, a basic definition for the Node.js modulevm could look like:

("vm" native?: #t exports: ("createContext" "runInContext"))

Seefs andralph/file-systemfor a an extended example of this mechanism.

Ralph supports hygienic macros through Clojure-like syntax-quoting.

In a separate module, define the macro usingdefine-macro. In the module youwant to use it, import the module during compilation using thecompile-time-import:option in thedefine-module definition.

For a full example, seeralph/macro-test.a, whichcan be compiled using.

$ NODE_PATH=core:build node -e "require('ralph/compiler')['compile-module']('ralph/macro-test.a')"

The section "Macro system" in thepaper contains more details.

The compiler can be recompiled and all tests can be run using:

• $ ./scripts/test-self.sh

Ralph isnot actively maintained.

If you have questions, are interested in using it, or even would like to continue its development, just open a new issue!