json_utils: JSON class utilities

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

JSON class utilities

Description

Several utility functions for working with json_class and json_vec objects are provided. This includes has_fields() for checking whether certain fields are available in an object, get_field() to extract values from an object that correspond to a field with a certain name, has_subclass() for testing that an object is of a certain class and get_subclass() to extract this class. Finally, NULL fields can be recursively removed using remove_null(). More information is available in the details section.

Usage

## S3 method for class 'json_class'
has_fields(x, fields, ...)

## S3 method for class 'json_class'
get_field(x, field, ...)

## S3 method for class 'json_class'
has_subclass(x, class, ...)

## S3 method for class 'json_class'
get_subclass(x)

has_fields(x, fields, ...)

## Default S3 method:
has_fields(x, ...)

get_field(x, field, ...)

has_subclass(x, class, ...)

## Default S3 method:
has_subclass(x, ...)

get_subclass(x)

## S3 method for class 'list'
get_subclass(x, ...)

remove_null(x)

## S3 method for class 'json_vec'
has_fields(x, fields, ...)

## S3 method for class 'json_vec'
get_field(x, field, ...)

## S3 method for class 'json_vec'
has_subclass(x, class, ...)

## S3 method for class 'json_vec'
get_subclass(x, ...)

Arguments

x	Object to test.
fields	Character vector of nonzero length, holding the field names for which to check.
...	Generic compatibility.
field	Character vector of length 1, holding the field name to extract.
class	Character vector of nonzero length, holding the class names to test for.

Details

The generic function has_fields() tests whether a single json_class object contains all of the specified fields or whether each json_class object contained in a json_vec object passes this test. If dispatch occurs on an object that is neither of class json_class, nor of class json_vec, has_fields() returns FALSE. A single field can be extracted from a json_class or a json_vec object, using get_field(). Iteration for json_vec objects happens via base::sapply() so that when possible the result is simplified.

In order to test whether a json_class or a json_vec object is of a certain sub-class (can also be a vector of sub-classes), the generic function has_subclass() can be used. Dispatch on objects that do not inherit from either json_class or json_vec will return FALSE. The sub-class of a json_class or a json_vec object can be determined, using get_subclass. This will also work if dispatched on a list of objects if that list object passes has_common_subclass().

The function remove_null() recursively removes all NULL fields from a nested list structure while preserving json_class and json_vec class attributes. This can be useful when fetching an object form openBIS and subsequently using this object for a further query: whenever the object returned by the first API call contains NULL fields, it is safer to remove all of them, as in some cases this might cause an error in the following API requests.

Value

Depending on whether a single or a set of multiple objects is represented, the S3 classes json_class or json_vec are applied respectively.

See Also

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

Examples

obj_1 <- json_class(a = 1, b = 2, class = "foo")
obj_2 <- json_class(a = 2, b = 4, class = "foo")
obj_3 <- json_class(a = 3, c = 6, class = "foo")

# one or more fields can be tested
has_fields(obj_1, "a")
has_fields(obj_1, c("a", "b"))
# dispatch on json_vec objects is possible as well
has_fields(c(obj_1, obj_2), "a")
has_fields(c(obj_1, obj_2), "b")
has_fields(c(obj_1, obj_3), "b")
has_fields(c(obj_1, obj_3), c("a", "b"))
# other types do not pass the test
has_fields(list(obj_1, obj_3), "a")

get_field(obj_1, "a")
get_field(c(obj_1, obj_3), "a")
## Not run: 
  # the requested field must be available in every instance
  get_field(c(obj_1, obj_3), "b")
  # only a single field may be requested
  get_field(c(obj_1, obj_2), c("a", "b"))

## End(Not run)

obj_4 <- json_class(a = 4, c = 8, class = "bar")

# dispatch on json_class
has_subclass(obj_1, "foo")
# dispatch on json_vec
has_subclass(c(obj_1, obj_2), "foo")
# dispatch on other object types always returns FALSE
has_subclass(list(obj_1, obj_2), "foo")

# dispatch on json_class
get_subclass(obj_1)
# dispatch on json_vec
get_subclass(c(obj_1, obj_2))
# dispatch on list is possible if the list passes has_common_subclass()
get_subclass(list(obj_1, obj_2))
## Not run: 
  get_subclass(list(obj_1, obj_4))

## End(Not run)

tmp <- json_class(a = json_class(b = "c", d = NULL, class = "foo"),
                  e = json_class(f = "g", class = "bar"),
                  h = NULL,
                  class = "foobar")
print(tmp, 2)
print(remove_null(tmp), 2)

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