Construct and validate JSON object vectors

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.

json_vec(..., .simplify = FALSE)

as_json_vec(x, ...)

as.json_vec(x, ...)

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

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

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

# S3 method for default
as_json_vec(x, force = FALSE, ...)

# S3 method for 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.

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.

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.

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)
#> ┌─█─foo 
#> │ └─field = a 
#> └─█─foo 
#>   └─field = b 

identical(ab, as_json_vec(list(a, b)))
#> [1] TRUE
# as_json_vec() is idempotent
identical(as_json_vec(list(a, b)),
          as_json_vec(as_json_vec(list(a, b))))
#> [1] TRUE

# 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)
#> [1] 2
ab_vec <- as_json_vec(ab_class)
length(ab_vec)
#> [1] 1
# this can be reversed using as_json_class()
identical(ab_class, as_json_class(ab_vec))
#> [1] TRUE
# 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)
#> [1] TRUE

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

is_json_vec(a)
#> [1] FALSE
is_json_vec(list(a, b))
#> [1] FALSE
is_json_vec(ab)
#> [1] TRUE