Creating casts

the @cast_str macro

The string macro @cast_str provides a convenient API to construct a Cast object:

using Asciicast
cast"""
    using Pkg
    Pkg.status()
    1 + 1
    """0.25

The Cast objects have a show method defined for HTML, allowing rich display with a local asciinema-player, in Documenter, Pluto, jupyter, VSCode, etc. For convenient use with Documenter in particular, see the @cast syntax in Documenter usage. 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 or saved to a gif using Asciicast.save_gif. See also Markdown usage 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:

using Asciicast
c = cast"""
       julia> 1+1
       3 # note: wrong!

       """0.25

@cast_str(code_string, delay=0, allow_errors=false) -> Cast

using Asciicast

c = cast"x=1"0.25 # note we set a delay of 0.25 here

Asciicast.save("test.cast", c)

using Asciicast
c = @cast_str("error()", 0, true)
Asciicast.save("test.cast", c)

record_output

Here only the outputs can be captured, as record_output is a function, not a macro.

using Asciicast
record_output(; height=10) do
    @info "Hello!"
    println("That was a logging statement, but this is printing.")
    x = 1
    x + 1 # does not print anything-- no output!
    @info "here's `x`" x
    println("Now I'll wait a second")
    sleep(1)
    println("ok, done!")
end

This likewise produces a Cast object. You can provide a filename to have it save the results directly to that file.

record_output(f, filepath::AbstractString, start_time::Float64=time(); delay=0, kw...) -> filepath
record_output(f, io::IO=IOBuffer(), start_time::Float64=time(); delay=0, kw...)

Cast objects and a manual example

Asciicast provides a type Cast which can be used for constructing asciicast v2 files. The most low-level interface is to use manual write_event! calls as follows:

using Asciicast
using Asciicast: Header
cast = Cast(IOBuffer(), Header(; height=5))
write_event!(cast, OutputEvent, "hello\n")
write_event!(cast, OutputEvent, "Let us wait...")
sleep(.5)
write_event!(cast, OutputEvent, "\nDone!")
cast

Such a Cast can be saved to a .cast file using Asciicast.save. These files are JSON lines files, which can be read with JSON3.read with the jsonlines=true keyword argument. They can also be parsed with Asciicast.parse_cast. They can be played in the terminal or uploaded to <asciinema.org> with asciinema, and converted to gifs with agg. Note that Asciicast.jl does not upload or embed any casts, using a local player instead.

See also: Cast files.

Cast(file_or_io=IOBuffer(), header=Header(), start_time=time(); delay=0.0, loop=false)

write_event!(cast::Cast, event_type::EventType, event_data::AbstractString)
write_event!(cast::Cast, event::Event)

Saving outputs

Cast objects (whether created via @cast_str, record_output, or manual construction with Cast and write_event!) can be saved to .cast files with Asciicast.save or to gifs with Asciicast.save_gif. Additionally, Asciicast.save_code_gif provides a shortcut to create a Cast object from code and save it to a gif in one go.

save(output, cast::Cast)

save_gif(output_path, cast::Cast; font_size=28)

save_code_gif(output_path, code_string; delay=0.25, font_size=28, height=nothing, allow_errors=false)