Add new configuration option `continue_on_error`, closes #201. (#257)

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+### Added
+ - A new keyword argument configuration `continue_on_error::Bool = false` has been added
+   which controls the behavior of code execution errors. By default (`continue_on_error =
+   false`) execution errors are re-thrown by Literate (as before). If `continue_on_error =
+   true` is set the error is used as the block result and execution continues with following
+   blocks. ([#201], [#257])
+
 ## [v2.19.1] - 2024-09-13
 ### Fixed
  - Set `:SOURCE_PATH` in the task local storage to the output file when executing code so

src/Literate.jl

@@ -346,6 +346,7 @@ function create_configuration(inputfile; user_config, user_kwargs, type=nothing)
     cfg["softscope"] = type === (:nb) ? true : false # on for Jupyter notebooks
     cfg["keep_comments"] = false
     cfg["execute"] = type === :md ? false : true
+    cfg["continue_on_error"] = false
     cfg["codefence"] = pick_codefence(
         get(user_config, "flavor", cfg["flavor"]),
         get(user_config, "execute", cfg["execute"]),
@@ -433,6 +434,10 @@ Available options:
   output script. Only applicable for `Literate.script`.
 - `execute` (default: `true` for notebook, `false` for markdown): Whether to execute and
   capture the output. Only applicable for `Literate.notebook` and `Literate.markdown`.
+- `continue_on_error` (default: `false`): Whether to continue code execution of remaining
+  blocks after encountering an error. By default execution errors are re-thrown. If
+  `continue_on_error = true` the error will be used as the output of the block instead and
+  execution will continue. This option is only applicable when `execute = true`.
 - `codefence` (default: `````"````@example \$(name)" => "````"````` for `DocumenterFlavor()`
   and `````"````julia" => "````"````` otherwise): Pair containing opening and closing
   code fence for wrapping code blocks.
@@ -621,6 +626,7 @@ function markdown(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwarg
                                       image_formats=config["image_formats"],
                                       file_prefix="$(config["name"])-$(chunknum)",
                                       softscope=config["softscope"],
+                                      continue_on_error=config["continue_on_error"],
                     )
                 end
             end
@@ -639,9 +645,10 @@ end
 function execute_markdown!(io::IO, sb::Module, block::String, outputdir;
                            inputfile::String, fake_source::String,
                            flavor::AbstractFlavor, image_formats::Vector, file_prefix::String,
-                           softscope::Bool)
+                           softscope::Bool, continue_on_error::Bool)
     # TODO: Deal with explicit display(...) calls
-    r, str, _ = execute_block(sb, block; inputfile=inputfile, fake_source=fake_source, softscope=softscope)
+    r, str, _ = execute_block(sb, block; inputfile=inputfile, fake_source=fake_source,
+                              softscope=softscope, continue_on_error=continue_on_error)
     # issue #101: consecutive codefenced blocks need newline
     # issue #144: quadruple backticks allow for triple backticks in the output
     plain_fence = "\n````\n" =>  "\n````"
@@ -777,7 +784,9 @@ function jupyter_notebook(chunks, config)
             cd(config["literate_outputdir"]) do
                 nb = execute_notebook(nb; inputfile=config["literate_inputfile"],
                                           fake_source=config["literate_outputfile"],
-                                          softscope=config["softscope"])
+                                          softscope=config["softscope"],
+                                          continue_on_error=config["continue_on_error"],
+)
             end
         catch err
             @error "error when executing notebook based on input file: " *
@@ -788,7 +797,8 @@ function jupyter_notebook(chunks, config)
     return nb
 end
 
-function execute_notebook(nb; inputfile::String, fake_source::String, softscope::Bool)
+function execute_notebook(nb; inputfile::String, fake_source::String, softscope::Bool,
+                          continue_on_error=continue_on_error)
     sb = sandbox()
     execution_count = 0
     for cell in nb["cells"]
@@ -796,7 +806,9 @@ function execute_notebook(nb; inputfile::String, fake_source::String, softscope:
         execution_count += 1
         cell["execution_count"] = execution_count
         block = join(cell["source"])
-        r, str, display_dicts = execute_block(sb, block; inputfile=inputfile, fake_source=fake_source, softscope=softscope)
+        r, str, display_dicts = execute_block(sb, block; inputfile=inputfile,
+                                              fake_source=fake_source, softscope=softscope,
+                                              continue_on_error=continue_on_error)
 
         # str should go into stream
         if !isempty(str)
@@ -878,7 +890,8 @@ function Base.display(ld::LiterateDisplay, mime::MIME, x)
 end
 
 # Execute a code-block in a module and capture stdout/stderr and the result
-function execute_block(sb::Module, block::String; inputfile::String, fake_source::String, softscope::Bool)
+function execute_block(sb::Module, block::String; inputfile::String, fake_source::String,
+                       softscope::Bool, continue_on_error::Bool)
     @debug """execute_block($sb, block)
     ```
     $(block)
@@ -904,7 +917,7 @@ function execute_block(sb::Module, block::String; inputfile::String, fake_source
         end
     end
     popdisplay(disp) # IOCapture.capture has a try-catch so should always end up here
-    if c.error
+    if c.error && !continue_on_error
         error("""
              $(sprint(showerror, c.value))
              when executing the following code block from inputfile `$(Base.contractuser(inputfile))`

test/runtests.jl

@@ -1459,6 +1459,22 @@ end end
     end # mktempdir
 end end
 
+@testset "continue_on_error=true" begin
+    input_with_error =
+        """
+        # The following will error
+
+        sqrt(-1.0)
+        """
+    mktempdir(@__DIR__) do sandbox
+        inputfile = joinpath(sandbox, "input.jl")
+        write(inputfile, input_with_error)
+        Literate.markdown(inputfile, sandbox; continue_on_error = true, execute = true)
+        output_md = read(joinpath(sandbox, "input.md"), String)
+        @test occursin("DomainError(-1.0", output_md)
+    end
+end
+
 @testset "Configuration" begin; Base.CoreLogging.with_logger(Base.CoreLogging.NullLogger()) do
     mktempdir(@__DIR__) do sandbox
         cd(sandbox) do