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.25The 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.25Asciicast.@cast_str — Macro
@cast_str(code_string, delay=0, allow_errors=false) -> CastCreates a Cast object by executing the code in code_string in a REPL-like environment.
Example
using Asciicast
c = cast"x=1"0.25 # note we set a delay of 0.25 here
Asciicast.save("test.cast", c)To allow exceptions, one needs to invoke the macro manually on a string:
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!")
endThis likewise produces a Cast object. You can provide a filename to have it save the results directly to that file.
Asciicast.record_output — Function
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...)Executes f() while saving all output to a cast whose data is saved to io, or to a file at filepath. The arguments kw... may be any keyword arguments accepted by Header.
The parameters of the cast may be passed here; see Cast for more details.
Returns a Cast object.
Cast objects and a manual example
Asciicast provides a type Cast which can be used for constructing asciicast v2 files (or v3 files, with Header(; version=3)). 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!")
castSuch a Cast can be saved to a .cast file using Asciicast.save. These files are JSON lines files, so they can be read with JSON.parsefile(path; jsonlines=true) from JSON.jl, except for v3 files containing comment lines (lines starting with #). They can also be parsed with Asciicast.parse_cast, which reads both v2 and v3 files, skips comments, and converts v3 event intervals to times since the start. 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.
Asciicast.Cast — Type
Cast(file_or_io=IOBuffer(), header=Header(), start_time=time(); delay=0.0, loop=false)Create a Cast object which represents an asciicast file (see https://docs.asciinema.org/manual/asciicast/v2/ and https://docs.asciinema.org/manual/asciicast/v3/ for the formats). The format is chosen by header.version, which may be 2 (the default) or 3; see Header.
- Set
delayto enforce a constant delay between events. - Set
looptotrueto loop continuously, or to an integer to loop a specified number of times. Only supported in the HTMLshowmethod for asciinema-player (not in the written file format, nor gif support, which currently always loops).
Use write_event! to write an event to the cast.
Asciicast.write_event! — Function
write_event!(cast::Cast, event_type::EventType, event_data::AbstractString)
write_event!(cast::Cast, event::Event)Write an event to cast of type event_type (e.g. OutputEvent or InputEvent; see EventType) with data given by event_data.
For OutputEvent and InputEvent, each not preceded by is written as . The data of other event types (markers, resizes, exits) is written unchanged.
For v3 casts, the interval since the previous event is written, rounded to millisecond precision. The rounding error is carried over to the next event, so the sum of the intervals stays within half a millisecond of the event times.
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.
Asciicast.save — Function
save(output, cast::Cast)Writes the contents of a Cast cast to output.
Asciicast.save_gif — Function
Asciicast.save_code_gif — Function
save_code_gif(output_path, code_string; delay=0.25, font_size=28, height=nothing, allow_errors=false)Given Julia source code as a string, run the code in a REPL mode and save the results as a gif to output_path.