## -----------------------------------------------------------------------------
#| include: false
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4.5,
                      dpi = 96, out.width = "100%")


## -----------------------------------------------------------------------------
library(paintr)


## -----------------------------------------------------------------------------
#| fig-alt: "A numeric vector of six values, 4, 8, 15, 16, 23, and 42, drawn as a column of cells;
#|   under each cell is its positional accessor, [1] through [6], the expression you type to reach
#|   that value."
paint_vector(c(4, 8, 15, 16, 23, 42))


## -----------------------------------------------------------------------------
#| fig-alt: "The same six values, 4, 8, 15, 16, 23, and 42, drawn as a column of cells with the
#|   accessors [1] through [6] beneath them, this time rendered as a ggplot object rather than
#|   base graphics; the picture is identical."
gpaint_vector(c(4, 8, 15, 16, 23, 42))


## -----------------------------------------------------------------------------
#| fig-alt: "A numeric vector of six values drawn as a column of cells holding -3, 5, NA, Inf, 2,
#|   and 1; the missing value shows as NA and the infinite value as Inf, and each cell carries its
#|   positional accessor [1] through [6]."
paint_vector(c(-3, 5, NA, Inf, 2, 1))


## -----------------------------------------------------------------------------
#| fig-alt: "The numbers 1 through 6 drawn as a single horizontal row of cells instead of a column,
#|   with the positional labels [1] through [6] printed outside the row beneath each cell."
paint_vector(1:6, layout = "horizontal", show_indices = "outside")


## -----------------------------------------------------------------------------
#| fig-alt: "A named numeric vector of four values, 12, 19, 3, and 8, drawn as a column of cells;
#|   each cell is labelled with its name as a character accessor, [\"mon\"], [\"tue\"], [\"wed\"],
#|   and [\"thu\"], the expression you type to reach that value."
paint_vector(c(mon = 12, tue = 19, wed = 3, thu = 8))


## -----------------------------------------------------------------------------
#| fig-alt: "The numbers 1 through 15 drawn as a 3 by 5 grid of cells filled column by column, so
#|   the first column reads 1, 2, 3 down and the last reads 13, 14, 15."
paint_matrix(matrix(1:15, nrow = 3))


## -----------------------------------------------------------------------------
#| fig-alt: "The same 3 by 5 grid of the numbers 1 through 15, now with each cell labelled by its
#|   [row, column] subscript, from [1, 1] in the top-left corner to [3, 5] in the bottom-right."
paint_matrix(matrix(1:15, nrow = 3), show_indices = "cell")


## -----------------------------------------------------------------------------
#| fig-height: 5
#| fig-alt: "The first six rows of the mtcars data frame drawn as a table: a header row of bare
#|   column names such as mpg, cyl, and disp, the column type beneath each, and a row-name gutter
#|   down the left labelling each row as an accessor, [\"Mazda RX4\", ] through [\"Valiant\", ];
#|   numbers show three significant figures with any trailing digits in grey."
paint_data_frame(head(mtcars))


## -----------------------------------------------------------------------------
#| fig-alt: "A list of three elements drawn as three side-by-side columns headed $id, $tags, and
#|   $ok; id holds 1, 2, 3, tags holds a and b, and ok holds TRUE, FALSE, NA. The tags column is
#|   one cell shorter, leaving a ragged bottom edge because the elements do not share a length."
paint_list(list(id = 1:3, tags = c("a", "b"), ok = c(TRUE, FALSE, NA)))


## -----------------------------------------------------------------------------
#| fig-height: 3
#| fig-alt: "A small data frame drawn as a table with two columns, x holding 1.5, 2.5, 3.5 and grp
#|   holding a, b, c, each headed by its bare column name with the column type beneath; the elements
#|   share a length, so the table is a clean rectangle."
df <- data.frame(x = c(1.5, 2.5, 3.5), grp = c("a", "b", "c"))
paint_data_frame(df)


## -----------------------------------------------------------------------------
#| fig-height: 3
#| fig-alt: "The same data drawn as a bare list after as.list(): two columns headed $x and $grp
#|   holding the same values 1.5, 2.5, 3.5 and a, b, c. Because the two elements share a length, the
#|   list draws the same clean rectangle a data frame does."
paint_list(as.list(df))


## -----------------------------------------------------------------------------
#| fig-height: 3
#| fig-alt: "The same list after shortening x to two values, 1.5 and 2.5, while grp keeps three, a,
#|   b, c; the elements no longer line up, so the outline is gone and the bottom edge is ragged, the
#|   picture of an object that is no longer a data frame."
broken <- as.list(df)
broken$x <- broken$x[1:2]
paint_list(broken)


## -----------------------------------------------------------------------------
#| fig-alt: "The same equal-length list drawn with gap = 0.5, which pushes the two columns x and grp
#|   apart into separate boxed vectors with clear space between them and no enclosing outline; the
#|   values are unchanged, but the picture now reads as two independent columns rather than one table."
paint_list(as.list(df), gap = 0.5)


## -----------------------------------------------------------------------------
#| fig-height: 3
#| fig-alt: "A list of two elements headed $a and $b, holding 10, 20, 30 and 1.5, 2.5, drawn with
#|   each cell labelled by its list accessor, double brackets to reach the element then a single
#|   bracket to pick the value, so [[2]][2] sits under 2.5 and [[1]][1] under 10."
l <- list(a = c(10, 20, 30), b = c(1.5, 2.5))
paint_list(l, show_indices = "cell")


## -----------------------------------------------------------------------------
#| fig-width: 7.7
#| fig-height: 6.6
#| fig-alt: "The numbers 1 through 24 drawn as a 2 by 3 by 4 array: four side-by-side blocks, each
#|   a 2 by 3 matrix slice sharing one font size and titled , , 1 through , , 4. Every cell is
#|   labelled with its full three-number subscript, from [1, 1, 1] to [2, 3, 4]."
paint_array(array(1:24, dim = c(2, 3, 4)), show_indices = "cell")


## -----------------------------------------------------------------------------
#| fig-height: 4.5
#| fig-alt: "The same 2 by 3 by 4 array, now with slices_per_row = 2, so the four slice blocks are
#|   laid out in a two-by-two grid instead of a single row. The blocks are titled , , 1 through
#|   , , 4 in left-to-right, top-to-bottom reading order, and are larger and easier to read than in
#|   one cramped row."
paint_array(array(1:24, dim = c(2, 3, 4)), slices_per_row = 2)


## -----------------------------------------------------------------------------
paint_size(head(mtcars))