joker

README

Joker

Joker is a small interpreted dialect of Clojure written in Go.

Getting Started

Download pre-built binary executable for your platform or build it yourself. Then run joker without arguments to launch REPL or pass the filename of the script you want to execute. Joker uses .joke filename extension.

Documentation

Standard library reference

Project goals

These are high level goals of the project that guide design and implementation decisions.

• Be suitable for scripting (lightweight, fast startup). This is something that Clojure is not good at and my personal itch I am trying to scratch.
• Be user friendly. Good error messages and stack traces are absolutely critical for programmer's happiness and productivity.
• Provide some tooling for Clojure and its dialects. Joker has linter mode which can be used for linting Joker, Clojure and ClojureScript code. It catches some basic errors. For those who don't use Cursive, this is probably already better than the status quo. Tooling is one of the primary Joker use cases for me, so I intend to improve and expand it.
• Be as close (syntactically and semantically) to Clojure as possible. Joker should truly be a dialect of Clojure, not a language inspired by Clojure. That said, there is a lot of Clojure features that Joker doesn't and will never have. Being close to Clojure only applies to features that Joker does have.

Project non-goals

• Performance. If you need it, use Cloiure. Joker is a naive implementation of an interpreter that evaluates unoptimized AST directly. I may be interested in doing some basic optimizations but this is definitely not a priority.
• Have all Clojure features. Some features are impossible to implement due to a different host language (Go vs Java), others I don't find that important for the use cases I have in mind for Joker. But generally Clojure is a pretty large language at this point and it is simply unfeasible to reach feature parity with it, even with naive implementation.

Differences with Clojure

1. Primitive types are different due to a different host language and desire to simplify things. Scripting doesn't normally require all the integer and float types, for example. Here is a list of Joker's primitive types:

Joker type	Corresponding Go type
BigFloat	big.Float
BigInt	big.Int
Bool	bool
Char	rune
Double	float64
Int	int
Keyword	n/a
Nil	n/a
Ratio	big.Rat
Regex	regexp.Regexp
String	string
Symbol	n/a

Note that Nil is a type that has one value nil.

1. The set of persistent data structures is much smaller:

Joker type	Corresponding Clojure type
ArrayMap	PersistentArrayMap
MapSet	PersistentHashSet (or hypothetical PersistentArraySet, depending on which kind of underlying map is used)
HashMap	PersistentHashMap
List	PersistentList
Vector	PersistentVector

1. Joker doesn't have the same level of interoperability with the host language (Go) as Clojure does with Java or ClojureScript does with JavaScript. It doesn't have access to arbitrary Go types and functions. There is only a small fixed set of built-in types and interfaces. Dot notation for calling methods is not supported (as there are no methods). All Java/JVM specific functionality of Clojure is not implemented for obvious reasons.
2. Joker is single-threaded with no support for concurrency or parallelism. Therefore no refs, agents, futures, promises, locks, volatiles, transactions, p* functions that use multiple threads. Vars always have just one "root" binding.
3. The following features are not implemented: protocols, records, structmaps, multimethods, chunked seqs, transients, tagged literals and reader conditionals, unchecked arithmetics, primitive arrays, custom data readers, transducers, validators and watch functions for vars and atoms, hierarchies, sorted maps and sets.
4. Unrelated to the features listed above, the following function from clojure.core namespace are not currently implemented but will probably be implemented in some form in the future: subseq, iterator-seq, reduced?, reduced, mix-collection-hash, definline, re-groups, hash-ordered-coll, enumeration-seq, compare-and-set!, rationalize, clojure-version, load-reader, find-keyword, comparator, letfn, resultset-seq, line-seq, file-seq, sorted?, ensure-reduced, rsubseq, pr-on, seque, alter-var-root, hash-unordered-coll, re-matcher, unreduced.
5. Built-in namespaces don't have clojure or joker prefix. The core namespace is called core. Other namespaces (string, json, os) are in their infancy.
6. Miscellaneous:
7. case is just a syntactic sugar on top of condp and doesn't require options to be constants. It scans all the options sequentially.
8. refer-clojure is not a thing. Use (core/refer 'core) instead if you really need to.
9. slurp only takes one argument - a filename (string). No options are supported.
10. ifn? is called callable?
11. Map entry is represented as a two-element vector.

Building

Joker's only dependency is readline. Below commands should get you up and running. Ignore the error message about undefined coreData after you run go get: coreData will be generated by go generate.

go get github.com/candid82/joker
cd $GOPATH/src/github.com/candid82/joker
go generate ./...
go build
./joker

License

Copyright (c) 2016 Roman Bataev. All rights reserved.
The use and distribution terms for this software are covered by the
Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
which can be found in the LICENSE file.

Joker contains parts of Clojure source code (from clojure.core namespace). Clojure is licensed as follows:

Copyright (c) Rich Hickey. All rights reserved.
The use and distribution terms for this software are covered by the
Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
which can be found in the file epl-v10.html at the root of this distribution.
By using this software in any fashion, you are agreeing to be bound by
the terms of this license.
You must not remove this notice, or any other, from this software.