Serialize Objects to Flat Strings

Serialize R objects into textual sequences of unindented (flat) and identifiable sections. These are called FLAT (1.0) objects.

Usage

flat_serialize(x = list(), tag_sep = ": ", tag_empty = "")

flat_deserialize(string = "", tag_sep = ": ")

flat_tag(x = list(), tag_sep = ": ", tag_empty = "")

flat_format(x = list())

flat_example()

Arguments

x

A list. It can be empty.

tag_sep

A non-empty and non-NA character string. The separator to use when creating tags from names (recursively) extracted from x.

tag_empty

A non-NA character string. The value to use as a substitute for empty names. Positional indices are automatically appended to it to ensure tags are always unique.

string

A non-NA character string. It can be empty. Contents to deserialize.

Value

flat_serialize() returns a character string, possibly empty.

flat_deserialize() returns a named list, possibly empty. Its structure depends on the underlying tags.

flat_tag() returns a character vector, possibly empty.

flat_format() returns an unnamed list having the same shape as x. See Details.

flat_example() returns a character string (a serialized example), invisibly. It is used for its side-effect of printing an illustration of the format (with useful information).

Details

The Flat format (Flat List As Text, or FLAT) is a minimal textual data serialization format optimized for R list objects. Elements are converted to character strings and organized into unindented sections identified by a tag. Call flat_example() for a valid example.

flat_serialize() serializes x into a FLAT object.

flat_deserialize() is the inverse operation: it converts a FLAT object back into a list. The latter has the same shape as the original one, but

• atomic vectors are not reconstituted (they are deserialized as elements of length 1), and

• all elements are also left as character strings.

The convention is to serialize an empty list to an empty character string.

Internal mechanisms

flat_tag() and flat_format() are called internally by flat_serialize(). Aside from debugging purposes, they should not be called outside of the former.

flat_tag() creates tags from names extracted from x and formats them. Tags may not be unique, depending on x's structure and names.

flat_format() recursively formats the elements of x as part of the serialization process. It

• converts NULL to the "NULL" character string,

• converts other elements to character strings using format() and

• replaces empty lists by a <empty list> constant treated as a placeholder.