Serialize Objects

Convert Translator objects, Text objects, and Location objects to a YAML object, or vice-versa.

Convert translations contained by a Translator object to a custom textual representation (a FLAT object), or vive-versa.

Usage

serialize(x, ...)

serialize_translations(tr = translator(), lang = "")

deserialize(string = "")

deserialize_translations(string = "", tr = NULL)

export_translations(tr = translator(), lang = "")

export(x, ...)

# S3 method for class 'Translator'
export(x, ...)

# S3 method for class 'Text'
export(x, id = uuid(), set_translations = FALSE, ...)

# S3 method for class 'Location'
export(x, id = uuid(), ...)

# S3 method for class 'ExportedTranslator'
assert(x, throw_error = TRUE, ...)

# S3 method for class 'ExportedText'
assert(x, throw_error = TRUE, ...)

# S3 method for class 'ExportedLocation'
assert(x, throw_error = TRUE, ...)

# S3 method for class 'ExportedTranslations'
assert(x, throw_error = TRUE, ...)

import(x, ...)

# S3 method for class 'ExportedTranslator'
import(x, ...)

# S3 method for class 'ExportedText'
import(x, ...)

# S3 method for class 'ExportedLocation'
import(x, ...)

# S3 method for class 'ExportedTranslations'
import(x, tr = NULL, ...)

# Default S3 method
import(x, ...)

format_errors(errors = character(), id = uuid(), throw_error = TRUE)

Arguments

x

Any R object.

...

Further arguments passed to, or from other methods.

tr

A Translator object.

This argument is NULL by default for deserialize_translations() and import.ExportedTranslations(). If a Translator object is passed to these functions, they will import translations and further register them (as long as they correspond to an existing source text).

lang

A non-empty and non-NA character string. The underlying language.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1 to maximize portability and cross-compatibility.

string

A non-empty and non-NA character string. Contents to deserialize.

id

A non-empty and non-NA character string. A unique identifier for the underlying object. It is used for validation purposes.

set_translations

A non-NA logical value. Should translations be included in the resulting ExportedText object? If FALSE, field Translations is set equal to NULL.

throw_error

A non-NA logical value. Should an error be thrown? If so, stops() is called. Otherwise, error messages are returned as a character vector (possibly empty).

errors

A non-empty character vector of non-NA values. Error message(s) describing why object(s) are invalid.

Value

See other sections for further information.

serialize(), and serialize_translations() return a character string.

export() returns a named list of S3 class

ExportedTranslator if x is a Translator object,
ExportedText if x is a Text object, or
ExportedLocation if x is a Location object.

export_translations() returns an ExportedTranslations object.

deserialize() and import() return

a Translator object if x is a valid ExportedTranslator object,
a Text object if x is a valid ExportedText object, or
a Location object if x a valid ExportedLocation object.

deserialize_translations() and import.ExportedTranslations() return an ExportedTranslations object. They further register imported translations if a Translator object is passed to tr.

Translations must correspond to an existing source text (a registered Text object). Otherwise, they are skipped.
The value passed to tr is updated by reference and is not returned.

import.default() is used for its side-effect of throwing an error for unsupported objects.

assert.ExportedTranslator(), assert.ExportedText(), assert.ExportedLocation(), and assert.ExportedTranslations() return a character vector, possibly empty. If throw_error is TRUE, an error is thrown if an object is invalid.

format_errors() returns a character vector, and outputs its contents as an error if throw_error is TRUE.

Details

The information contained within a Translator object is split by default. Unless set_translations is TRUE, translations are serialized independently from other fields. This is useful when creating Translator files and translations files.

While serialize() and serialize_translations() are distinct, they share a common design and perform the same thing, at least conceptually. The same is true for deserialize() and deserialize_translations(). These 4 functions are those that should be used in almost all circumstances.

Serialization

The data serialization process performed by serialize() and serialize_translations() is internally broken down into 2 steps: objects are first exported before being serialized.

export() and export_translations() are preserializing mechanisms that convert objects into transient objects that ease the conversion process. They are never returned to the user: serialize(), and serialize_translations() immediately transform them into character strings.

serialize() returns a YAML object.

serialize_translations() returns a FLAT object.

Deserialization

The data deserialization process performed by deserialize() and deserialize_translations() is internally broken down into 3 steps: objects are first deserialized, then validated and finally, imported.

deserialize() and deserialize_translations() are raw deserializer mechanisms: string is converted into an R named list that is presumed to be an exported object. deserialize() relies on YAML tags to infer the class of each object.

The contents of the transient objects is thoroughly checked with an assert() method (based on the underlying presumed class). Valid objects are imported back into an appropriate R object with import().

Custom fields and comments added by users to serialized objects are ignored.

Formatting errors

assert() methods accumulate error messages before returning, or throwing them. format_errors() is a helper function that eases this process. It exists to avoid repeting code in each method. There is no reason to call it outside of assert() methods.

Note

Dividing the serialization and deserialization processes into multiple steps helps keeping the underlying functions short, and easier to test.

Exported Objects

An exported object is a named list of S3 class ExportedTranslator, ExportedText, ExportedLocation, or ExportedTranslations and always having a tag attribute whose value is equal to the super-class of x.

There are four main differences between an object and its exported counterpart.

Field names are slightly more verbose.
Source text is treated independently from translations.
Unset fields are set equal to NULL (a ~ in YAML).
Each object has an Identifier used to locate errors.

The correspondance between objects is self-explanatory.

See class Translator for more information on class ExportedTranslator.
See class Text for more information on class ExportedText.
See class Location for more information on class ExportedLocation.

You may also explore provided examples below.

The `ExportedTranslations` Class

ExportedTranslations objects are created from a Translator object with export_translations(). Their purpose is to restructure translations by language. They are different from other exported objects because there is no corresponding Translations class.

An ExportedTranslations object is a named list of S3 class ExportedTranslations containing the following elements.

Identifier

The unique identifier of argument tr. See Translator$id for more information.

Language Code

The value of argument lang.

Language

The translation's language. See Translator$native_languages for more information.

Source Language

The source text's language. See Translator$source_langs for more information.

Translations

A named list containing further named lists. Each sublist contains two values:

Source Text: A non-empty and non-NA character string.
Translation: A non-empty and non-NA character string.

See Text$translations for more information.

Unavailable translations are automatically replaced by a placeholder that depends on whether they are exported or imported.