Package {zuyaml}

zuyaml: Parse and Emit 'YAML' 1.2

Description

Converts between 'YAML' 1.2 (https://yaml.org/spec/1.2.2/) and ordinary R objects using a bundled copy of the 'cyaml' C11 parser and emitter (https://github.com/andrewmd5/cyaml), so there is no system dependency and no runtime dependency beyond R itself. Ambiguous 'YAML' features are handled strictly and predictably: duplicate keys are refused by default, the 'YAML' 1.2 core schema is followed so that yes and no resolve as strings, and integers beyond double precision are preserved rather than silently rounded. A stream of documents and a sequence are different things, and the interface keeps them apart. Input size, nesting depth and the number of values materialised are all bounded, which makes the parser usable on untrusted input.

Author(s)

Maintainer: Pedro Baltazar pedrobtz@gmail.com [copyright holder]

Authors:

• Pedro Baltazar pedrobtz@gmail.com [copyright holder]

Other contributors:

• Andrew Sampson (author of the bundled cyaml library) [contributor, copyright holder]

See Also

Useful links:

• https://github.com/pedrobtz/zuyaml

• https://pedrobtz.github.io/zuyaml/

• Report bugs at https://github.com/pedrobtz/zuyaml/issues

Emit YAML

Description

yaml_emit() converts one R object to a YAML document. yaml_emit_all() converts a list of objects to a YAML stream.

Usage

yaml_emit(
  x,
  indent = 2L,
  width = 80L,
  document_start = FALSE,
  document_end = FALSE
)

yaml_emit_all(
  x,
  indent = 2L,
  width = 80L,
  document_start = FALSE,
  document_end = FALSE
)

Arguments

Details

Emission favours readable YAML over reproducing any particular source formatting. Comments, quoting style and flow-versus-block choices are not preserved; see vignette("zuyaml") for the conversions that do not round trip.

Value

A length-one UTF-8 character vector.

Examples

cat(yaml_emit(list(host = "localhost", port = 8080L)))
cat(yaml_emit_all(list(list(a = 1L), list(b = 2L))))

# Strings that look like other types stay strings.
cat(yaml_emit(list(version = "42")))

Parse YAML

Description

yaml_parse() parses a single YAML document. yaml_parse_all() parses a YAML stream and returns one element per document.

Usage

yaml_parse(
  x,
  simplify = FALSE,
  aliases = c("resolve", "error"),
  big_integers = c("bigint", "double", "error"),
  tags = c("ignore", "error"),
  duplicate_keys = FALSE,
  max_depth = 128L,
  max_size = 64 * 1024^2,
  max_nodes = 1e+06,
  path = NULL
)

yaml_parse_all(
  x,
  simplify = FALSE,
  aliases = c("resolve", "error"),
  big_integers = c("bigint", "double", "error"),
  tags = c("ignore", "error"),
  duplicate_keys = FALSE,
  max_depth = 128L,
  max_size = 64 * 1024^2,
  max_nodes = 1e+06,
  path = NULL
)

Arguments

Details

Both functions parse the input as a stream. yaml_parse() then requires it to contain exactly one document, so trailing documents are never silently discarded:

A zero-document stream is an error rather than NULL, because NULL is the legitimate result of parsing a document whose content is null. Comment-only input is a zero-document stream.

Value

yaml_parse() returns an R object. yaml_parse_all() returns a list with one element per document.

Examples

yaml_parse("host: localhost\nport: 8080\ntls: true\n")

# The core schema, not YAML 1.1: `yes` is a string, and a quoted number
# stays a string.
str(yaml_parse("answer: yes\nversion: \"42\"\n"))

# A stream is not a sequence: one element per document.
yaml_parse_all("---\nfirst\n---\nsecond\n")

Read and write YAML files

Description

yaml_read() reads one YAML document from a file; yaml_read_all() reads a stream. yaml_write() and yaml_write_all() are their counterparts.

Usage

yaml_read(path, ...)

yaml_read_all(path, ...)

yaml_write(x, path, ...)

yaml_write_all(x, path, ...)

Arguments

Details

These work on bytes, not text: files are read and written with readBin() and writeBin(), so nothing depends on the session's locale, and the file path is carried into parse errors to make them locatable.

Value

yaml_read() returns an R object and yaml_read_all() a list of them. The writers return path invisibly.

Examples

path <- tempfile(fileext = ".yml")
yaml_write(list(host = "localhost", port = 8080L), path)
yaml_read(path)
unlink(path)

Integers too large for R's numeric types

Description

A character vector holding the decimal representation of integers that R cannot store exactly: beyond 2^53 a double silently loses precision, and R has no native 64-bit integer scalar.

Usage

zuyaml_bigint(x)

Arguments

Details

yaml_parse() returns one of these when it meets such a value and big_integers = "bigint" (the default). It carries the decimal normalisation of the value, not the source text, so 0x1FFFFFFFFFFFFFFF and its decimal spelling compare equal.

This is a marker for values whose precision must be preserved, not a big-integer arithmetic type: there is no arithmetic. Use as.numeric() to accept the precision loss deliberately, or a package such as bit64 for real 64-bit arithmetic.

Value

zuyaml_bigint() returns a character vector of class "zuyaml_bigint".

Examples

yaml_parse("9223372036854775807")
as.numeric(yaml_parse("9223372036854775807")) # lossy, on purpose

Mappings whose keys are not scalars

Description

YAML mapping keys can be sequences or mappings, which cannot become R names without destroying structure. yaml_parse() represents such a mapping as a zuyaml_map: two parallel lists, keys and values.

Usage

## S3 method for class 'zuyaml_map'
print(x, ...)

Arguments

Details

This is parse-only. The vendored cyaml builder can only attach string keys, so a zuyaml_map cannot be emitted; see vignette("zuyaml") for the full list of conversions that do not round-trip.

Value

print() returns x invisibly.

Examples

yaml_parse("? [one, two]\n: value\n")