IOCapture.capture(
    f; rethrow=Any, color=false, passthrough=false, capture_buffer=IOBuffer(), io_context=[],
)

Runs the function f and captures the stdout and stderr outputs, without printing them in the terminal, unless passthrough=true.

Returns an object with the following fields:

• .value :: Any: return value of the function, or the error exception object on error
• .output :: String: captured stdout and stderr
• .error :: Bool: set to true if f threw an error, false otherwise
• .backtrace :: Vector: array with the backtrace of the error if an error was thrown

The behaviour can be customized with the following keyword arguments:

• rethrow:

  When set to Any (default), capture will rethrow any exceptions thrown by evaluating f.

  To only throw on a subset of possible exceptions pass the exception type instead, such as InterruptException. If multiple exception types may need to be thrown then pass a Union{...} of the types. Setting it to Union{} will capture all thrown exceptions. Captured exceptions will be returned via the .value field, and will also set .error and .backtrace accordingly.

• color: if set to true, capture inherits the :color property of stdout and stderr, which specifies whether ANSI color/escape codes are expected. This argument is only effective on Julia v1.6 and later.

• passthrough: if set to true, show the output as well as capturing it.

• capture_buffer: The internal buffer used to capture the combined stdout and stderr.

• io_context: An optional vector of IOContext key/value pairs that are passed to the IOContext that wraps the redirected stdout and stderr streams. This only has an effect on Julia v1.6 and later.

Extended help

capture works by temporarily redirecting the standard output and error streams (stdout and stderr) using redirect_stdout and redirect_stderr to a temporary capture_buffer, evaluate the function f and then restores the streams. Both the captured text output and the returned object get captured and returned:

julia> c = IOCapture.capture() do
           println("test")
       end;

julia> c.output
"test\n"

This approach does have some limitations – see the README for more information.

If passthrough=true, the redirected streams will also be passed through to the original standard output. As a result, the output from f would both be captured and shown on screen. Note that stdout and stderr are merged in the pass-through, and color is stripped unless the color option is set to true.

Exceptions. Normally, if f throws an exception, capture simply re-throws it with rethrow. However, by setting rethrow, it is also possible to capture errors, which then get returned via the .value field. Additionally, .error is set to true, to indicate that the function did not run normally, and the catch_backtrace of the exception is returned via .backtrace.

As mentioned above, it is also possible to set rethrow to InterruptException. This will make capture rethrow only InterruptExceptions. This is useful when you want to capture all the exceptions, but allow the user to interrupt the running code with Ctrl+C.

Capture Buffer

Giving a non-standard capture_buffer allows to dynamically process the captured output in arbitrary ways. For example, a custom buffer could truncate the capture of some very large output. The object passed as capture_buffer must implement two methods: Base.write(capture_buffer, bytes) and bytes = Base.take!(capture_buffer). When combined with passthrough, a custom capture_buffer will not affect the pass-through. Thus, for the example of a truncated capture, the pass-through would still show the full output.

Recommended pattern. The recommended way to refer to capture is by fully qualifying the function name with IOCapture.capture. This is also why the package does not export the function. However, if a shorter name is desired, we recommend renaming the function when importing:

using IOcapture: capture as iocapture

This avoids the function name being too generic.