Merge tag 'v1.0.0'

Initial release.

    pillar(x, title = NULL, width = NULL, ...)
    colonnade(x, has_row_id = TRUE, width = NULL, ...)
    squeeze(x, width = NULL, ...)

    new_pillar_shaft_simple(formatted, ..., width = NULL, align = "left", min_width = NULL, na_indent = 0L)
    new_pillar_shaft(x, ..., width, min_width = width, subclass)
    new_ornament(x, width = NULL, align = NULL)
    get_extent(x)
    get_max_extent(x)

    dim_desc(x)
    style_na(x)
    style_neg(x)
    style_num(x, negative, significant = rep_along(x, TRUE))
    style_subtle(x)

    expect_known_display(object, file, ..., width = 80L, crayon = TRUE)

    pillar_shaft(x, ...) # AsIs, Date, POSIXt, character, default, list, logical, numeric
    type_sum(x) # AsIs, Date, POSIXct, data.frame, default, difftime, factor, ordered
    is_vector_s3(x) # Date, POSIXct, data.frame, default, difftime, factor, ordered
    obj_sum(x) # AsIs, POSIXlt, default, list
    extra_cols(x, ...) # squeezed_colonnade

DESCRIPTION

@@ -1,12 +1,12 @@
 Package: pillar
 Title: Coloured Formatting for Columns
-Version: 0.0.0.9000
+Version: 1.0.0
 Authors@R: c(
     person("Kirill", "Müller", , "krlmlr+r@mailbox.org", role = c("aut", "cre")),
     person("Hadley", "Wickham", role = "aut"),
     person("RStudio", role = "cph")
   )
-Description: Provides a `pillar` generic designed for formatting columns
+Description: Provides a 'pillar' generic designed for formatting columns
    of data using the full range of colours provided by modern terminals.
 License: GPL-3
 Encoding: UTF-8
@@ -15,7 +15,7 @@ URL: https://github.com/hadley/pillar
 BugReports: https://github.com/hadley/pillar/issues
 Imports:
     cli,
-    crayon,
+    crayon (>= 1.3.4),
     methods,
     rlang,
     utf8
@@ -24,8 +24,6 @@ Suggests:
     testthat
 Roxygen: list(markdown = TRUE, roclets = c("collate", "namespace", "rd", "pkgapi::api_roclet"))
 RoxygenNote: 6.0.1
-Remotes:
-    r-lib/crayon
 Collate: 
     'compat-purrr.R'
     'dim.R'

NEWS.md

@@ -0,0 +1,37 @@
+## pillar 1.0.0 (2017-11-16)
+
+Initial release.
+
+### User functions
+
+    pillar(x, title = NULL, width = NULL, ...)
+    colonnade(x, has_row_id = TRUE, width = NULL, ...)
+    squeeze(x, width = NULL, ...)
+
+### Functions for implementers of data types
+
+    new_pillar_shaft_simple(formatted, ..., width = NULL, align = "left", min_width = NULL, na_indent = 0L)
+    new_pillar_shaft(x, ..., width, min_width = width, subclass)
+    new_ornament(x, width = NULL, align = NULL)
+    get_extent(x)
+    get_max_extent(x)
+
+### Utilities
+
+    dim_desc(x)
+    style_na(x)
+    style_neg(x)
+    style_num(x, negative, significant = rep_along(x, TRUE))
+    style_subtle(x)
+
+### Testing helper
+
+    expect_known_display(object, file, ..., width = 80L, crayon = TRUE)
+
+### Own S3 methods
+
+    pillar_shaft(x, ...) # AsIs, Date, POSIXt, character, default, list, logical, numeric
+    type_sum(x) # AsIs, Date, POSIXct, data.frame, default, difftime, factor, ordered
+    is_vector_s3(x) # Date, POSIXct, data.frame, default, difftime, factor, ordered
+    obj_sum(x) # AsIs, POSIXlt, default, list
+    extra_cols(x, ...) # squeezed_colonnade

R/extent.R

@@ -5,6 +5,9 @@
 #'
 #' @param x A character vector.
 #' @export
