listing: Nicer message listings and flattening or expansion of objects
In pkgutils: Utilities for Creating R Packages

Description Usage Arguments Value See Also Examples

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.

  ## 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)

`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`.

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

base::message base::warning base::stop base::formatDL

Other coding-functions: L, LL, assert, case, check, collect, contains, map_names, map_values, must, set, sql,

## listing()

# default style
x <- structure(letters[1:5], names = LETTERS[1:5])
(y <- listing(x, "Five letters:", "...end here", 1))
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"))
stopifnot(y == "a, b, and c", length(y) == 1)
(y <- listing(letters[1:3], style = I("sentence"), last.sep = "both"))
stopifnot(y == "1, 2, and 3", length(y) == 1)
(y <- listing(letters[1:3], style = "sentence", prepend = TRUE))
stopifnot(y == "1: a, 2: b and 3: c", length(y) == 1)
(y <- listing(letters[1:3], style = I("sentence"), prepend = TRUE))
stopifnot(y == "a: 1, b: 2 and c: 3", length(y) == 1)
(y <- listing(letters[1:3], style = "sentence", prepend = "%s=>%s"))
stopifnot(y == "1=>a, 2=>b and 3=>c", length(y) == 1)
(y <- listing(letters[1:3], style = "sentence", last.sep = "two"))
stopifnot(y == "a, b, or c", length(y) == 1)

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

# create m4 macro definitions
(y <- listing(x, style = "m4"))
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
stopifnot(is.list(y), length(y) == 4, !sapply(y, is.list))
# atomic objects are not modified by default
stopifnot(identical(letters, flatten(letters)))