In r-lib/asciicast: Create 'Ascii' Screen Casts from R Scripts

Example

This is an example vignette for creating asciinema screen casts. To include a screencast in your document, you need to do two steps. The first is to initialize the asciicast engine:

```r`r ''`
asciicast::init_knitr_engine()
```

asciicast::init_knitr_engine()

After this, for the chunks that you want to display in an asciinema player, use the asciicast engine:

```{asciicast}`r ''`
# This will be an ascii cast
# Let's evaluate some code
head(mtcars)
```

This will produce the following cast:

```{asciicast cache = TRUE}

This will be an ascii cast

Let's evaluate some code

head(mtcars)

## Changing parameters

You can include a DCF header in the asciicast, to set some parameters, e.g.
the height of the widget.

````
```{asciicast}`r ''`
#' Rows: 5

# No much here, so avoid a big widget
1 + 2 + 3 + 4

```{asciicast cache = TRUE}
#' Rows: 5

# Not much here, so avoid a big widget
1 + 2 + 3 + 4
```

## Caching

Recording the asciinema casts might take long, as everything happens
in real time. You can tell knitr to cache the results, as long as the
code of the chunk is unchanged. E.g. the previous chunk with caching
looks like this:

``{asciicast cache = TRUE}r ''`

' Rows: 5

Not much here, so avoid a big widget

1 + 2 + 3 + 4

````

## Casting a script from a file

It is possible to read the R code of a cast from a file, instead of
specifying it in the code chunk. The advantage of this is that it is easier
to use the code in the R scripts for other purposes.

````
```{asciicast code = readLines("../inst/examples/hello.R")}`r ''`

```{asciicast code = readLines("../inst/examples/hello.R"), cache = TRUE}
```

## Using SVG files

Sometimes the asciinema player widget cannot be used, because custom
JavaScript code is forbidden on the page. A common example is README
(and other) markdown files on GitHub. acsiicast can also use animated SVG
images instead of the asciinema player HTML widget. For this set the
`asciicast_knitr_svg` option to `TRUE`, or the `ASCIICAST_KNITR_SVG`
environment variable to `TRUE`. (The former takes precedence if both are
set.)

```r
options(asciicast_knitr_svg = TRUE)
```

``{asciicast}r ''`

' Rows: 3

cli::rule(center = "TITLE", line = "~-", line_col = "blue")

````

```{asciicast, cache = TRUE}
#' Rows: 3
cli::rule(center = "TITLE", line = "~-", line_col = "blue")

You can also use SVG files to show still screenshots, with the state of the screen after running the R code.

```{asciicast}`r ''`
#' Rows: 3
#' At: end
#' Window: FALSE
#' Padding: 10
#' Cursor: FALSE
cli::rule(center = "TITLE", line = "~-", line_col = "blue")
```

```{asciicast, cache = TRUE, fig.with = 15}

' Rows: 3

' Cols: 82

' At: end

' Window: FALSE

' Padding: 10

' Cursor: FALSE

cli::rule(center = "TITLE", line = "~-", line_col = "blue")

## Showing the code

By default asciicast code chunks do not show the code, i.e. the `echo`
kntr option is set to `FALSE` for them. You can override this locally
for a code chunk, or globally, by supplying the `echo` argument to
`asciicast::init_knitr_engine()`.

````
```{asciicast echo = TRUE}`r ''`
#' Rows: 5
#' At: end
# This code will be shown
head(mtcars, 3)

This will show the code above the SVG image. The header is not shown:

```{asciicast, echo = TRUE, cache = TRUE}
#' Rows: 5
#' At: end
# This code will be shown
head(mtcars, 3)
```

## cpp11 integration

Use the `asciicastcpp11` knitr engine to compile cpp11 functions in the
asciicast subprocess:

``{asciicastcpp11}r ''` double mean_cpp(doubles x) { int n = x.size(); double total = 0; for (double value : x) { total += value; } return total / n; }

````

```{asciicastcpp11, echo = FALSE}
double mean_cpp(doubles x) {
  int n = x.size();
  double total = 0;
  for (double value : x) {
     total += value;
  }
  return total / n;
}

Then you can use these functions in regular asciicast chunks:

```{asciicast}`r ''`
mean_cpp(1:10000*1.0)
```

mean_cpp(1:10000*1.0)

r-lib/asciicast documentation built on Jan. 31, 2024, 1:19 p.m.