CodeEvaluation

A small utility package to emulate executing Julia code, seemingly in a clean Main module.

There are two main parts to the API:

1. The Sandbox object: provides a clean, mock Julia Main module, and the related low-level evaluate! function to directly evaluate Julia expressions in the sandbox.

2. Higher level functions that can be used to run code in the sandbox in different modes (codeblock! and replblock!).

Constructing a Sandbox object provides you

The evaluate! function can be used to evaluate Julia expressions within the context of the sandbox module. It returns a Result object that contains the captured return value and what was printed into the standard output and error streams.

julia> sb = CodeEvaluation.Sandbox();

julia> r = CodeEvaluation.evaluate!(sb, :(x = 40 + 2));

julia> r.value, r.output
(42, "")

julia> r = CodeEvaluation.evaluate!(sb, :(println("x = " * string(x))));

julia> r.value, r.output
(nothing, "x = 42\n")

As an implementation detail, it uses the IOCapture.jl package underneath to perform output capture of the evaluated code.

As an asterisk, as the sandboxes are implemented as anonymous Julia modules, all within the same Julia process, there are limitations to to their independence (e.g. method definitions and other global state modifications can, of course, leak over). The goal is to be best-effort in terms of providing a seemingly independent Julia session to execute code in.

Presently, there are two functions that offer a

1. codeblock! is meant to offer a simple way to execute a block of Julia code (provided as a simple string, not a parsed expression). This is roughly meant to correspond to running a Julia script.

   julia> sb = CodeEvaluation.Sandbox();
   
   julia> code = """
          x = 40
          println("x = \$x")
          x + 2
          """
   "x = 40\nprintln(\"x = \$x\")\nx + 2\n"
   
   julia> r = CodeEvaluation.codeblock!(sb, code);
   
   julia> r.value, r.output
   (42, "x = 40\n")

2. replblock! emulates a REPL session. The input code is split up and evaluated as if copy-pasted into the REPL line-by-line. The outputs are then captured as if they would be shown in the REPL.

   julia> sb = CodeEvaluation.Sandbox();
   
   julia> code = """
          x = 40
          println("x = \$x")
          x + 2
          """
   "x = 40\nprintln(\"x = \$x\")\nx + 2\n"
   
   julia> r = CodeEvaluation.replblock!(sb, code);

   At this point, using the CodeEvaluation.join_to_string(r) function, the package is able to reconstruct how the corresponding REPL session would look like.

   julia> x = 40
   40
   
   julia> println("x = $x")
   x = 40
   
   julia> x + 2
   42