|
1 | | -`as.yaml` <- |
2 | | -function(x, line.sep = c('\n', '\r\n', '\r'), indent = 2, omap = FALSE, |
3 | | - column.major = TRUE, unicode = TRUE, precision = getOption('digits'), |
4 | | - indent.mapping.sequence = FALSE, handlers = NULL) { |
5 | | - |
| 1 | +#' Convert an R object into a YAML string |
| 2 | +#' |
| 3 | +#' If you set the `omap` option to TRUE, as.yaml will create ordered maps |
| 4 | +#' (or omaps) instead of normal maps. |
| 5 | +#' |
| 6 | +#' The `column.major` option determines how a data frame is converted. If |
| 7 | +#' TRUE, the data frame is converted into a map of sequences where the name of |
| 8 | +#' each column is a key. If FALSE, the data frame is converted into a sequence |
| 9 | +#' of maps, where each element in the sequence is a row. You'll probably |
| 10 | +#' almost always want to leave this as TRUE (which is the default), because |
| 11 | +#' using [yaml.load()] on the resulting string returns an object |
| 12 | +#' which is much more easily converted into a data frame via |
| 13 | +#' [as.data.frame()]. |
| 14 | +#' |
| 15 | +#' You can specify custom handler functions via the `handlers` argument. |
| 16 | +#' This argument must be a named list of functions, where the names are R |
| 17 | +#' object class names (i.e., 'numeric', 'data.frame', 'list', etc). The |
| 18 | +#' function(s) you provide will be passed one argument (the R object) and can |
| 19 | +#' return any R object. The returned object will be emitted normally. |
| 20 | +#' |
| 21 | +#' Character vectors that have a class of \sQuote{verbatim} will not be quoted |
| 22 | +#' in the output YAML document except when the YAML specification requires it. |
| 23 | +#' This means that you cannot do anything that would result in an invalid YAML |
| 24 | +#' document, but you can emit strings that would otherwise be quoted. This is |
| 25 | +#' useful for changing how logical vectors are emitted (see below for example). |
| 26 | +#' |
| 27 | +#' Character vectors that have an attribute of \sQuote{quoted} will be wrapped |
| 28 | +#' in double quotes (see below for example). |
| 29 | +#' |
| 30 | +#' You can specify YAML tags for R objects by setting the \sQuote{tag} |
| 31 | +#' attribute to a character vector of length 1. If you set a tag for a vector, |
| 32 | +#' the tag will be applied to the YAML sequence as a whole, unless the vector |
| 33 | +#' has only 1 element. If you wish to tag individual elements, you must use a |
| 34 | +#' list of 1-length vectors, each with a tag attribute. Likewise, if you set a |
| 35 | +#' tag for an object that would be emitted as a YAML mapping (like a data frame |
| 36 | +#' or a named list), it will be applied to the mapping as a whole. Tags can be |
| 37 | +#' used in conjunction with YAML deserialization functions like |
| 38 | +#' [yaml.load()] via custom handlers, however, if you set an internal |
| 39 | +#' tag on an incompatible data type (like \dQuote{!seq 1.0}), errors will occur |
| 40 | +#' when you try to deserialize the document. |
| 41 | +#' |
| 42 | +#' @param x The object to be converted. |
| 43 | +#' @param line.sep The line separator character(s) to use. |
| 44 | +#' @param indent The number of spaces to use for indenting. |
| 45 | +#' @param omap Determines whether or not to convert a list to a YAML omap; see |
| 46 | +#' Details. |
| 47 | +#' @param column.major Determines how to convert a data.frame; see Details. |
| 48 | +#' @param unicode Determines whether or not to allow unescaped unicode |
| 49 | +#' characters in output. |
| 50 | +#' @param precision Number of significant digits to use when formatting numeric |
| 51 | +#' values. |
| 52 | +#' @param indent.mapping.sequence Determines whether or not to indent sequences |
| 53 | +#' in mapping context. |
| 54 | +#' @param handlers Named list of custom handler functions for R objects; see |
| 55 | +#' Details. |
| 56 | +#' @return Returns a YAML string which can be loaded using |
| 57 | +#' [yaml.load()] or copied into a file for external use. |
| 58 | +#' @author Jeremy Stephens <jeremy.f.stephens@@vumc.org> |
| 59 | +#' @seealso [yaml.load()] |
| 60 | +#' @references YAML: http://yaml.org |
| 61 | +#' |
| 62 | +#' YAML omap type: http://yaml.org/type/omap.html |
| 63 | +#' @keywords data manip |
| 64 | +#' @export |
| 65 | +#' @examples |
| 66 | +#' |
| 67 | +#' as.yaml(1:10) |
| 68 | +#' as.yaml(list(foo=1:10, bar=c("test1", "test2"))) |
| 69 | +#' as.yaml(list(foo=1:10, bar=c("test1", "test2")), indent=3) |
| 70 | +#' as.yaml(list(foo=1:10, bar=c("test1", "test2")), indent.mapping.sequence=TRUE) |
| 71 | +#' as.yaml(data.frame(a=1:10, b=letters[1:10], c=11:20)) |
| 72 | +#' as.yaml(list(a=1:2, b=3:4), omap=TRUE) |
| 73 | +#' as.yaml("multi\nline\nstring") |
| 74 | +#' as.yaml(function(x) x + 1) |
| 75 | +#' as.yaml(list(foo=list(list(x = 1, y = 2), list(x = 3, y = 4)))) |
| 76 | +#' |
| 77 | +#' # custom handler |
| 78 | +#' as.yaml(Sys.time(), handlers = list( |
| 79 | +#' POSIXct = function(x) format(x, "%Y-%m-%d") |
| 80 | +#' )) |
| 81 | +#' |
| 82 | +#' # custom handler with verbatim output to change how logical vectors are |
| 83 | +#' # emitted |
| 84 | +#' as.yaml(c(TRUE, FALSE), handlers = list( |
| 85 | +#' logical = verbatim_logical)) |
| 86 | +#' |
| 87 | +#' # force quotes around a string |
| 88 | +#' port_def <- "80:80" |
| 89 | +#' attr(port_def, "quoted") <- TRUE |
| 90 | +#' x <- list(ports = list(port_def)) |
| 91 | +#' as.yaml(x) |
| 92 | +#' |
| 93 | +#' # custom tag for scalar |
| 94 | +#' x <- "thing" |
| 95 | +#' attr(x, "tag") <- "!thing" |
| 96 | +#' as.yaml(x) |
| 97 | +#' |
| 98 | +#' # custom tag for sequence |
| 99 | +#' x <- 1:10 |
| 100 | +#' attr(x, "tag") <- "!thing" |
| 101 | +#' as.yaml(x) |
| 102 | +#' |
| 103 | +#' # custom tag for mapping |
| 104 | +#' x <- data.frame(a = letters[1:5], b = letters[6:10]) |
| 105 | +#' attr(x, "tag") <- "!thing" |
| 106 | +#' as.yaml(x) |
| 107 | +#' |
| 108 | +#' # custom tag for each element in a list |
| 109 | +#' x <- list(1, 2, 3) |
| 110 | +#' attr(x[[1]], "tag") <- "!a" |
| 111 | +#' attr(x[[2]], "tag") <- "!b" |
| 112 | +#' attr(x[[3]], "tag") <- "!c" |
| 113 | +#' as.yaml(x) |
| 114 | +#' |
| 115 | +as.yaml <- function( |
| 116 | + x, |
| 117 | + line.sep = c('\n', '\r\n', '\r'), |
| 118 | + indent = 2, |
| 119 | + omap = FALSE, |
| 120 | + column.major = TRUE, |
| 121 | + unicode = TRUE, |
| 122 | + precision = getOption('digits'), |
| 123 | + indent.mapping.sequence = FALSE, |
| 124 | + handlers = NULL |
| 125 | +) { |
6 | 126 | line.sep <- match.arg(line.sep) |
7 | | - res <- .Call(C_serialize_to_yaml, x, line.sep, indent, omap, column.major, |
8 | | - unicode, precision, indent.mapping.sequence, handlers, |
9 | | - PACKAGE="yaml") |
| 127 | + res <- .Call( |
| 128 | + C_serialize_to_yaml, |
| 129 | + x, |
| 130 | + line.sep, |
| 131 | + indent, |
| 132 | + omap, |
| 133 | + column.major, |
| 134 | + unicode, |
| 135 | + precision, |
| 136 | + indent.mapping.sequence, |
| 137 | + handlers, |
| 138 | + PACKAGE = "yaml" |
| 139 | + ) |
10 | 140 | Encoding(res) <- "UTF-8" |
11 | 141 | res |
12 | 142 | } |
0 commit comments