Package 'asciicast'

Description

You can set asciicast parameters in the header of the recorded R script. The header is in DCF format (see read.dcf()), but all lines are prefixed with ⁠#'⁠ comments.

Details

The DCF header may specify arbitrary parameters. We list here the parameters that are interpreted by the asciicast functions.

Recording parameters:

• allow_errors: Whether to cast errors properly. If this is set to TRUE, then asciicast overwrites the "error" option. Only change this if you know what you are doing.

• cols: Width of the terminal, in number of characters.

• empty_wait: How long to wait for empty lines in the script file, in seconds.

• end_wait: Delay at the very end, in seconds.

• env: Environment variables to include in the case JSON file. Defaults to list(TERM = "xterm-256color", SHELL = "/bin/zsh").

• idle_time_limit: Time limit for the cast not printing anything, in seconds. By default there is no limit.

• record_env: Environment variables to set for the R subprocess.

• rows: Height of the terminal, in number of characters.

• start_wait: Delay at the beginning, in seconds.

• timeout: Idle timeout, in seconds If the R subprocess running the recording does not answer within this limit, it is killed and the recording stops. Update this for slow running code, that produces no output as it runs.

• timestamp: Time stamp of the recording, defaults to Sys.time(), this is included in the cast JSON file.

• title: Title of the cast, this is included in the cast JSON file.

• typing_speed: Average typing speed, per keypress, in seconds.

Asciinema player parameters:

• author: Author, displayed in the titlebar in fullscreen mode.

• author_img_url: URL of the author's image, displayed in the titlebar in fullscreen mode.

• author_url: URL of the author's homepage/profile. Author name (author above) is linked to this URL.

• autoplay: Whether to start playing the cast automatically.

• cols: Width of the terminal, in number of characters.

• font_size: Size of terminal font. Possible values: small, medium, big, any css font-size value (e.g. 15px).

• idle_time_limit: Time limit for the cast not printing anything, in seconds. By default there is no limit.

• loop: Whether to loop the playback.

• poster_frame: Which frame to use (in seconds) as the preview picture.

• poster_text: Text to use as the preview picture. Defaults to the title.

• rows: Height of the terminal, in number of characters.

• speed: Whether to play slower or faster. 1 is normal speed.

• start_at: Where to start the playback from, in seconds.

• theme: Theme to use, currently it has to be a string, one of "asciinema", "tango", "solarized-dark", "solarized-light", "monokai". The first one is the default.

• title: Title of the cast.

Parameters for SVG files:

• at: Timestamp of single frame to render, in seconds.

• cols: Width of the terminal, in number of characters.

• cursor: Enable cursor rendering.

• end_at: Upper range of timeline to render in seconds.

• padding: Distance between text and image bounds.

• padding_x: Distance between text and image bounds on x axis.

• padding_y: Distance between text and image bounds on y axis.

• rows: Height of the terminal, in number of characters.

• start_at: Where to start the playback from, in seconds.

• window: Render with window decorations.

• theme: Theme to use, currently it has to be a string referring to a build-in theme, or a named list of theme properties, see default_theme(). The built-in themes are "asciinema", "tango", "solarized-dark", "solarized-light", "seti", "monokai", "github-light", "github-dark", "pkgdown" ,"readme". "readme" is a special theme the switches between light and dark mode automatically in README.md files on GitHub.

See Also

Other asciicast functions: asciicast_start_process(), read_cast(), record(), write_json()

Description

Default options to set in the asciicast subprocess.

Usage

asciicast_options()

Value

Named list.

Examples

asciicast_options()

Description

This is for expert use, if you want to run multiple recordings in the same process.

Usage

asciicast_start_process(
  startup = NULL,
  timeout = 10,
  record_env = NULL,
  interactive = TRUE,
  locales = get_locales(),
  options = NULL,
  show_output = FALSE
)

Arguments

Value

The R process, a processx::process object.

See Also

Other asciicast functions: asciicast-package, read_cast(), record(), write_json()

Examples

