to_rjson: Convert R object to and from RJSON specification

Description

RJSON is an object specification that is not unlike JSON, but better adapted to represent R objects (i.e., richer than JSON). It is also easier to parse and evaluate in both R and JavaScript to render the objects in both languages. RJSON objects are used by SciViews to exchange data between R and SciViews GUIs like Komodo/SciViews-K.

Usage

to_rjson(x, attributes = FALSE)
eval_rjson(rjson)
list_to_json(x)
toRjson(x, attributes = FALSE)
evalRjson(rjson)
listToJson(x)

Arguments

Any R object to be converted into RJSON (do not work with objects containing C pointers, environments, promises or expressions, but should work with almost all other R objects).

attributes

If FALSE (by default), a simple object is created by ignoring all attributes. This is usally the suitable option to transfer data to another language, like JavaScript that do not understand R attributes anyway. With attributes = TRUE, the complete information about the object is written, so that the object could be recreated (almost) identical when evaluated in R (but prefer save() and load() to tranfer objects between R sessions!).

rjson

A string containing an object specified in RJSON notation. The specification is evaluated in R... and it can contain also R code. There is no protection provided against execution of bad code. So, you must trust the source!

Value

For to_rjson(), a character string vector with the RJSON specification of the argument.

For eval_rjson(), the corresponding R object in case of a pure RJSON object specification, or the result of evaluating the code, if it contains R commands (for instance, a RJSONp -RJSON with padding- item where a RJSON object is an argument of an R function that is evaluated. In this case, the result of the evaluation is returned).

For list_to_json(), correct (standard) JSON code is generated if x is a list of character strings, or lists.

Details

JSON (JavaScript Object Notation) allows to specify fairly complex objects that can be rather easily exchanged between languages. The notation is also human-readable and not too difficult to edit manually (although not advised, of course). However, JSON has too many limitations to represent R objects (no NA versus NaN, no infinite numbers, no distinction between lists and objects with attributes, or S4 objects, etc.). Moreover, JSON is not very easy to interpret in R and the existing implementations can convert only specified objects (simple objects, lists, data frames, ...).

RJSON slighly modifies and enhances JSON to make it: (1) more complete to represent almost any R object (except objects with pointers, environments, ..., of course), and (2) to make it very easy to parse and evaluate in both R and JavaScript (and probably many other) languages.

With attributes = FALSE, factors and Dates are converted to their usual character representation before encoding the RJSON object. If attributes = TRUE, they are left as numbers and their attributes (class, -and levels for factor-) completely characterize them (i.e., using eval_rjson() and such objects recreate factors or Dates, respectively). However, they are probably less easy to handle in JavaScript of other language where you import the RJSON representation.

Note also that a series of objects are not yet handled correctly. These include: complex numbers, the different date flavors other that Date, functions, expressions, environments, pointers. Do not use such items in objects that you want to convert to RJSON notation.

A last restriction: you cannot have any special characters like linefeed, tabulation, etc. in names. If you want to make your names most compatible with JavaScript, note that the dot is not allowed in syntactically valid names, but the dollar sign is allowed.

Examples

Run this code

# NOT RUN {
# A complex R object
obj <- structure(list(
  a = as.double(c(1:5, 6)),
  LETTERS,
  c = c(c1 = 4.5, c2 = 7.8, c3 = Inf, c4 = -Inf, NA, c6 = NaN),
  c(TRUE, FALSE, NA),
  e = factor(c("a", "b", "a")),
  f = 'this is a "string" with quote',
  g = matrix(rnorm(4), ncol = 2),
  `h&$@` = data.frame(x = 1:3, y = rnorm(3),
    fact = factor(c("b", "a", "b"))),
  i = Sys.Date(),
  j = list(1:5, y = "another item")),
  comment = "My comment",
  anAttrib = 1:10,
  anotherAttrib = list(TRUE, y = 1:4))

# Convert to simplest RJSON, without attributes
rjson1 <- to_rjson(obj)
rjson1
eval_rjson(rjson1)

# More complex RJSON, with attributes
rjson2 <- to_rjson(obj, TRUE)
rjson2
obj2 <- eval_rjson(rjson2)
obj2
# Numbers near equivalence comparison (note: identical(Robj, Robj2) is FALSE)
all.equal(obj, obj2)

rm(obj, obj2, rjson1, rjson2)
# }