Skip to content

Latest commit

 

History

History
145 lines (101 loc) · 9.31 KB

README.md

File metadata and controls

145 lines (101 loc) · 9.31 KB
Raw

Closer.js

Build Status NPM version Dependency Status devDependency Status

Closer.js is a parser for the Clojure programming language written in JavaScript, compatible with the Mozilla Parser API. It also provides much of the Clojure core library as a separate module (thanks in large part to swannodette/mori). All of this is heavily tested, with > 90% code coverage (the untested 10% is mostly unused code from the Jison parser generator).

It was created to be used on CodeCombat, a site that teaches users how to code by playing a game (there's multiplayer too!). CodeCombat is open-source, backed by YCombinator, participating in Google Summer of Code 2014, and is generally awesome all around. Go check it out!

This project could be useful for a variety of things like browser-based Clojure code editing, linting, syntax highlighting, auto-completion, and running sandboxed Clojure code in a browser.

Key Features

defmacro is not supported at the moment, as I haven't quite figured it out yet. Ideas and pull requests on how to go about it are always welcome!

Installation & Usage

Get it via NPM: npm install closer.

Closer works on Node.js and all modern browsers (via browserify). It has been tested on Node 0.10.24, Chromium 34, and Firefox 28.

closer.parse(src, options={})

  • src is a String containing the input Clojure code

  • options can contain the following:

    • loc (default true): if true, AST nodes will have line and column-based location information attached to them

    • range (default false): if true, AST nodes will have range-based location information attached to them, similar to Esprima

    • loose (default false): if true, Closer will try to handle common syntax errors and will always return a valid AST, even if empty, similar to Acorn's loose mode

    • coreIdentifier (default 'closerCore'): if the core library is being used, it must be in scope at the point of execution with this name. The parser qualifies calls to core functions with this. For example:

    // parse
var closer = require('closer');
var ast = closer.parse('(+ 1 2)', { coreIdentifier: 'core' });
// execute
var core = closer.core; // the name of this variable must match coreIdentifier
var escodegen = require('escodegen');
eval(escodegen.generate(ast)); // === 3
// escodegen generates JS from AST (https://github.com/Constellation/escodegen)

    If being used in a browser, this parameter will usually not need to be used.

    • assertionsIdentifier (default 'closerAssertions'): if user-defined functions are to be executed, the assertions module must be in scope at the point of execution with this name. For example:
    // parse
var closer = require('closer');
var opts = { assertionsIdentifier: 'assertions' };
var ast1 = closer.parse('(#(do %) 42)', opts);
var ast2 = closer.parse('(#(do %) 42 57)', opts);
var ast3 = closer.parse('(#(+ % %2) 42 "str")', opts);
// execute
var assertions = closer.assertions; // the name of this variable must match assertionsIdentifier
var escodegen = require('escodegen');
eval(escodegen.generate(ast1)); // === 42
eval(escodegen.generate(ast2)); // ArityError: expected 1..1 args, got 2
eval(escodegen.generate(ast3)); // ArgTypeError: str is not a number

    If being used in a browser, this parameter will usually not need to be used.

closer.core

All implemented clojure.core functions are in this object. A list of what's available can be found here.

Ensure it is in scope (with the same name as that passed in the parser's coreIdentifier option) if you want to execute JS code generated from your AST using escodegen, for instance.

closer.assertions

This is a small module emulating Clojure's arity and type checks. You will never need to use this directly; only ensure it is in scope (with the same name as that passed in the parser's assertionsIdentifier option), if you want to execute JS code generated from your AST using escodegen, for instance.

Demo

Check out the demo page. Extensive examples of usage can be found in the core and functional tests.

Contributing

New contributors can look at issue #10 to dive in easily and quickly!

Closer's primary dependencies are the Jison parser generator and Mori. All new features and functions should have corresponding tests. Issues and pull requests are welcome. So are ideas, pointers, and code on how to implement defmacro in JavaScript.

Setup / workflow instructions:

  • Fork and clone this repository
  • Run these commands from project root:
    • npm install
    • sudo npm install -g grunt-cli jison
  • Run grunt test to make sure everything's working
  • Make your changes, running grunt test to test them
  • You can run ./repl to get a basic Clojure REPL: it will display the parser output and execute it as JavaScript
  • Once all tests pass, commit and push your changes, and send a pull request! Congratulations!

License

Licensed under the MIT License.

Contributors