json_vec: Construct and validate JSON object vectors

In nbenn/infx: OpenBIS API Access to the InfectX Data Repository

Construct and validate JSON object vectors

Description

In order to allow method dispatch on a set of json_class objects without resorting to iterating over the individual set members, vectors of json_class objects are wrapped by a json_vec class. Iterating over objects is in some cases inefficient because the openBIS API can for some functions accept lists of objects. Assembling multiple json_class objects as a list in R however breaks method dispatch, as the type of this object is list instead of the desired json_class sub-class. A json_vec object therefore represents a list of json_class objects of the same sub-class and brings this sub-class to the surface of the compound object.

Usage

json_vec(..., .simplify = FALSE)

as_json_vec(x, ...)

as.json_vec(x, ...)

## S3 method for class 'json_vec'
as_json_vec(x, simplify = FALSE, ...)

## S3 method for class 'json_class'
as_json_vec(x, simplify = FALSE, ...)

## S3 method for class 'list'
as_json_vec(x, recursive = TRUE, force = FALSE,
  simplify = FALSE, ...)

## Default S3 method:
as_json_vec(x, force = FALSE, ...)

## S3 method for class 'json_vec'
as.list(x, recursive = FALSE, ...)

is_json_vec(x)

is.json_vec(x)

has_common_subclass(x)

Arguments

...	Individual json_class objects, or generic compatibility. Might be passed on to as.list() for json_class objects.
x	A single/list of json_class object(s), or other object to coerce
simplify, .simplify	Logical switch indicating whether to simplify json_vec objects of length 1 to json_class objects.
recursive	Recursively apply the function.
force	Suppress error when casting an object to json_vec that cannot be converted.

Details

A json_vec object can be instantiated using the json_vec() constructor which takes a list of json_class objects of the same sub-class. An existing list of json_class objects can be coerced to json_vec using as_json_vec()/as.json_vec() and applying as_list()/as.list() to a json_vec object reverses the action of as_json_vec() by removing all json_vec related class information.

The function is_json_vec() and its alias is.json_vec() can be used to test whether an object is a proper json_vec object. This requires that

• all child elements have to be of the same sub-class

• all child elements are required to be properly formed json_class objects

• the json_vec class attribute has to be in last position

• the remaining class attributes have to be equal to the common sub-class determined for the children.

Testing whether a list structure consists of json_class objects which are of the same sub-class can be done with has_common_subclass(). This always returns TRUE if a json_class object is passed and FALSE if a non-list structure is passed.

Value

Multiple json_class objects of the same sub-type can be represented as S3 objects with type json_vec and the common sub-type as second class attribute.

See Also

Other json object handling functions: has_fields.json_class, json_class, print.json_class

Examples

a <- json_class(field = "a", class = "foo")
b <- json_class(field = "b", class = "foo")

ab <- json_vec(a, b)

print(ab)

identical(ab, as_json_vec(list(a, b)))
# as_json_vec() is idempotent
identical(as_json_vec(list(a, b)),
          as_json_vec(as_json_vec(list(a, b))))

# a json_class object can be turned into a json_vec of length 1
ab_class <- json_class(foo1 = a, foo2 = b, class = "bar")
length(ab_class)
ab_vec <- as_json_vec(ab_class)
length(ab_vec)
# this can be reversed using as_json_class()
identical(ab_class, as_json_class(ab_vec))
# this might not be desirable in all cases; the argument simplify can be
# used to only create json_vec objects of length greater than 1
identical(as_json_vec(list(a), simplify = TRUE),
          a)

# has_common_subclass() will alway return true for json_class objects
has_common_subclass(a)
# list-based objects are tested
has_common_subclass(list(a, b))
# this includes json_vec objects
has_common_subclass(ab)
# each list entry has to be a json_class object
has_common_subclass(list("a", "b"))
# here sub-classes are "foo" and "bar"
has_common_subclass(list(ab_class, a))

is_json_vec(a)
is_json_vec(list(a, b))
is_json_vec(ab)

nbenn/infx documentation built on May 20, 2022, 7:44 a.m.