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!

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, return map of :val and :ns.

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

`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

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

`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

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

_Source

Files

API.md

Latest commit

History

API.md

File metadata and controls

API

Table of contents