R: Nicer message listings and flattening or expansion of objects

listing {pkgutils}

R Documentation

Nicer message listings and flattening or expansion of objects

Description

Create some kind of listing, used, e.g., in (error) messages or warnings. Alternatively, make an object ‘flat’, such as by creating a non-nested list from a list, or expand it after splitting certain components.

Usage

  ## S4 method for signature 'ANY'
flatten(object, ...) 
  ## S4 method for signature 'list'
flatten(object, use.names = TRUE, ...) 

  ## S4 method for signature 'ANY'
listing(x, ...) 
  ## S4 method for signature 'character'
listing(x, header = NULL, footer = NULL,
    prepend = FALSE, style = "list", collapse = if (style == "sentence")
      ""
    else
      "\n", force.numbers = FALSE,
    last.sep = c("and", "both", "comma", "or", "two"), hf.collapse = collapse,
    ...) 
  ## S4 method for signature 'factor'
listing(x, ...) 
  ## S4 method for signature 'list'
listing(x, ...) 
  ## S4 method for signature 'numeric'
listing(x, ...) 

  ## S4 method for signature 'character'
unnest(object, sep, fixed = TRUE, ...,
    stringsAsFactors = FALSE) 
  ## S4 method for signature 'data.frame'
unnest(object, sep, col = names(object),
    fixed = TRUE, ..., stringsAsFactors = FALSE) 
  ## S4 method for signature 'list'
unnest(object, ..., stringsAsFactors = FALSE)

Arguments

`object`	Usually a list. The default method just returns `object` if it is atomic but raises an error otherwise. For `unnest`, a data frame, list or character vector.
`use.names`	Logical scalar passed to `unlist` from the base package.
`x`	For the default method, an object convertible via `unclass` to one of the object classes that have explicit methods. For the character-vector method, in the default style mode, its ‘names’ attribute is used as the first column of the resulting listing; if it is `NULL` or if `force.numbers` is `TRUE`, numbers are inserted. The ‘double’ method is controlled by the ‘digits’ entry of `options` from the base package.
`header`	`NULL` or character vector. Prepended to the result.
`footer`	`NULL` or character vector. Appended to the result.
`prepend`	Logical, numeric or character scalar. The two main uses are: Default mode: The value is prepended to each line except `header` and `footer`. If numeric, the number of spaces. `TRUE` causes tabs to be used, `FALSE` turns prepending off. If in ‘character’ mode, used directly. If `style` is ‘sentence’: In that case, a logical scalar decides about whether names are prepended before joining the vector elements. A character scalar is used as template for `sprintf`, which gets `names(x)` passed as second and `x` as third argument. (This order can be inverted, see next argument.)
`style`	Character scalar. The main options are: ‘table’ or ‘list’: Passed to `formatDL`. ‘sentence’: A comma-separated list is created from `x`, the last separator according to `last.sep`. ‘m4’ or ‘M4’ acronymGNU `m4` macro definitions using double or single quoting, respectively, for the expansions are created. A warning is issued if the macro strings are invalid, which is always the case of `x` has no names; `prepend` is ignored. Otherwise: A template for `sprintf` is assumed taking two additional arguments, first `names(x)` and then `x`. Note that names and values of `x` are exchanged beforehand if `style` is run through `I` from the base package.
`collapse`	Character scalar used to join the resulting vector elements. It is by default also applied for joining `header` and `footer` footer with them (if provided). This can be turned off using hf.collapse. By default this is an empty string for ‘sentence’ style, the newline character otherwise.
`force.numbers`	Logical scalar. Always use numbers instead of the ‘names’ attribute?
`last.sep`	Character scalar indicating what should be used as last separator if `style` is ‘sentence’. ‘both’ means ‘and’ and comma, ‘two’ means ‘or’ and comma.
`hf.collapse`	Character scalar or empty. If distinct from `collapse`, used for separately for joining `header` and `footer` (if provided).
`...`	Optional other arguments passed to `formatDL`. For `unnest`, optional arguments passed to `data.frame`.
`sep`	Character scalar passed as `split` argument to `strsplit`.
`col`	Character vector with the names of the columns to be passed to `strsplit` for splitting.
`fixed`	Logical scalar passed to `strsplit`.
`stringsAsFactors`	Logical scalar passed to `data.frame`.

