Liking cljdoc? Tell your friends :D

Small Clojure Interpreter

CircleCI Clojars Project cljdoc badge

A tiny implementation of Clojure in Clojure.

Rationale

You want to evaluate code from user input, but eval isn't safe or simply doesn't work.

This library works with:

  • Clojure on the JVM
  • Clojure compiled with GraalVM native
  • ClojureScript, even when compiled with :advanced

It is used as the interpreter for babashka.

Status

Experimental. Breaking changes are expected to happen at this phase.

Installation

Use as a dependency:

[borkdude/sci "0.0.4"]

Usage

(require '[sci.core :as sci])
(sci/eval-string "(inc 1)") => ;; 2
(sci/eval-string "(inc x)" {:bindings {'x 2}}) ;;=> 3

Anonymous function literals are allowed with currently up to three positional arguments. This is an arbitrary limit and may be changed in the future.

(sci/eval-string "(#(+ %1 %2 %3) 1 2 3)") => ;; 6

Currently only the following special forms/macros are supported: anonymous function literals like #(%1 %2), quote, do,if, when, let, and, or, ->, ->>, as->.

By default sci only enables access to the pure non-side-effecting functions in Clojure. More functions can be enabled, at your own risk, using :bindings:

user=> (sci/eval-string "(println \"hello\")" {:bindings {'println println}})
hello
nil

More examples of what is currently possible can be found at babashka.

Caveats

To make the rand-* functions behave well when compiling to a GraalVM native binary, use this setting:

--initialize-at-run-time=java.lang.Math\$RandomNumberGeneratorHolder

Test

Required: lein, the clojure CLI and GraalVM.

To succesfully run the GraalVM tests, you will have to compile the binary first with script/compile.

To run all tests:

script/test

License

Copyright © 2019 Michiel Borkent

Distributed under the Eclipse Public License 1.0. This project contains code from Clojure and ClojureScript which are also licensed under the EPL 1.0. See LICENSE.

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close