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 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.
  • capture-continuation-context - Capture the active SCI context and dynamic bindings for later continuation resumption.
  • continuation-context-fn - Return a function that invokes f with the SCI world and dynamic bindings represented by continuation-context.
  • 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.
  • disable-jit
  • enable-unrestricted-access! - Removed.
  • 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 an isolated runtime world.
  • 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
  • retarget-continuation-context - Copy a captured continuation context for target-ctx, which must belong to the same SCI lineage.
  • set! - Establish thread local binding of dynamic var.
  • 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-detached-context - Invoke zero-argument f outside the currently executing SCI context.
  • 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

---

sci.async

await

(await promise)

Function.

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

_Source

await?

(await? promise)

Function.

Check if promise was marked with await.

_Source

eval-form

(eval-form ctx form)

Function.

Eval single form in ctx.

_Source

eval-form+

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

Function.

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

_Source

eval-string*

(eval-string* ctx s)

Function.

_Source

eval-string+

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

Function.

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)

Function.

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)

Function.

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)

Function.

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

_Source

add-namespace!

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

Function.

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

_Source

all-ns

(all-ns ctx)

Function.

Returns all SCI ns objects in the ctx

_Source

alter-var-root

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

Function.

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

capture-continuation-context

(capture-continuation-context)
(capture-continuation-context ctx)

Function.

Capture the active SCI context and dynamic bindings for later continuation resumption. Must be called from managed SCI evaluation. The returned token is opaque; use continuation-context-fn to resume through it.

The explicit ctx arity is for host embedding boundaries invoked through an interpreted function after the top-level evaluation has returned.

_Source

continuation-context-fn

(continuation-context-fn continuation-context f)

Function.

Return a function that invokes f with the SCI world and dynamic bindings represented by continuation-context.

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

On ClojureScript, when sym names a protocol (except cljs.core/IFn), the sci var holds a protocol entry instead of the raw protocol object. Sci code can then implement the protocol on deftype types, extend those with extend-type and use satisfies?. Host code calling protocol methods on such instances dispatches into the sci implementations.

Options (ignored for protocols):

• :name: The name of the copied var. Defaults to the original var name.
• :copy-meta-from: A symbol resolving to a var whose metadata (:doc, :arglists, :file, :line, :column) is used instead of sym's. Useful for wrapper vars that delegate to another var.

_Source

copy-var*

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

Function.

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

_Source

create-ns

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

Function.

Creates namespace object. Can be used in var metadata.

_Source

disable-jit

_Source

enable-unrestricted-access!

(enable-unrestricted-access!)

Function.

Removed. Use the :unrestricted option of init or eval-string instead. Throws when called.

_Source

err

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

_Source

eval-form

(eval-form ctx form)

Function.

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)

Function.

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.

• :allow: a seqable of allowed symbols. All symbols, even those brought in via :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}

• :interrupt-fn: a zero-arg fn called on every interpreted fn entry / loop entry

• :unrestricted: when true, evaluated code may mutate built-in vars and CLJS instance interop skips :classes checks. Off by default. Applies only to this context: a context created during an unrestricted evaluation is sandboxed unless it also gets this option.

• :fork-fn: optional one-argument host function used by fork to copy values held in SCI world cells that do not implement sci.fork/Forkable and need application-specific isolation. SCI-owned mutable primitives are already world-relative and retain identity.

• :runtime-mode: :standard (the default) retains SCI's direct hot paths. :forkable enables isolated runtime worlds for Vars, dynamic bindings and SCI-owned mutable primitives.

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

_Source

eval-string*

(eval-string* ctx s)

Function.

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

_Source

eval-string+

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

Function.

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)

Function.

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

_Source

fork

(fork ctx)
(fork ctx opts)

Function.

Forks a context (as produced with init) into an isolated runtime world.

Existing SCI Vars and SCI-created mutable primitives retain identity, but their values diverge after the fork. Host values may implement sci.fork/Forkable; opts may contain :fork-fn, which overrides the context's fallback function for other application-specific host values.

_Source

format-stacktrace

(format-stacktrace stacktrace)

Function.

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)

Function.

_Source

get-line-number

(get-line-number reader)

Function.

_Source

in

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

_Source

init

(init opts)

Function.

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)

Function.

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)

Function.

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)

Function.

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)

Function.

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)

Function.

Returns a new sci var.

_Source

normalize-meta

(normalize-meta m)

Function.

_Source

ns

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

_Source

ns-name

(ns-name sci-ns)

Function.

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)

Function.

Parses next form from reader

_Source

parse-next+string

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

Function.

Parses next form from reader

_Source

parse-string

(parse-string ctx s)

Function.

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

_Source

pmap

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

Function.

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)

Function.

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

_Source

resolve

(resolve ctx sym)

Function.

_Source

retarget-continuation-context

(retarget-continuation-context continuation-context target-ctx)

Function.

Copy a captured continuation context for target-ctx, which must belong to the same SCI lineage. The copy has independent dynamic binding boxes.

_Source

set!

(set! dynamic-var v)

Function.

Establish thread local binding of dynamic var

_Source

source-reader

(source-reader x)

Function.

_Source

stacktrace

(stacktrace ex)

Function.

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

_Source

var->symbol

(var->symbol sci-var)

Function.

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

_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-detached-context

(with-detached-context f)

Function.

Invoke zero-argument f outside the currently executing SCI context.

Embeddings use this host boundary when interpreted code recursively creates an independent SCI interpreter. The caller's active world and dynamic binding frame are restored even when f throws. Ordinary nested evaluation of an existing context does not need this function.

_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.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 binds this dynamic var to the evaluating context during eval-form. Projects like sci.configs assume this var to be set in some of their functions.

get-ctx

(get-ctx)

Function.

Retrieve stored ctx or throw an exception.

_Source

reset-ctx!

(reset-ctx! ctx)

Function.

Store ctx

_Source

swap-ctx!

(swap-ctx! f & args)

Function.

Update ctx using f and args

_Source

with-ctx

(with-ctx ctx & body)

Macro.

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)

Function.

_Source