# Use the same R process to record multiple casts
process <- asciicast_start_process()
script1 <- "a <- runif(10)\n"
script2 <- "a\n"
cast1 <- record(textConnection(script1), process = process)
cast2 <- record(textConnection(script2), process = process)
cast1
cast2

Description

You can use this widget in Rmd files or Shiny applications, the same way as other HTML widgets.

Usage

asciinema_player(
  cast,
  start_at = 0,
  rows = NULL,
  cols = NULL,
  autoplay = NULL,
  loop = NULL,
  speed = NULL,
  title = NULL,
  author = NULL,
  author_url = NULL,
  author_img_url = NULL,
  poster_text = NULL,
  poster_frame = NULL,
  font_size = NULL,
  theme = NULL,
  idle_time_limit = NULL,
  html_height = NULL,
  html_width = NULL,
  element_id = NULL
)

Arguments

Examples

cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast"))
asciinema_player(cast)

Description

The new cast will inherit its options (screen size, etc.) from the first cast in the argument list. The options of the rest of the casts are ignored.

Usage

clear_screen()

pause(secs)

merge_casts(...)

Arguments

Details

pause() inserts a pause of the specified seconds between the casts.

clear_screen() clears the screen between two casts.

Value

An asciicast object.

Examples

# merge two casts, with a pause, and clear screen between them
cast1 <- read_cast(system.file("examples", "hello.cast", package = "asciicast"))
cast2 <- read_cast(system.file("examples", "dplyr.cast", package = "asciicast"))
cast <- merge_casts(cast1, pause(3), clear_screen(), cast2)
play(cast)

Description

Currently only used for write_svg()

Usage

default_theme()

Value

A named list.

See Also

Other SVG functions: play(), write_svg()

Examples

cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast"))
svg_file <- tempfile(fileext = ".svg")
mytheme <- modifyList(default_theme(), list(cursor = c(255, 0, 0)))
write_svg(cast, svg_file, theme = mytheme)

Description

This function is very similar to testthat::expect_snapshot_output(), but it runs the code in an asciciast subprocess, using record_output().

Usage

expect_snapshot_r_process(
  ...,
  interactive = TRUE,
  echo = TRUE,
  startup = NULL,
  transform = NULL,
  variant = NULL
)

Arguments

Details

THe Code part of the snapshot is always the same, but the Output part shows the code, assuming echo = TRUE (the default).

Examples

Sys.getpid()
testthat::local_edition(3)
expect_snapshot_r_process(Sys.getpid())

Description

Helper function to query locales as a named character vector.

Usage

get_locales()

Value

Named character vector with entries:

• LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC and LC_TIME.

Description

Call this function in your Rmd file to enable creating asciinema casts from code chunks.

Usage

init_knitr_engine(
  echo = FALSE,
  same_process = TRUE,
  timeout = 10,
  startup = NULL,
  record_env = NULL,
  echo_input = TRUE,
  interactive = TRUE
)

Arguments

Details

Limitations

• purl() or setting the purl = TRUE chunk option, does not work properly, in that knitr thinks that asciicast chunks are not R code, so they will appear as comments. If you know how to fix this, please contact us.

Examples

Call this function from an Rmd chunk and then you can use the asciicast knitr engine:

```{r setup, include = FALSE}
asciicast::init_knitr_engine()
```

