add loop_delay documenter option, expose idle_time_limit, and fix parsing of delay in @cast blocks to not truncate (#39)

* add loop_delay documenter option

* comment

* add tests

* add debug logs

Author: ericphanson

Project.toml

@@ -1,7 +1,7 @@
 name = "Asciicast"
 uuid = "2600d445-abca-43b9-92aa-ce144ac0b05b"
 authors = ["Eric Hanson <[email protected]> and contributors"]
-version = "0.1.2"
+version = "0.1.3"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

docs/src/documenter_usage.md

@@ -196,12 +196,49 @@ println("="^80)
 println("="^80)
 ```
 
+### Loops
+We can use `loop=true` to infinitely loop the cast:
+
+````markdown
+```@cast; delay=0.5, loop=true, hide_inputs=true
+1
+2
+3
+```
+````
+
+```@cast; delay=0.5, loop=true, hide_inputs=true
+1
+2
+3
+```
+
+We can also specify a delay to write at the end of each loop:
+
+````markdown
+```@cast; delay=0.5, loop=true, loop_delay=4.5, hide_inputs=true
+1
+2
+3
+```
+````
+
+```@cast; delay=0.5, loop=true, loop_delay=4.5, hide_inputs=true
+1
+2
+3
+```
+
+Note that currently setting `loop_delay` increases `idle_time_limit` as an implementation detail, meaning that delays of up to `loop_delay` during code execution will be shown.
+
 ### All supported options in `@cast` Documenter blocks
 
 * `hide_inputs::Bool=false`. Whether or not to hide the `@repl`-style inputs before the animated gif.
 * `allow_errors::Bool=false`. Whether or not the Documenter build should fail if exceptions are encountered during execution of the `@cast` block.
 * `delay::Float64=0.25`. The amount of delay between line executions (to emulate typing time).
 * `loop::Union{Int,Bool}=false`. Set to `true` for infinite looping, or an integer to loop a fixed number of times.
+* `loop_delay::Union{Int,Float64}=0`. An amount of time to wait at the end of the cast, usually useful to pause before looping.
+* `idle_time_limit::Union{Int,Float64}=1`. Sets the maximum amount of time to wait between printing.
 * `height::Int`. Heuristically determined by default. Set to an integer to specify the number of lines.
 * `width::Int`. Set to `80` by default. Set to an integer to specify the number of columns.
 

src/runner.jl

@@ -3,6 +3,20 @@ abstract type CastBlocks <: ExpanderPipeline end
 Selectors.order(::Type{CastBlocks}) = 9.1 # just after REPL blocks
 Selectors.matcher(::Type{CastBlocks}, node, page, doc) = iscode(node, r"^@cast")
 
+function parse_float_int(name, kwargs)
+    matched = match(Regex("\\b$(name)\\s*=\\s*((?:[0-9]*[.])?[0-9]+)"), kwargs)
+    if matched !== nothing
+        return parse(Float64, matched[1])
+    else
+        # match integer delay
+        matched = match(Regex("\\b$(name)\\s*=\\s*([0-9]+)"), kwargs)
+        if matched !== nothing
+            return convert(Float64, parse(Int, matched[1]))
+        end
+    end
+    return nothing
+end
+
 # We can't just run the actual REPLBlocks, because then we have no timing information.
 # Thus, we need to basically reproduce their implementation, while saving timing info.
 
@@ -34,6 +48,8 @@ function Selectors.runner(::Type{CastBlocks}, node, page, doc)
     height = nothing
     width = nothing
     loop = false
+    loop_delay = 0
+    idle_time_limit = 1
     if kwargs !== nothing
         # ansicolor
         matched = match(r"\bansicolor\s*=\s*(true|false)\b", kwargs)
@@ -80,30 +96,23 @@ function Selectors.runner(::Type{CastBlocks}, node, page, doc)
             end
         end
 
-        # delay
-        # match integer delay
-        matched = match(r"\bdelay\s*=\s*([0-9]+)", kwargs)
-        if matched !== nothing
-            delay = convert(Float64, parse(Int, matched[1]))
-        else
-            # match float delay
-            matched = match(r"\bdelay\s*=\s*((?:[0-9]*[.])?[0-9]+)", kwargs)
-            if matched !== nothing
-                delay = parse(Float64, matched[1])
-            end
-        end
-    end
+        delay = something(parse_float_int("delay", kwargs), delay)
 
-    multicodeblock = MarkdownAST.CodeBlock[]
+        idle_time_limit = something(parse_float_int("idle_time_limit", kwargs), idle_time_limit)
 
+        loop_delay = something(parse_float_int("loop_delay", kwargs), loop_delay)
+    end
+    idle_time_limit = max(idle_time_limit, loop_delay)
+    @debug "`@cast` block delays" delay loop_delay idle_time_limit
+    multicodeblock = MarkdownAST.CodeBlock[]
     n_lines = length(split(x.code))
 
     # If `height` isn't provided, we guess the number of lines:
     height = something(height, min(n_lines * 2, 24))
     width = something(width, 80)
-    cast = Cast(IOBuffer(), Header(; height, width, idle_time_limit=1); delay, loop)
+    cast = Cast(IOBuffer(), Header(; height, width, idle_time_limit); delay, loop)
 
-    cast_from_string!(x.code, cast; doc, page, ansicolor, mod, multicodeblock, allow_errors, x)
+    cast_from_string!(x.code, cast; doc, page, ansicolor, mod, multicodeblock, allow_errors, x, loop_delay)
 
     raw_html = sprint(show, MIME"text/html"(), cast)
 
@@ -149,7 +158,7 @@ function Base.showerror(io::IO, c::CastExecutionException)
         """)
 end
 
-function cast_from_string!(code_string::AbstractString, cast::Cast; doc=FakeDoc(), page=FakePage(), ansicolor=true, mod=get_module(), multicodeblock=MarkdownAST.CodeBlock[], allow_errors=false, x=nothing, remove_prompt=false)
+function cast_from_string!(code_string::AbstractString, cast::Cast; doc=FakeDoc(), page=FakePage(), ansicolor=true, mod=get_module(), multicodeblock=MarkdownAST.CodeBlock[], allow_errors=false, x=nothing, remove_prompt=false, loop_delay=0.0)
     linenumbernode = LineNumberNode(0, "REPL") # line unused, set to 0
     @debug "Evaluating @cast:\n$(x.code)"
 
@@ -235,6 +244,12 @@ function cast_from_string!(code_string::AbstractString, cast::Cast; doc=FakeDoc(
         end
         push!(multicodeblock, MarkdownAST.CodeBlock("documenter-ansi", rstrip(outstr)))
     end
+    if loop_delay > 0 # if there's delay, write an empty output
+        # note: for some reason, it doesn't seem to matter if we write an empty string or actual output here- for me
+        # it doesn't display either way
+        event = Event(time() + loop_delay - cast.start_time, OutputEvent, "")
+        write_event!(cast, event)
+    end
 end
 
 

test/runtests.jl

@@ -150,6 +150,17 @@ end
         c = cast"""include("test_file.jl")"""
         @test c isa Cast
     end
+
+    @testset "Float-int parsing" begin
+        @test Asciicast.parse_float_int("delay", "delay=0.5, loop=true, loop_delay=4.5, hide_inputs=true") == 0.5
+        @test Asciicast.parse_float_int("delay", "delay=1, loop=true, loop_delay=4.5, hide_inputs=true") == 1.0
+        @test Asciicast.parse_float_int("delay", "delay=1.0, loop=true, loop_delay=4.5, hide_inputs=true") == 1.0
+        @test Asciicast.parse_float_int("delay", "delay=1.5, loop=true, loop_delay=4.5, hide_inputs=true") == 1.5
+        @test Asciicast.parse_float_int("delay",
+            "width=100, height=50, delay=0.1, loop=true, loop_delay=5") == 0.1
+        @test Asciicast.parse_float_int("loop_delay",
+            "width=100, height=50, delay=0.1, loop=true, loop_delay=5") == 5
+    end
 end