closer

Closer.js
=========


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

- Special forms
- def
- if
- do
- let
- fn
- loop / recur
- Persistent data structures (courtesy mori)
- JavaScript interop
- Destructuring forms
- Anonymous function literals
- More than 100 functions from clojure.core
- Many of the core functions can work with lazy sequences, like range, map, filter, iterate, take and repeat
- In loose mode, the parser can handle common syntax errors (missing / excess parentheses at the end, etc.) and will always return a valid AST, even if empty, similar to Acorn's loose mode

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:
``js
// 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:
`js
// 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
------------

- Vicky Chijwani
- Closer exists thanks to the following projects:
- CodeCombat and Aether (the _raisons d'être_ for this project)
- Jison
- Mori
- Lodash
- Jasmine
- Reflect.js (for helping me get started)
- Browserify
- @Constellation's escodegen and estraverse
- Grunt