API.md

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

• sci.async
  • await - Mark promise to be flatteded into top level async evaluation, similar
  • await? - Check if promise was marked with await.
  • eval-string*
  • eval-string+ - Same as eval-string* but returns map with :val, the evaluation
  • require - Async require that can be substituted for sync require by
• 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
  • add-import! - Adds import of class named by class-name (a symbol) to namespace named by `ns-
  • add-namespace! - Adds namespace map ns-map named by the symbol ns-name to
  • 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
  • assert - SCI var that represents SCI's clojure.core/assert
  • binding - Macro for binding sci vars
  • cljs-ns-publics
  • copy-ns - Returns map of names to SCI vars as a result of copying public
  • 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
  • err - SCI var that represents SCI's clojure.core/err
  • eval-form - Evaluates form (as produced by parse-string or parse-next) in the
  • eval-string - Evaluates string s as one or multiple Clojure expressions using the Small Cloj
  • eval-string* - Evaluates string s in the context of ctx (as produced with
  • 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-sy
  • 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
  • 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
  • new-var - Returns a new sci var.
  • 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-string - Parses string s in the context of ctx (as produced with
  • 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-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
  • set! - Establish thread local binding of dynamic var
  • stacktrace - Returns list of stacktrace element maps from exception, if available.
  • 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
  • with-out-str - Evaluates exprs in a context in which sci's out is bound to a fresh
• 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

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-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-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)

Macro.

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

cljs-ns-publics

_source

copy-ns

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

Macro.

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)

Macro.

Copies contents from var sym to a new sci var. The value ns is an object created with sci.core/create-ns. If new-name is supplied, the copied var will be named new-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

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

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)

Macro.

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

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-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-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

set!

(set! dynamic-var v)

Establish thread local binding of dynamic var
_source

stacktrace

(stacktrace ex)

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

with-bindings

(with-bindings bindings-map & body)

Macro.

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)

Macro.

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)

Macro.

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.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