sci

API

Anything in the SCI repository with impl in the name should be regarded implementation detail and may change at any time. Please reach out if you end up needing something from the dark impl side!

Table of contents

• cljs.core
  • set! - Establish thread local binding of dynamic var.
• sci.async
  • await - Mark promise to be flatteded into top level async evaluation, similar to top level await.
  • await? - Check if promise was marked with await.
  • eval-form - Eval single form in ctx.
  • eval-form+ - Eval single form in ctx, return map of :val and :ns.
  • eval-string*
  • eval-string+ - Same as eval-string* but returns map with :val, the evaluation result, and :ns, the last active namespace.
  • require - Async require that can be substituted for sync require by {:namespaces {'clojure.core {'require scia/require}}}.
• sci.core - The main SCI API namespace.
  • *1
  • *2
  • *3
  • *e
  • add-class! - Adds class (JVM class or JS object) to ctx as class-name (a symbol).
  • add-import! - Adds import of class named by class-name (a symbol) to namespace named by ns-name (a symbol) under alias alias (a symbol).
  • add-js-lib! - Add js library to context, so it can be used with require.
  • add-namespace! - Adds namespace map ns-map named by the symbol ns-name to ctx.
  • all-ns - Returns all SCI ns objects in the ctx.
  • alter-var-root - Atomically alters the root binding of sci var v by applying f to its current value plus any args.
  • assert - SCI var that represents SCI’s clojure.core/assert.
  • binding - Macro for binding sci vars.
  • copy-ns - Returns map of names to SCI vars as a result of copying public Clojure vars from ns-sym (a symbol).
  • copy-var - Copies contents from var sym to a new sci var.
  • copy-var* - Copies Clojure var to SCI var.
  • create-ns - Creates namespace object.
  • enable-unrestricted-access! - Calling this will enable - Altering core vars using alter-var-root - In CLJS: set! is able to set the value of any var.
  • err - SCI var that represents SCI’s clojure.core/*err*.
  • eval-form - Evaluates form (as produced by parse-string or parse-next) in the context of ctx (as produced with init).
  • eval-string - Evaluates string s as one or multiple Clojure expressions using the Small Clojure Interpreter.
  • eval-string* - Evaluates string s in the context of ctx (as produced with init).
  • eval-string+ - Evaluates string s in the context of ctx (as produced with init).
  • file - SCI var that represents SCI’s clojure.core/*file*.
  • find-ns - Returns SCI ns object as created with sci/create-ns from ctx found by ns-sym.
  • fork - Forks a context (as produced with init) into a new context.
  • format-stacktrace - Returns a list of formatted stack trace elements as strings from stacktrace.
  • future - Like clojure.core/future but also conveys sci bindings to the thread.
  • get-column-number
  • get-line-number
  • in - SCI var that represents SCI’s clojure.core/*in*.
  • init - Creates an initial sci context from given options opts.
  • intern - Finds or creates a sci var named by the symbol name in the namespace ns (which can be a symbol or a sci namespace), setting its root binding to val if supplied.
  • merge-opts - Updates a context with opts merged in and returns it.
  • new-dynamic-var - Same as new-var but adds :dynamic true to meta.
  • new-macro-var - Same as new-var but adds :macro true to meta as well as :sci/macro true to meta of the fn itself.
  • new-var - Returns a new sci var.
  • normalize-meta
  • ns - SCI var that represents SCI’s clojure.core/*ns*.
  • ns-name - Returns name of SCI ns as symbol.
  • out - SCI var that represents SCI’s clojure.core/*out*.
  • parse-next - Parses next form from reader.
  • parse-next+string - Parses next form from reader.
  • parse-string - Parses string s in the context of ctx (as produced with init).
  • pmap - Like clojure.core/pmap but also conveys sci bindings to the threads.
  • print-dup - SCI var that represents SCI’s clojure.core/*print-dup*.
  • print-err-fn - SCI var that represents SCI’s cljs.core/*print-err-fn*.
  • print-fn - SCI var that represents SCI’s cljs.core/*print-fn*.
  • print-length - SCI var that represents SCI’s clojure.core/*print-length*.
  • print-level - SCI var that represents SCI’s clojure.core/*print-level*.
  • print-meta - SCI var that represents SCI’s clojure.core/*print-meta*.
  • print-namespace-maps - SCI var that represents SCI’s clojure.core/*print-namespace-maps*.
  • print-newline - SCI var that represents SCI’s cljs.core/*print-newline*.
  • print-readably - SCI var that represents SCI’s clojure.core/*print-readably*.
  • read-eval - SCI var that represents SCI’s clojure.core/*read-eval*.
  • reader - Coerces x into indexing pushback-reader to be used with parse-next.
  • resolve
  • source-reader
  • stacktrace - Returns list of stacktrace element maps from exception, if available.
  • var->symbol - Returns a fully qualified symbol from a sci.lang.Var.
  • with-bindings - Macro for binding sci vars.
  • with-in-str - Evaluates body in a context in which sci’s in is bound to a fresh StringReader initialized with the string s.
  • with-out-str - Evaluates exprs in a context in which sci’s out is bound to a fresh StringWriter.
• sci.ctx-store - Canonical place for projects to store, update and retrieve a context.
  • get-ctx - Retrieve stored ctx or throw an exception.
  • reset-ctx! - Store ctx.
  • swap-ctx! - Update ctx using f and args.
  • with-ctx - Bind ctx during execution of body.
• sci.lang
  • Namespace - Representation of a SCI namespace, created e.g.
  • Type - Representation of a SCI custom type, created e.g.
  • Var - Representation of a SCI var, created e.g.
  • notify-watches

---

cljs.core

set!

(set! dynamic-var v)

Function.

Establish thread local binding of dynamic var

_Source

---

sci.async

await

(await promise)

Mark promise to be flatteded into top level async evaluation, similar to top level await.

_Source

await?

(await? promise)

Check if promise was marked with await.

_Source

eval-form

(eval-form ctx form)

Eval single form in ctx.

_Source

eval-form+

(eval-form+ ctx s)
(eval-form+ ctx form opts)

Eval single form in ctx, return map of :val and :ns.

_Source

eval-string*

(eval-string* ctx s)

_Source

eval-string+

(eval-string+ ctx s)
(eval-string+ ctx s opts)

Same as eval-string* but returns map with :val, the evaluation result, and :ns, the last active namespace. The return value can be passed back into opts to preserve the namespace state.

_Source

require

Async require that can be substituted for sync require by {:namespaces {'clojure.core {'require scia/require}}}

_Source

---

sci.core

The main SCI API namespace.

*1

_Source

*2

_Source

*3

_Source

*e

_Source

add-class!

(add-class! ctx class-name class)

Adds class (JVM class or JS object) to ctx as class-name (a symbol). Returns mutated context.

_Source

add-import!

(add-import! ctx ns-name class-name alias)

Adds import of class named by class-name (a symbol) to namespace named by ns-name (a symbol) under alias alias (a symbol). Returns mutated context.

_Source

add-js-lib!

(add-js-lib! ctx name-str js-lib)

Add js library to context, so it can be used with require.

_Source

add-namespace!

(add-namespace! ctx ns-name ns-map)

Adds namespace map ns-map named by the symbol ns-name to ctx. Returns mutated context.

_Source

all-ns

(all-ns ctx)

Returns all SCI ns objects in the ctx

_Source

alter-var-root

(alter-var-root v f)
(alter-var-root v f & args)

Atomically alters the root binding of sci var v by applying f to its current value plus any args.

_Source

assert

SCI var that represents SCI’s clojure.core/assert

_Source

binding

(binding bindings & body)

Function.

Macro for binding sci vars. Must be called with a vector of sci dynamic vars to values.

_Source

copy-ns

(copy-ns ns-sym sci-ns)
(copy-ns ns-sym sci-ns opts)

Function.

Returns map of names to SCI vars as a result of copying public Clojure vars from ns-sym (a symbol). Attaches sci-ns (result of sci/create-ns) to meta. Copies :name, :macro :doc, :no-doc and :argslists metadata.

Options:

• :exclude: a seqable of names to exclude from the namespace. Defaults to none.

• :copy-meta: a seqable of keywords to copy from the original var meta. Use :all instead of a seqable to copy all. Defaults to [:doc :arglists :macro].

• :exclude-when-meta: seqable of keywords; vars with meta matching these keys are excluded. Defaults to [:no-doc :skip-wiki]

The selection of vars is done at compile time which is mostly important for ClojureScript to not pull in vars into the compiled JS. Any additional vars can be added after the fact with sci/copy-var manually.

_Source

copy-var

(copy-var sym ns)
(copy-var sym ns opts)

Function.

Copies contents from var sym to a new sci var. The value ns is an object created with sci.core/create-ns.

Options:

• :name: The name of the copied var. Defaults to the original var name.

_Source

copy-var*

(copy-var* clojure-var sci-ns)

Copies Clojure var to SCI var. Runtime analog of compile time copy-var.

_Source

create-ns

(create-ns sym)
(create-ns sym meta)

Creates namespace object. Can be used in var metadata.

_Source

enable-unrestricted-access!

(enable-unrestricted-access!)

Calling this will enable

• Altering core vars using alter-var-root
• In CLJS: set! is able to set the value of any var.
• In CLJS: instance method calls are not restricted to only :classes

In the future, more unrestricted access may be added, so only use this when you’re not using SCI as a sandbox.

_Source

err

SCI var that represents SCI’s clojure.core/*err*

_Source

eval-form

(eval-form ctx form)

Evaluates form (as produced by parse-string or parse-next) in the context of ctx (as produced with init). To allow namespace switches, establish root binding of sci/ns with sci/binding or sci/with-bindings.

_Source

eval-string

(eval-string s)
(eval-string s opts)

Evaluates string s as one or multiple Clojure expressions using the Small Clojure Interpreter.

The map opts may contain the following:

• :namespaces: a map of symbols to namespaces, where a namespace is a map with symbols to values, e.g.: {'foo.bar {'x 1}}. These namespaces can be used with require.

• :bindings: :bindings x is the same as :namespaces {'user x}.

• :allow: a seqable of allowed symbols. All symbols, even those brought in via :bindings or :namespaces have to be explicitly enumerated.

• :deny: a seqable of disallowed symbols, e.g.: [loop quote recur].

• :features: when provided a non-empty set of keywords, sci will process reader conditionals using these features (e.g. #{:bb}).

• :ns-aliases: a map of aliases to namespaces that are globally valid, e.g. {'clojure.test 'cljs.test}

_Source

eval-string*

(eval-string* ctx s)

Evaluates string s in the context of ctx (as produced with init).

_Source

eval-string+

(eval-string+ ctx s)
(eval-string+ ctx s opts)

Evaluates string s in the context of ctx (as produced with init).

Options: *:ns - the namespace to start evaluation in (defaults to the value of sci/ns)

Returns map with:

• :val - the evaluated value
• :ns - the namespace object

_Source

file

SCI var that represents SCI’s clojure.core/*file*

_Source

find-ns

(find-ns ctx ns-sym)

Returns SCI ns object as created with sci/create-ns from ctx found by ns-sym.

_Source

fork

(fork ctx)

Forks a context (as produced with init) into a new context. Any new vars created in the new context won’t be visible in the original context.

_Source

format-stacktrace

(format-stacktrace stacktrace)

Returns a list of formatted stack trace elements as strings from stacktrace.

_Source

future

(future & body)

Function.

Like clojure.core/future but also conveys sci bindings to the thread.

_Source

get-column-number

(get-column-number reader)

_Source

get-line-number

(get-line-number reader)

_Source

in

SCI var that represents SCI’s clojure.core/*in*

_Source

init

(init opts)

Creates an initial sci context from given options opts. The context can be used with eval-string*. See eval-string for available options. The internal organization of the context is implementation detail and may change in the future.

_Source

intern

(intern ctx sci-ns name)
(intern ctx sci-ns name val)

Finds or creates a sci var named by the symbol name in the namespace ns (which can be a symbol or a sci namespace), setting its root binding to val if supplied. The namespace must exist in the ctx. The sci var will adopt any metadata from the name symbol. Returns the sci var.

_Source

merge-opts

(merge-opts ctx opts)

Updates a context with opts merged in and returns it.

_Source

new-dynamic-var

(new-dynamic-var name)
(new-dynamic-var name init-val)
(new-dynamic-var name init-val meta)

Same as new-var but adds :dynamic true to meta.

_Source

new-macro-var

(new-macro-var name init-val)
(new-macro-var name init-val meta)

Same as new-var but adds :macro true to meta as well as :sci/macro true to meta of the fn itself.

_Source

new-var

(new-var name)
(new-var name init-val)
(new-var name init-val meta)

Returns a new sci var.

_Source

normalize-meta

(normalize-meta m)

_Source

ns

SCI var that represents SCI’s clojure.core/*ns*

_Source

ns-name

(ns-name sci-ns)

Returns name of SCI ns as symbol.

_Source

out

SCI var that represents SCI’s clojure.core/*out*

_Source

parse-next

(parse-next ctx reader)
(parse-next ctx reader opts)

Parses next form from reader

_Source

parse-next+string

(parse-next+string ctx reader)
(parse-next+string ctx reader opts)

Parses next form from reader

_Source

parse-string

(parse-string ctx s)

Parses string s in the context of ctx (as produced with init).

_Source

pmap

(pmap f coll)
(pmap f coll & colls)

Like clojure.core/pmap but also conveys sci bindings to the threads.

_Source

print-dup

SCI var that represents SCI’s clojure.core/*print-dup*

_Source

print-err-fn

SCI var that represents SCI’s cljs.core/*print-err-fn*

_Source

print-fn

SCI var that represents SCI’s cljs.core/*print-fn*

_Source

print-length

SCI var that represents SCI’s clojure.core/*print-length*

_Source

print-level

SCI var that represents SCI’s clojure.core/*print-level*

_Source

print-meta

SCI var that represents SCI’s clojure.core/*print-meta*

_Source

print-namespace-maps

SCI var that represents SCI’s clojure.core/*print-namespace-maps*

_Source

print-newline

SCI var that represents SCI’s cljs.core/*print-newline*

_Source

print-readably

SCI var that represents SCI’s clojure.core/*print-readably*

_Source

read-eval

SCI var that represents SCI’s clojure.core/*read-eval*

_Source

reader

(reader x)

Coerces x into indexing pushback-reader to be used with parse-next. Accepts: string or java.io.Reader.

_Source

resolve

(resolve ctx sym)

_Source

source-reader

(source-reader x)

_Source

stacktrace

(stacktrace ex)

Returns list of stacktrace element maps from exception, if available.

_Source

var->symbol

(var->symbol sci-var)

Returns a fully qualified symbol from a sci.lang.Var

_Source

with-bindings

(with-bindings bindings-map & body)

Function.

Macro for binding sci vars. Must be called with map of sci dynamic vars to values. Used in babashka.

_Source

with-in-str

(with-in-str s & body)

Function.

Evaluates body in a context in which sci’s in is bound to a fresh StringReader initialized with the string s.

_Source

with-out-str

(with-out-str & body)

Function.

Evaluates exprs in a context in which sci’s out is bound to a fresh StringWriter. Returns the string created by any nested printing calls.

_Source

---

sci.ctx-store

Canonical place for projects to store, update and retrieve a context. This can be used by projects that need to expose their context to functions. SCI does not populate this dynamic var itself during evaluation. Projects like sci.configs assume this var to be set in some of their functions.

get-ctx

(get-ctx)

Retrieve stored ctx or throw an exception.

_Source

reset-ctx!

(reset-ctx! ctx)

Store ctx

_Source

swap-ctx!

(swap-ctx! f & args)

Update ctx using f and args

_Source

with-ctx

(with-ctx ctx & body)

Function.

Bind ctx during execution of body.

_Source

---

sci.lang

Namespace

Representation of a SCI namespace, created e.g. with (create-ns 'foo). The fields of this type are implementation detail and should not be accessed directly.

_Source

Type

Representation of a SCI custom type, created e.g. with (defrecord Foo []). The fields of this type are implementation detail and should not be accessed directly.

_Source

Var

Representation of a SCI var, created e.g. with (defn foo []) The fields of this type are implementation detail and should not be accessed directly.

_Source

notify-watches

(notify-watches ref watches old-val new-val)

_Source

This site is open source. Improve this page.