```{asciicast, cache = TRUE}`
#' Rows: 10
# This is an asciicast example
loadedNamespaces()
```

Description

Download the zip package, unzip it, and copy the executable to a system directory in which asciicast can look for the PhantomJS executable.

Usage

install_phantomjs(
  version = "2.1.1",
  baseURL = "https://github.com/wch/webshot/releases/download/v0.3.1/",
  quiet = FALSE
)

Arguments

Details

This function was designed primarily to help Windows users since it is cumbersome to modify the PATH variable. Mac OS X users may install PhantomJS via Homebrew. If you download the package from the PhantomJS website instead, please make sure the executable can be found via the PATH variable.

On Windows, the directory specified by the environment variable APPDATA is used to store ‘phantomjs.exe’. On OS X, the directory ‘~/Library/Application Support’ is used. On other platforms (such as Linux), the directory ‘~/bin’ is used. If these directories are not writable, the directory ‘PhantomJS’ under the installation directory of the asciicast package will be tried. If this directory still fails, you will have to install PhantomJS by yourself.

Value

NULL (the executable is written to a system directory).

Description

Uses write_svg() to create an SVG image for a cast, in a temporary file, and then previews a minimal HTML file with the SVG image, in the default browser.

Usage

play(cast, ...)

Arguments

Value

The path of the temporary SVG file, invisibly.

See Also

Other SVG functions: default_theme(), write_svg()

Examples

cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast"))
play(cast)

Description

Import an asciicast from an asciicast JSON file

Usage

read_cast(json)

Arguments

Value

asciicast object.

See Also

Other asciicast functions: asciicast-package, asciicast_start_process(), record(), write_json()

Examples

c1 <- read_cast("https://asciinema.org/a/uHQwIVpiZvu0Ioio8KYx6Uwlj.cast?dl=1")
play(c1)

c2 <- read_cast(258660)
play(c2)


c3 <- read_cast(system.file("examples", "hello.cast", package = "asciicast"))
play(c3)

Description

Record an asciinema screencast

Usage

record(
  script,
  typing_speed = NULL,
  empty_wait = NULL,
  cols = NULL,
  rows = NULL,
  title = NULL,
  timestamp = NULL,
  env = NULL,
  idle_time_limit = NULL,
  timeout = NULL,
  start_wait = NULL,
  end_wait = NULL,
  record_env = NULL,
  startup = NULL,
  echo = TRUE,
  speed = NULL,
  process = NULL,
  interactive = TRUE,
  locales = get_locales(),
  options = asciicast_options(),
  incomplete_error = NULL,
  show_output = FALSE
)

Arguments

Value

An asciicast object, write this to file with write_json().

See Also

Other asciicast functions: asciicast-package, asciicast_start_process(), read_cast(), write_json()

Examples

script <- system.file("examples", "hello.R", package = "asciicast")
cast <- record(script)
play(cast)

Description

This function uses record() internally, but instead of creating an ascii cast, it just returns the output of the code in a character vector.

Usage

record_output(
  script,
  echo = FALSE,
  prompt = echo,
  stdout = TRUE,
  stderr = TRUE,
  ...
)

Arguments

Value

Character vector of output (plus input if echo, plus prompt if prompt), as it would appear on a terminal.

See record() for additional options.

Description

Export ascii screencast to animated GIF file

Usage

write_gif(
  cast,
  path,
  show = NULL,
  cols = NULL,
  rows = NULL,
  theme = NULL,
  scale = 2,
  speed = 1,
  max_colors = 256,
  loop = 0,
  end_wait = 10,
  optimize = TRUE
)

Arguments

Value

path, invisibly.

Description

Create a HTML snapshot of an asciicast

Usage

write_html(
  cast,
  path,
  at = "end",
  omit_last_line = NULL,
  prefix = "",
  theme = NULL,
  details = FALSE,
  summary = "See output"
)

Arguments

Description

The file uses the asciinema file format, version 2: https://github.com/asciinema/asciinema/blob/master/doc/asciicast-v2.md.

Usage

write_json(cast, path)

Arguments

See Also

Other asciicast functions: asciicast-package, asciicast_start_process(), read_cast(), record()

Examples

script <- system.file("examples", "hello.R", package = "asciicast")
cast <- record(script)
json <- tempfile(fileext = ".json")
write_json(cast, json)

Description

Create animated SVG from an asciicast

Usage

write_svg(
  cast,
  path,
  window = NULL,
  start_at = NULL,
  end_at = NULL,
  at = NULL,
  cursor = NULL,
  rows = NULL,
  cols = NULL,
  padding = NULL,
  padding_x = NULL,
  padding_y = NULL,
  omit_last_line = NULL,
  theme = NULL,
  show = NULL
)

Arguments

See Also

Other SVG functions: default_theme(), play()

Examples

cast <- read_cast(system.file("examples", "hello.cast", package = "asciicast"))
svg_file <- tempfile(fileext = ".svg")
write_svg(cast, svg_file)