Making the ClojureScript language usable from nodejs
Command Line Tool Example
$ echo '(ns cljs.user (:require [clojure.string :as str])) (println (str/reverse "hello"))' > a.cljs$ runcljs a.cljsolleh
var cljs = ;var code ='(ns cljs.user'' (:require [clojure.string :as str]))''(println (str/reverse "hello"))';/* Evaluate ClojureScript programs */cljs; // prints olleh/* Compile ClojureSCript programs* prints:* goog.provide('cljs.user');* goog.require('cljs.core');* goog.require('clojure.string');* cljs.core.println.call(null,clojure.string.reverse.call(null,"hello"));*/processstdout;
This has somewhat limited functionality. You can evaluate expressions and define functions and variables, but you can't require additional namespaces.
I want to write a program in ClojureScript.
I want to break it up into multiple files, and include functions from the standard library.
I don't want to install java.
I don't want to bootstrap my own compiler.
I just want to write some ClojureScript. Is that too much to ask?
This package includes:
- the ClojureScript standard library
- a script (runcljs) for running cljs files
- a REPL
- the source files used to generate a thin wrapper around the compiler and supply it with a means of resolving required files
- a script for bootstrapping the compiler from the java-based ClojureScript compiler and generating a fresh standard library
- unit tests
All the functionality except for bootstrapping can be used without java installed.
Evaluates ClojureScript from a string. Returns the value of the last expression.
code the string to evaluate
libraryPaths an array of library paths can optionally be provided.
These should be paths to directories containing ClojureScript
files that will be searched when require statements are
encountered. For more information, see
Require Name Resolution.
isExpression a boolean determining whether to treat the string as
an expression or an entire program
filename filename displayed in error messages
Arguments have the same meaning as those of
Evaluates a ClojureScript program in a file. Returns the value of the last expression.
path path to the file to be evaluated
All other arguments are the same as those of
Arguments have the same meaning as those of
Require Name Resolution
Programs evaluated or compiled with this tool may import code from other files.
The above ClojureScript program requires code from 2 external files.
clojure.stringis part of the ClojureScript standard library
foo.bar.bazis a user-provided file containing (at least) a function called "my-fn"
foo.bar.baz are namespaces.
This tool implements a policy for converting namespaces like these into paths to files
which are loaded by the runtime. This policy is based on observing the directory structure
of the standard library and the namespaces used within it.
:require statements get compiled
into calls to
Google's Closure Library.
Short on documentation on exactly how namespaces are resolved into file paths, I resorted
to reverse engineering. This may be incorrect according to some spec. If someone knows about
such a spec, please contact me and I'll fix this tool!
This will explain how namespaces are convert to the path to a ClojureScript, Clojure, or JavaScirpt file.
- Start with a namespace (such as
foo.bar.baz). It must contain at least 2 parts (this is a requirement of the cloSure library).
- Replace periods with path files separators (e.g. "/") and convert to lowercase.
- Search the library paths for the files
EXTis one of
.js. The spec does specify that the extensions should be searched for in this order. Thus, the list of paths to search for is
- The process searches for these files relative to a number of library paths.
Library paths are supplied as arguments to the compilation/evaluation
runcljstool uses the directory of the file being evaluated as a library path. Additional library paths can be supplied to
-pargument. The last library path to be searched is the standard library. This tool has the location of the standard library baked into it. It expects a directory called
cljsin the same directory as the
core.jsfile. These are located inside the
libdirectory in this repo.
cljscontains the standard library and is searched last to allow other libraries to override the standard library's namespaces.
For some examples of files including external files, consult the test directory or the standard library.
- downloads a .jar containing the java-based ClojureScript compiler
- generates a build config file
- compiles src/clojurescript/core.cljs a second time, configured to spit out the stand library as separate files. The standard library is then copied to lib/cljs.
This is the only part of this tool that requires java be installed. Running this script is only necessary after changing src/clojurescript/core.cljs.
Get the generated compiler into such a state that it can recompile src/clojurescript/core.cljs without needing java at all.