Value

Character scalar in the case of listing, data frame in the case of unnest.

Examples

## listing()

# default style
x <- structure(letters[1:5], names = LETTERS[1:5])
(y <- listing(x, "Five letters:", "...end here", 1))

## [1] "Five letters:\n A: a\n B: b\n C: c\n D: d\n E: e\n...end here"

stopifnot(length(y) == 1, y ==
  "Five letters:\n A: a\n B: b\n C: c\n D: d\n E: e\n...end here")

# 'sentence' style
(y <- listing(letters[1:3], style = "sentence", last.sep = "both"))

## [1] "a, b, and c"

stopifnot(y == "a, b, and c", length(y) == 1)
(y <- listing(letters[1:3], style = I("sentence"), last.sep = "both"))

## [1] "1, 2, and 3"

stopifnot(y == "1, 2, and 3", length(y) == 1)
(y <- listing(letters[1:3], style = "sentence", prepend = TRUE))

## [1] "1: a, 2: b and 3: c"

stopifnot(y == "1: a, 2: b and 3: c", length(y) == 1)
(y <- listing(letters[1:3], style = I("sentence"), prepend = TRUE))

## [1] "a: 1, b: 2 and c: 3"

stopifnot(y == "a: 1, b: 2 and c: 3", length(y) == 1)
(y <- listing(letters[1:3], style = "sentence", prepend = "%s=>%s"))

## [1] "1=>a, 2=>b and 3=>c"

stopifnot(y == "1=>a, 2=>b and 3=>c", length(y) == 1)
(y <- listing(letters[1:3], style = "sentence", last.sep = "two"))

## [1] "a, b, or c"

stopifnot(y == "a, b, or c", length(y) == 1)

# with explicit sprintf template
(y <- listing(x, style = "%s, %s", collapse = "; ", prepend = "!"))

## [1] "!A, a; !B, b; !C, c; !D, d; !E, e"

stopifnot(y == "!A, a; !B, b; !C, c; !D, d; !E, e", length(y) == 1)
(y <- listing(x, style = I("%s, %s"), collapse = "; ", prepend = "!"))

## [1] "!a, A; !b, B; !c, C; !d, D; !e, E"

stopifnot(y == "!a, A; !b, B; !c, C; !d, D; !e, E", length(y) == 1)

# create m4 macro definitions
(y <- listing(x, style = "m4"))

## [1] "define(`A', ``a'')dnl\ndefine(`B', ``b'')dnl\ndefine(`C', ``c'')dnl\ndefine(`D', ``d'')dnl\ndefine(`E', ``e'')dnl"

stopifnot(grepl("^(define\\([^)]+\\)dnl\n?)+$", y), length(y) == 1)

# other 'x' arguments
stopifnot(listing(x) == listing(as.list(x)))
old.opt <- options(digits = 3)
stopifnot(listing(pi) == "1: 3.14") # controlled by getOption("digits")
options(old.opt)

## flatten()
x <- list(a = list(b = 1:5, c = letters[1:5]), d = LETTERS[1:3],
  e = list(pi))
(y <- flatten(x)) # sublists removed, non-list elements kept

## $a.b
## [1] 1 2 3 4 5
## 
## $a.c
## [1] "a" "b" "c" "d" "e"
## 
## $d
## [1] "A" "B" "C"
## 
## $e
## [1] 3.141593

stopifnot(is.list(y), length(y) == 4, !sapply(y, is.list))
# atomic objects are not modified by default
stopifnot(identical(letters, flatten(letters)))