Package 'yaml12'

Format or write R objects as YAML 1.2.

Description

format_yaml() returns YAML as a character string. write_yaml() writes a YAML stream to a file or stdout and always emits document start (⁠---⁠) markers and a final end (...) marker. Both functions honor a yaml_tag attribute on values (see examples).

Usage

format_yaml(value, multi = FALSE)

write_yaml(value, path = NULL, multi = FALSE)

Arguments

value	Any R object composed of lists, atomic vectors, and scalars.
multi	When TRUE, treat value as a list of YAML documents and encode a stream.
path	Scalar string file path to write YAML to when using write_yaml(). When NULL (the default), write to R's standard output connection.

Value

format_yaml() returns a scalar character string containing YAML. write_yaml() invisibly returns value.

Examples

cat(format_yaml(list(foo = 1, bar = list(TRUE, NA))))

docs <- list("first", "second")
cat(format_yaml(docs, multi = TRUE))

tagged <- structure("1 + 1", yaml_tag = "!expr")
cat(tagged_yaml <- format_yaml(tagged), "\n")

dput(parse_yaml(tagged_yaml))


write_yaml(list(foo = 1, bar = list(2, "baz")))

write_yaml(list("foo", "bar"), multi = TRUE)

tagged <- structure("1 + 1", yaml_tag = "!expr")
write_yaml(tagged)

---

Parse YAML 1.2 document(s) into base R structures.

Description

parse_yaml() takes strings of YAML; read_yaml() reads from a file path.

Usage

parse_yaml(text, multi = FALSE, simplify = TRUE, handlers = NULL)

read_yaml(path, multi = FALSE, simplify = TRUE, handlers = NULL)

Arguments

text	Character vector; elements are concatenated with "\n".
multi	When TRUE, return a list containing all documents in the stream.
simplify	When FALSE, keep YAML sequences as R lists instead of simplifying to atomic vectors.
handlers	Named list of R functions with names corresponding to YAML tags; matching handlers transform tagged values.
path	Scalar string path to a YAML file'.

Details

YAML tags without a corresponding handler are preserved in a yaml_tag attribute. Mappings with keys that are not all simple scalar strings are returned as a named list with a yaml_keys attribute.

Value

When multi = FALSE, returns a parsed R object for the first document. When multi = TRUE, returns a list of parsed documents.

Examples

dput(parse_yaml("foo: [1, 2, 3]"))

# homogeneous sequences simplify by default.
# YAML null maps to NA in otherwise homogeneous sequences.
dput(parse_yaml("foo: [1, 2, 3, null]"))

# mixed type sequence never simplify
dput(parse_yaml("[1, true, cat]"))

# use `simplify=FALSE` to always return sequences as lists.
str(parse_yaml("foo: [1, 2, 3, null]", simplify = FALSE))

# Parse multiple documents when requested.
stream <- "
---
first: 1
---
second: 2
"
str(parse_yaml(stream, multi = TRUE))

# Read from a file; keep sequences as lists.
path <- tempfile(fileext = ".yaml")
writeLines("alpha: [true, null]\nbeta: 3.5", path)
str(read_yaml(path, simplify = FALSE))

---