YAML is a human-readable markup language. With it, you can create easily readable documents that can be consumed by a variety of programming languages.
american: - Boston Red Sox - Detroit Tigers - New York Yankees national: - New York Mets - Chicago Cubs - Atlanta BravesData dictionary specification:
- field: ID description: primary identifier type: integer primary key: yes - field: DOB description: date of birth type: date format: yyyy-mm-dd - field: State description: state of residence type: string
install.packages('yaml')
R CMD INSTALL
followed by the name of the file you downloaded (as root if necessary)
git clone git://github.com/viking/r-yaml yaml
R CMD check yaml
to make sure everything is OK.
R CMD INSTALL yaml
(as root if necessary).
yaml
packages has two main functions: yaml.load
and as.yaml
.
yaml.load
function is the YAML parsing function. It accepts a YAML document as a string. Here's a simple example that parses a YAML sequence:
x <- " - 1 - 2 - 3 " yaml.load(x) #=> [1] 1 2 3
1.2345In this case, the scalar "1.2345" is typed as a
float
(or numeric) by the parser. yaml.load
would return a numeric vector of length 1 for this document.
yaml.load("1.2345") #=> [1] 1.2345
- this - is - a - simple - sequence - of - scalarsIf you pass a YAML sequence to
yaml.load
, a couple of things can happen. If all of the elements in the sequence are uniform, yaml.load
will return a vector of that type (i.e. character, integer, real, or logical). If the elements are not uniform, yaml.load
will return a list of the elements. No coercion is done by default.
one: 1 two: 2 three: 3 four: 4Passing a map to
yaml.load
will produce a named list by default. That is, keys are coerced to strings. Since it is possible for the keys of a YAML map to be almost anything (not just strings), you might not want yaml.load
to return a named list. If you want to preserve the data type of keys, you can pass as.named.list = FALSE
to yaml.load
. If as.named.list
is FALSE, yaml.load
will create a keys
attribute for the list it returns instead of coercing the keys into strings.
yaml.load
has the capability to accept custom handler functions. With handlers, you can customize yaml.load
to do almost anything you want. Example of handler usage:
integer.handler <- function(x) { as.integer(x) + 123 } yaml.load("123", handlers = list(int = integer.handler)) #=> [1] 246Handlers are passed to
yaml.load
through the handlers
argument. The handlers
argument must be a named list of functions, where each name is the YAML type that you want to be handled by your function. The functions you provide must accept one argument and must return an R object.
Handler functions will be passed a string or list, depending on the original type of the object. In the example above, integer.handler
was passed the string "123".
Custom sequence handlers will be passed a list of objects. You can then convert the list into whatever you want and return it. Example:
sequence.handler <- function(x) { tmp <- as.numeric(x) tmp / 5 } string <- " - foo - bar - 123 - 4.567 " yaml.load(string, handlers = list(seq = sequence.handler)) #=> [1] NA NA 24.6000 0.9134
keys
attribute (depending on the value of as.named.list
). Example:
string <- " a: - 1 - 2 b: - 3 - 4 " yaml.load(string, handlers = list(map = function(x) { as.data.frame(x) }))Returns:
b a 1 3 1 2 4 2An interesting thing to note in this example is that the
b
column appears before the a
column in the resulting data frame. This is because YAML maps are considered to be hashes, and therefore, order is not preserved. If you want an ordered map, you can use a combination of maps and sequences like so:
- a: - 1 - 2 - b: - 3 - 4
yaml.load_file
does the same thing as yaml.load
, except it reads a file from a connection. For example:
x <- yaml.load_file("Data/document.yml")This function takes the same arguments as
yaml.load
, with the exception that the first argument is a filename or a connection.
as.yaml
is an S3 method used to convert R objects into YAML strings. Example as.yaml
usage:
x <- as.yaml(1:5) cat(x, "\n")Output from above example:
- 1 - 2 - 3 - 4 - 5
as.yaml
arguments:
Name | Description | Default |
---|---|---|
x | the object to convert | |
line.sep | line separator to use ("\n", "\r\n", or "\r") | "\n" |
indent | number of spaces to use for indenting | 2 |
column.major | determines if data.frames are output as column major | TRUE |
column.major
option determines how a data frame is converted into YAML. By default, column.major
is TRUE.
Example of as.yaml
when column.major
is TRUE:
x <- data.frame(a=1:5, b=6:10) y <- as.yaml(x, column.major = TRUE) cat(y, "\n")Outputs:
a: - 1 - 2 - 3 - 4 - 5 b: - 6 - 7 - 8 - 9 - 10Whereas:
x <- data.frame(a=1:5, b=6:10) y <- as.yaml(x, column.major = FALSE) cat(y, "\n")Outputs:
- a: 1 b: 6 - a: 2 b: 7 - a: 3 b: 8 - a: 4 b: 9 - a: 5 b: 10
help(package='yaml')
or example('yaml-package')
for some examples.