Differences from Clojure

What follows is a section-by-section review of the sections on the left nav of clojure.org, enumerating what is different in ClojureScript.

Some general questions:

• how to talk about things that are missing?
• need separate terms for missing by design, and missing til we get to it?
• link out to design discuss/tickets for people who want to participate?
• should each section (doubly briefly) enumerate what is the same?
• otherwise this makes for slightly depressing reading
• esp. since most things are there

Rationale

The rataionale for ClojureScript is much the same as for Clojure, with JavaScript in the role of platform.

State and Identity

Same as Clojure. Clojure's identity model is simpler and more robusy that mutable state, even in single threaded environments.

Dynamic Development

The ClojureScript REPL can be launched from within the Clojure REPL as follows.

TBD instructions

TBD differences in reloading changed code.

Functional Programming

ClojureScript has the same immutable collections, but the alphas versions are not necessarily persistent. Persistent versions will be added over time.

Lisp

ClojureScript's macros are written in Clojure, and are referenced via the refer-macros keyword in namespace declarations:

(ns my.namespace (:refer-macros '[my.macros :as my])

The ":as prefix" selector is required in :refer-macros.

Runtime Polymorphism

ClojureScript protocols have the same semantics as Clojure protocols.

Multimethods are not yet implemented, but are on the development roadmap.

Concurrent Programming

• atoms work as in Clojure
• no refs or STM
• binding works as in Clojure
• TODO all vars are rebindable ?
• agents may be implemented in the future
• vars are not reified at runtime
• many development time uses of reification are obviated by access to Clojure data structures via the analyzer

Hosted on the JVM

ClojureScript is hosted on JavaScript + Google's Closure compiler.

TODO: example

Getting Started

See [TODO]

The Reader

TBD

The REPL and main

TBD

Evaluation

• ClojureScript has the same evaluation rules as Clojure
• load and load-file work as in Clojure (TODO ?)
• runtime eval is not supported in ClojureScript

Special Forms

• The :macro metadata key is not used in ClojureScript, as macros are written in Clojure
• vars are not reified at runtime, and the var special form is not implemented
• Like Clojure, and unlike JavaScript try, ClojureScript catches exceptions by type
• monitor-enter, monitor-exit, and locking are not implemented

Special Forms

The following ClojureScript special forms are identical to their Clojure cousins: if, do, let, quote, loop, recur, throw, and try.

• def differences
• No metadata is placed on vars: there are no vars in ClojureScript
• TODO is some of this available some other way? ** e.g. is :private enforced by compiler ** hmm, @#'private bypass trick won't work in ClojureScript
• if differences
• the section about Java's boolean boxes is irrelevant in ClojureScript
• var special form does not exist in ClojureScript
• fn differences
• TODO anything different in arity overloading limits?
• TODO pre- and post- conditions?
• monitor-enter and monitor-exit do not exist in ClojureScript

Macros

Macros are Clojure macros, and are available only during compilation.

Other Functions

• printing
• TODO is there an out?
• regex support
• TODO is there a different to document here?

Data Structures

• Numbers
• in the first release, numbers are just JavaScript numbers
• later releases will use JavaScript classes to provide Clojure-equivalent number types
• coercions are not implemented, since there are no types to coerce to (yet)
• Characters
• JavaScript has no character type. Clojure characters are represented internally as strings
• Keywords
• TODO are not interned in ClojureScript
• Collections
• in the first release, some immutable collections are copy-in-write
• later releases will have Clojure-equivalent persistent collections
• Most but not all collection fns are implemented. See the "Not Implemented" section below

Seqs

Seqs have the same semantics as in Clojure, and almost all Seq library functions are available in ClojureScript.

Transients

Transients are not implemented at this time.

Multimethods

Multimethods are not implemented at this time.

Protocols

• Protocols and deftype work as in Clojure.
• Reflective capabilities (extends?, extenders, satisifies?) work as in Clojure.
• defrecord, reify, and extend are not implemented yet.

Missing but not obvious from the above

• sort

Metadata

Works as in Clojure

Namespaces

• Namespace use is not supported. You must use the :as form of require.
• Macros are written in Clojure, and are referenced via the new :require-macros option to ns

Libs

Existing Clojure libs will have to conform to the ClojureScript subset in order to work in ClojureScript.

Vars and the Global Environment

• Def and binding work as in Clojure.
• Atoms work as in Clojure.
• Refs and agents are not currently implementd.
• Var validators work as in Clojure.
• TODO What about doc and find-doc?

Refs and Transactions

Refs and tranasactions are not currently supported.

Agents

Agents are not currently supported.

Atoms

Atoms work as in Clojure.

Host Interop

The host language interop features work as in Clojure.

TODO document . for resolution (method call vs. member access)

Compilation and Class Generation

Compilation is entirely different from Clojure:

• All ClojureScript programs are compiled into optimized JavaScript.
• gen-class, gen-interface et al are unnecessary and unimplemented in ClojureScript.

Other Libraries

ClojureScript currently includes the following non-core namespaces ported from Clojure:

• clojure.set => cljs.set
• clojure.string => cljs.string

TODO why have we named these differently?

Differences with other Lisps

ClojureScript is the same (at a Lisp level) as Clojure.

Contributing

Clojure and ClojureScript share the same Contributor Agreement and development process.

Not Implemented

Master list of fns from Clojure not currently implemented in ClojureScript. TODO: would be great to have a program generate this list