A sequence of evaluations against one Schooner.Environment, each seeing what the ones before it defined: the evaluation state behind mix schooner.repl, for building a console of your own.

iex> session = Schooner.Session.new(Schooner.Environment.new(pre_imports: [["scheme", "base"]]))
iex> {:ok, _, session} = Schooner.Session.eval(session, "(define x 41)")
iex> {:ok, 42, _session} = Schooner.Session.eval(session, "(+ x 1)")

Schooner.eval/3 keeps a script's top-level defines and imported variables in the environment, but its define-syntax macros, and the macros its (import ...) forms bring in from a library such as one loaded with Schooner.Library.Loader, last only for that call. A session keeps them too, so a later evaluation can use a macro an earlier one defined or imported:

iex> session = Schooner.Session.new(Schooner.Environment.new(pre_imports: [["scheme", "base"]]))
iex> {:ok, _, session} =
...>   Schooner.Session.eval(session, "(define-syntax twice (syntax-rules () ((_ e) (begin e e))))")
iex> {:ok, 3, _session} = Schooner.Session.eval(session, "(twice 1) 3")

eval/3 returns the next session whether the evaluation succeeded or not, and an error doesn't end the session. What the failing source did before the error stays done, as with Schooner.eval/3: the definitions it evaluated, and its imports and macros once they were read and resolved.

As with Schooner.Environment, the session's definitions live in the dictionary of the process that built the environment, so use a session only from that process.

The session's imports are resolved against the environment's registry, so a session can import only what a script evaluated with Schooner.eval/3 against the same environment could.