Features and improvements (#28)

* strip prompt, VSCode `show` methods

* add some basic tests

* add support for named blocks

* add named blocks to docs

* bump

Author: ericphanson

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.7'
+          - '1.8'
           - '1'
         os:
           - windows-latest

Project.toml

@@ -34,7 +34,7 @@ StructTypes = "1.7"
 Test = "<0.0.1,1"
 UUIDs = "<0.0.1,1"
 agg_jll = "1.4.3"
-julia = "1.7"
+julia = "1.8"
 pandoc_jll = "3.1.9"
 
 [extras]

docs/src/creating_casts.md

@@ -13,10 +13,21 @@ cast"""
     """0.25
 ```
 
-The `Cast` objects have a `show` method defined for HTML, allowing rich display with a local [asciinema-player](https://github.com/asciinema/asciinema-player), in Documenter, Pluto, jupyter, etc. For convenient use with Documenter in particular, see the `@cast` syntax in [Documenter usage](@ref). Note that this player needs the asciinema-player javascript and CSS assets to be loaded.
+The `Cast` objects have a `show` method defined for HTML, allowing rich display with a local [asciinema-player](https://github.com/asciinema/asciinema-player), in Documenter, Pluto, jupyter, VSCode, etc. For convenient use with Documenter in particular, see the `@cast` syntax in [Documenter usage](@ref). Note that this player needs the asciinema-player javascript and CSS assets to be loaded (note that in VSCode, this happens automatically).
 
 They can be saved to a `.cast` file using [`Asciicast.save`](@ref) or saved to a gif using [`Asciicast.save_gif`](@ref). See also [Markdown usage](@ref) for easier integration into READMEs and other documents.
 
+Note also that `julia>` prompts may be prepended. In this case, existing outputs will be discarded, similarly to the REPL's prompt-pasting feature:
+
+```@example
+using Asciicast
+c = cast"""
+       julia> 1+1
+       3 # note: wrong!
+
+       """0.25
+```
+
 ```@docs
 @cast_str
 ```

docs/src/markdown_usage.md

@@ -37,12 +37,32 @@ Note that the attributes must be separated by spaces, not commas, as shown above
 
 Here, the gifs are generated with [`agg`](https://github.com/asciinema/agg) (which is installed automatically using a JLL package), and the font-size parameter is passed there. Currently no other `agg` parameters are supported, but file an issue if you have a use for one.
 
+### Named blocks
+
+One can name blocks to continue execution after interrupting by some text. For example:
+````markdown
+Here we have `x`:
+```julia {cast="true" name="ex1"}
+x=2
+
+```
+
+Now we add 1:
+```julia {cast="true" name="ex1"}
+y = x+1
+
+```
+````
+
+This works the same way as [named example blocks in Documenter](https://documenter.juliadocs.org/stable/man/syntax/#@example-block).
+
 ### All supported attributes
 
 * `delay::Float64=0.25`. The amount of delay between line executions (to emulate typing time).
 * `font-size::Int=28`. Used by `agg` when generating the gif.
 * `height::Int`. Heuristically determined by default. Set to an integer to specify the number of lines.
 * `allow_errors::Bool=false`. Whether or not [`cast_document`](@ref) (or [`cast_readme`](@ref)) should fail if exceptions are encountered during execution of the block.
+* `name::String`. Optionally provide a name to allow running multiple examples in the same module, similar to named example blocks in Documenter.
 
 ### Syntax notes
 

src/Asciicast.jl

@@ -143,13 +143,22 @@ end
 
 collect_bytes(cast::Cast) = collect_bytes(cast.write_handle)
 
-function Base.show(io::IO, mime::MIME"text/html", cast::Cast)
-    base64_str = base64encode(collect_bytes(cast))
+Base.show(io::IO, ::MIME"text/html", cast::Cast) = show_html(io, cast)
+function Base.show(io::IO, ::MIME"juliavscode/html", cast::Cast)
+    nodes = Documenter.HTMLWriter.asset_links(".", Asciicast.assets())
+    for node in nodes
+        print(io, node)
+    end
+    show_html(io, cast)
+end
+
+function show_html(io::IO, cast::Cast)
+        base64_str = base64encode(collect_bytes(cast))
     name = uuid4()
     # Note: the extra div with `margin` is me trying to make the asciinema player
     # have a little space around it, so it looks better in documenter pages etc.
     # I don't know what I'm doing; if this is bad, make a PR to improve it!
-    html = HTML("""
+    html = """
     <div style="margin: 20px">
     <div id="$(name)"></div>
     <script>
@@ -159,8 +168,8 @@ function Base.show(io::IO, mime::MIME"text/html", cast::Cast)
     );
     </script>
     </div>
-    """)
-    return show(io, mime, html)
+    """
+    return print(io, html)
 end
 
 """

src/gif.jl

@@ -3,8 +3,8 @@
 
 Given Julia source code as a string, run the code in a REPL mode and save the results as a gif to `output_path`.
 """
-function save_code_gif(output_path, code_string; delay=0.25, font_size=28, height=nothing, allow_errors=false)
-    cast = _cast_str(code_string, delay; height, allow_errors)
+function save_code_gif(output_path, code_string; delay=0.25, font_size=28, height=nothing, allow_errors=false, mod=Module())
+    cast = _cast_str(code_string, delay; height, allow_errors, mod)
     save_gif(output_path, cast::Cast; font_size)
     return output_path
 end
@@ -33,14 +33,14 @@ function get_attribute(attributes, key, default)
         value = tryparse(typeof(default), attributes[idx][2])
         if value === nothing
             @warn "Invalid $(key) $(attributes[idx][2]). Using default value $default."
-            value = 28
+            value = default
         end
     end
     return value
 end
 
 # Pandoc filter to add gifs with the contents of `julia {cast="true"}` code blocks.
-function cast_action(tag, content, format, meta; base_dir, counter)
+function cast_action(tag, content, format, meta; base_dir, counter, module_meta)
     tag == "CodeBlock" || return nothing
     length(content) < 2 && return nothing
     length(content[1]) < 3 && return nothing
@@ -51,16 +51,21 @@ function cast_action(tag, content, format, meta; base_dir, counter)
     font_size = get_attribute(attributes, "font-size", 28)
     delay = get_attribute(attributes, "delay", 0.25)
     height = get_attribute(attributes, "height", 0)
+    name_idx = findfirst(attr -> attr[1] == "name", attributes)
+    example_name = isnothing(name_idx) ? nothing : attributes[name_idx][2]
+
     allow_errors = get_attribute(attributes, "allow_errors", false)
     if height == 0
         height = nothing
     end
     block = content[2]
     counter[] += 1
     c = counter[]
-    name = "output_$(c)[email protected]"
-    rel_path = joinpath("assets", name)
-    save_code_gif(joinpath(base_dir, rel_path), block; delay, font_size, height, allow_errors)
+    rel_path = joinpath("assets", "output_$(c)[email protected]")
+
+    mod = Documenter.get_sandbox_module!(module_meta, "@cast", example_name)
+
+    save_code_gif(joinpath(base_dir, rel_path), block; delay, font_size, height, allow_errors, mod)
     return [
         Pandoc.CodeBlock(content...)
         Pandoc.Para([Pandoc.Image(["", [], []], [], [rel_path, ""])])
@@ -110,7 +115,9 @@ function cast_document(input_path, output_path=input_path; format="gfm+attribute
     base_dir = dirname(output_path)
     mkpath(joinpath(base_dir, "assets"))
     counter = Ref{Int}(0)
-    act = (args...) -> cast_action(args...; base_dir, counter)
+    module_meta = Dict{Symbol, Any}()
+
+    act = (args...) -> cast_action(args...; base_dir, counter, module_meta)
     output = JSON3.write(Pandoc.filter(json, [rm_old_gif, act]))
     open(`$(pandoc()) -f json -t $format --wrap=preserve --resource-path=$(base_dir) -o $output_path`; write=true) do io
         write(io, output)

src/runner.jl

@@ -139,10 +139,25 @@ function Base.showerror(io::IO, c::CastExecutionException)
         """)
 end
 
-function cast_from_string!(code_string::AbstractString, cast::Cast; doc=FakeDoc(), page=FakePage(), ansicolor=true, mod=Module(), multicodeblock=MarkdownAST.CodeBlock[], allow_errors=false, x=nothing)
+function cast_from_string!(code_string::AbstractString, cast::Cast; doc=FakeDoc(), page=FakePage(), ansicolor=true, mod=Module(), multicodeblock=MarkdownAST.CodeBlock[], allow_errors=false, x=nothing, remove_prompt=false)
     linenumbernode = LineNumberNode(0, "REPL") # line unused, set to 0
     @debug "Evaluating @cast:\n$(x.code)"
 
+    # if there are prompts, and we are to remove them, we will use
+    # prompt-pasting semantics, where only lines with the prompt count,
+    # and those prompts are removed.
+    # xref https://github.com/JuliaLang/julia/pull/17599/files
+    if remove_prompt && contains(code_string, r"^julia>"m)
+        code_string_io = IOBuffer()
+        for line in eachsplit(code_string, r"(?>\r\n|\n|\r)")
+            startswith(line, "julia>") || continue
+            n = 6 # length("julia>")
+            n += startswith(" ", line)
+            println(code_string_io, @view(line[(n+1):end]))
+        end
+        code_string = String(take!(code_string_io))
+    end
+
     pb = Documenter.parseblock(code_string, doc, page; keywords=false,
         linenumbernode=linenumbernode)
     n = length(pb)
@@ -240,10 +255,10 @@ macro cast_str(code_string, delay=0, allow_errors=false)
     return _cast_str(code_string, delay; allow_errors)
 end
 
-function _cast_str(code_string, delay=0; height=nothing, allow_errors=false)
+function _cast_str(code_string, delay=0; height=nothing, allow_errors=false, mod=Module())
     n_lines = length(split(code_string))
     height = something(height, min(n_lines * 2, 24)) # try to choose the number of lines more appropriately
     cast = Cast(IOBuffer(), Header(; height); delay=delay)
-    cast_from_string!(code_string, cast; allow_errors)
+    cast_from_string!(code_string, cast; allow_errors, remove_prompt=true, mod)
     return cast
 end

test/runtests.jl

@@ -118,15 +118,34 @@ end
     tmp = mktempdir()
     output = joinpath(tmp, "output.md")
     # Check that we can parse these blocks and produce the gif tags.
-    @test cast_document("test_doc.md", output) == 3
+    n = 6
+    @test cast_document("test_doc.md", output) == n
     str = read(output, String)
-    @test contains(str, "[email protected]")
-    @test contains(str, "output_2_@cast.gif")
-    @test contains(str, "[email protected]")
+    for i in 1:n
+        @test contains(str, "output_$(i)_@cast.gif")
+    end
 end
 
 @testset "markdown errors" begin
     tmp = mktempdir()
     output = joinpath(tmp, "output.md")
     @test_throws CastExecutionException cast_document("bad.md", output)
 end
+
+@testset "`Cast` show methods" begin
+    c = cast"""
+       julia> 1+1
+       2
+
+       julia> 3
+       3
+       """0.25
+    vscode_str = sprint(show, MIME"juliavscode/html"(), c)
+    # Contains the JS and css:
+    @test contains(vscode_str, "asciinema-player.min.js")
+    @test contains(vscode_str, "asciinema-player.min.css")
+    @test contains(vscode_str, "AsciinemaPlayer.create")
+
+    html_str = sprint(show, MIME"text/html"(), c)
+    @test contains(html_str, "AsciinemaPlayer.create")
+end

test/test_doc.md

@@ -9,3 +9,22 @@
 ```julia {cast="true" allow_errors="true"}
 error("oops")
 ```
+
+```julia {cast="true"}
+julia> 1+1
+2
+
+julia> 3
+3
+
+```
+
+```julia {cast="true" name="ex1"}
+x=2
+
+```
+
+```julia {cast="true" name="ex1"}
+y = x+1
+
+```