+#' @examples
+#' get_extent(c("abc", "de"))
+#' get_extent("\u904b\u6c23")
 get_extent <- function(x) {
   utf8::utf8_width(crayon::strip_style(x), encode = FALSE)
 }
@@ -14,6 +17,8 @@ get_extent <- function(x) {
 #' character vector, zero for empty vectors.
 #' @export
 #' @rdname get_extent
+#' @examples
+#' get_max_extent(c("abc", "de"))
 get_max_extent <- function(x) {
   max(get_extent(x), 0L, na.rm = TRUE)
 }

R/multi.R

@@ -9,6 +9,18 @@
 #' @param width Default width of the entire output, optional
 #' @param ... Ignored
 #' @export
+#' @examples
+#' colonnade(list(a = 1:3, b = letters[1:3]))
+#'
+#' long_string <- list(paste(letters, collapse = " "))
+#' colonnade(long_string, width = 20)
+#' colonnade(long_string, has_row_id = FALSE, width = 20)
+#'
+#' # The width can also be overridden when calling format() or print():
+#' print(colonnade(long_string), width = 20)
+#'
+#' # If width is larger than getOption("width"), multiple tiers are created:
+#' colonnade(rep(long_string, 4), width = Inf)
 colonnade <- function(x, has_row_id = TRUE, width = NULL, ...) {
   has_title <- is_named(x)
   if (has_title) {
@@ -39,6 +51,8 @@ colonnade <- function(x, has_row_id = TRUE, width = NULL, ...) {
 #'
 #' @rdname colonnade
 #' @export
+#' @examples
+#' squeeze(colonnade(long_string), width = 20)
 squeeze <- function(x, width = NULL, ...) {
   # Hacky shortcut for zero-height corner case
   if (attr(x, "zero_height")) {
@@ -125,9 +139,11 @@ knit_print_squeezed_colonnade_tier <- function(x) {
 #' Formatting a [colonnade] object may lead to some columns being omitted
 #' due to width restrictions. This method returns a character vector that
 #' describes each of the omitted columns.
-#' @param x The result of [format()] on a [colonnade] object
+#' @param x The result of [squeeze()] on a [colonnade] object
 #' @param ... Unused
 #' @export
+#' @examples
+#' extra_cols(squeeze(colonnade(list(a = 1:3, b = 4:6), width = 8)))
 extra_cols <- function(x, ...) {
   UseMethod("extra_cols")
 }
@@ -159,7 +175,7 @@ colonnade_get_width <- function(x, width, rowid_width) {
 
   #' @details
   #' In a first pass, for each pillar it is decided in which tier it is shown,
-  #' if at all, and how much horizontal space it may use (either its minumum
+  #' if at all, and how much horizontal space it may use (either its minimum
   #' or its maximum width). More than one tier may be created if
   #' `width > getOption("width")`, in this case each tier is at most
   #' `getOption("width")` characters wide.
@@ -178,7 +194,7 @@ get_tier_widths <- function(width, ncol, rowid_width, tier_width = getOption("wi
       width
     )
   } else {
-    pos <- seq(0, length.out = ncol, by = tier_width)
+    pos <- seq(0, length.out = ncol + 1L, by = tier_width)
   }
 
   widths <- diff(pos) - rowid_width

R/ornament.R

@@ -12,7 +12,10 @@
 #' @param align Alignment, one of `"left"` or `"right"`
 #'
 #' @export
+#' @examples
+#' new_ornament(c("abc", "de"), align = "right")
 new_ornament <- function(x, width = NULL, align = NULL) {
+  if (is.null(width)) width <- get_max_extent(x)
   ret <- structure(
     x,
     align = align,

R/scientific.R

@@ -1,10 +1,14 @@
-#' Format numbers in scientific notation
-#'
-#' Uses colour, careful alignment, and superscripts to display numbers
-#' in scientific notation.
-#'
-#' @inheritParams format_decimal
-#' @param superscript If `TRUE`, will use superscript numbers in exponent.
+# Format numbers in scientific notation
+#
+# Uses colour, careful alignment, and superscripts to display numbers
+# in scientific notation.
+#
+# @seealso [format_decimal()]
+# @inheritParams format_decimal
+# @param superscript If `TRUE`, will use superscript numbers in exponent.
+# @examples
+# format_scientific(1.5:3.5)
+# format_scientific(1e9)
 format_scientific <- function(x, sigfig = 3, superscript = TRUE) {
   split_decimal(x, sigfig, scientific = TRUE, superscript = superscript)
 }

R/shaft.R

@@ -5,6 +5,7 @@
 #' This is a virtual or abstract class, you must specify the `subclass`
 #' argument.
 #' By convention, this should be a string that starts with `"pillar_shaft_"`.
+#' See `vignette("extending", package = "tibble")` for usage examples.
 #'
 #' @param x An object
 #' @param ... Additional attributes
@@ -35,6 +36,11 @@ new_pillar_shaft <- function(x, ..., width, min_width = width, subclass) {
 #' @param x A vector to format
 #' @param ... Unused, for extensibility.
 #' @export
+#' @examples
+#' pillar_shaft(1:3)
+#' pillar_shaft(1.5:3.5)
+#' pillar_shaft(NA)
+#' pillar_shaft(c(1:3, NA))
 pillar_shaft <- function(x, ...) {
   UseMethod("pillar_shaft")
 }
@@ -77,7 +83,7 @@ pillar_shaft.logical <- function(x, ...) {
 #' @export
 #' @rdname pillar_shaft
 #' @param sigfig Minimum number of significant figures to display. Numbers
-#'   larger than 1 will potentially show more signficiant figures than this
+#'   larger than 1 will potentially show more significant figures than this
 #'   but they will be greyed out.
 pillar_shaft.numeric <- function(x, ..., sigfig = 3) {
   dec <- format_decimal(x, ..., sigfig = sigfig)

R/sigfig.R

@@ -1,19 +1,23 @@
-#' Format numbers in decimal notation
-#'
-#' This formatting system is designed to make it as easy as possible to
-#' compare columns of numbers. Significant digits are coloured black or red
-#' (for positive and negative numbers) and non-significant digits are coloured
-#' in paler gray.
-#'
-#' @return A list with at least the following elements:
-#' * `neg`: negative sign or space, if needed
-#' * `lhs`: whole number
-#' * `dec`: decimal point, if needed
-#' * `rhs`: remainder of number
-#'
-#' @param x A numeric vector
-#' @param sigfig Number of signficiant figures to display.
-#' @param ... Ignored
+# Format numbers in decimal notation
+#
+# This formatting system is designed to make it as easy as possible to
+# compare columns of numbers. Significant digits are coloured black or red
+# (for positive and negative numbers) and non-significant digits are coloured
+# in paler gray.
+#
+# @return A list with at least the following elements:
+# * `neg`: negative sign or space, `TRUE` if needed
+# * `lhs`: whole number
+# * `dec`: decimal point, `TRUE` if needed
+# * `rhs`: remainder of number
+#
+# @param x A numeric vector
+# @param sigfig Number of significant figures to display.
+# @param ... Ignored
+# @seealso [format_scientific()]
+# @examples
+# format_decimal(1.5:3.5)
+# format_decimal(1e9)
 format_decimal <- function(x, sigfig = 3, ...) {
   split_decimal(x, sigfig)
 }
@@ -165,6 +169,16 @@ format_rhs <- function(s) {
 #' @param negative,significant Logical vector the same length as `x` that
 #'   indicate if the values are negative and significant, respectively
 #' @rdname style_subtle
+#' @examples
+#' style_num(
+#'   c("123", "456"),
+#'   negative = c(TRUE, FALSE)
+#' )
+#' style_num(
+#'   c("123", "456"),
+#'   negative = c(TRUE, FALSE),
+#'   significant = c(FALSE, FALSE)
+#' )
 style_num <- function(x, negative, significant = rep_along(x, TRUE)) {
   ifelse(significant, ifelse(negative, style_neg(x), x), style_subtle(x))
 }

R/spark-bar.R

@@ -1,24 +1,24 @@
-#' Draw a sparkline bar graph with unicode block characters
-#'
-#' Rendered using [block elements](https://en.wikipedia.org/wiki/Block_Elements).
-#' In most common fixed width fonts these are rendered wider than regular
-#' characters which means they are not suitable if you need precise alignment.
-#'
-#' @param x A numeric vector between 0 and 1
-#' @param safe Nominally there are 8 block elements from 1/8 height to full
-#'   height (8/8). However, the half-height and full-height blocks appear
-#'   to be rendered inconsistently (possibly due to font substitution).
-#' @examples
-#' \dontrun{
-#' x <- seq(0, 1, length = 6)
-#' spark_bar(x)
-#' spark_bar(sample(x))
-#'
-#' # This might work if you're lucky
-#' spark_bar(seq(0, 1, length = 8), safe = FALSE)
-#'
-#' spark_bar(c(0, NA, 0.5, NA, 1))
-#' }
+# Draw a sparkline bar graph with unicode block characters
+#
+# Rendered using [block elements](https://en.wikipedia.org/wiki/Block_Elements).
+# In most common fixed width fonts these are rendered wider than regular
+# characters which means they are not suitable if you need precise alignment.
+#
+# @param x A numeric vector between 0 and 1
+# @param safe Nominally there are 8 block elements from 1/8 height to full
+#   height (8/8). However, the half-height and full-height blocks appear
+#   to be rendered inconsistently (possibly due to font substitution).
+# @examples
+# \dontrun{
+# x <- seq(0, 1, length = 6)
+# spark_bar(x)
+# spark_bar(sample(x))
+#
+# # This might work if you're lucky
+# spark_bar(seq(0, 1, length = 8), safe = FALSE)
+#
+# spark_bar(c(0, NA, 0.5, NA, 1))
+# }
 spark_bar <- function(x, safe = TRUE) {
   stopifnot(is.numeric(x))
 

R/spark-line.R

@@ -1,11 +1,11 @@
-#' Draw a sparkline line graph with Braille characters.
-#'
-#' @inheritParams spark_bar
-#' @examples
-#' \dontrun{
-#' x <- seq(0, 1, length = 10)
-#' spark_line(x)
-#' }
+# Draw a sparkline line graph with Braille characters.
+#
+# @inheritParams spark_bar
+# @examples
+# \dontrun{
+# x <- seq(0, 1, length = 10)
+# spark_line(x)
+# }
 spark_line <- function(x) {
   stopifnot(is.numeric(x))
 

R/styles.R

@@ -14,6 +14,8 @@ keep_empty <- function(fun) {
 #'
 #' @param x The character vector to style.
 #' @export
+#' @examples
+#' style_subtle("text")
 style_subtle <- keep_empty(function(x) {
   style_grey(0.6, x)
 })
@@ -28,12 +30,16 @@ style_spark_na <- function(x) {
 
 #' @rdname style_subtle
 #' @export
+#' @examples
+#' style_na("NA")
 style_na <- function(x) {
   crayon::bgYellow(crayon::black(x))
 }
 
 #' @rdname style_subtle
 #' @export
+#' @examples
+#' style_neg("123")
 style_neg <- keep_empty(function(x) {
   crayon::red(x)
 })

R/testthat.R

@@ -52,6 +52,6 @@ expect_known_display <- function(object, file, ..., width = 80L, crayon = TRUE)
   if (utils::packageVersion("testthat") <= "1.0.2") {
     testthat::expect_output_file(print(eval_tidy(object)), file, update = TRUE)
   } else {
-    testthat::expect_known_output(eval_tidy(object), file, print = TRUE, width = width)
+    testthat::expect_output_file(print(eval_tidy(object)), file, update = TRUE, width = width)
   }
 }

R/title.R

@@ -3,6 +3,7 @@ pillar_title <- function(title, ...) {
     width <- 0L
   } else {
     width <- get_extent(format_title(title, width = Inf))
+    stopifnot(!is.na(width))
   }
 
   ret <- structure(
@@ -22,7 +23,6 @@ format.pillar_title <- function(x, width, ...) {
   title <- x$title
   if (is.null(title)) return(character())
 
-  desired_width <- get_width(x)
   title <- format_title(title, width)
 
   crayon::bold(title)