Write/read KVH (key-value hierarchy) file

Description

The format KVH is a lightweight format that can be read/written both by humans and machines. It can be useful in situations where XML or alike formats seem to be an overkill. We provide an ability to manipulate kvh files in R with a good efficiency due to Rcpp use. The content read in kvh file is hierarchically organized in nested lists. The key-values are always returned as character strings. It's up to user to convert them further in useful types (numeric vectors, matrices and so on).

Author(s)

Serguei Sokol.

Maintainer: Serguei Sokol <sokol@insa-toulouse.fr>

References

http://serguei.sokol.free.fr/kvh-format/

Examples

  ## Not run: 
     # prepare object to write to kvh file
     obj=list(x=structure(1:3, names=letters[1:3]), R=R.version)
     # write it
     obj2kvh(obj, "test", "test.kvh") # will create test.kvh file
     # read it back
     l=kvh_read("test.kvh")
     # check a field
     l$test$x # NB. it has a character values put in a list not a numeric vector as it was in obj.
  
## End(Not run)

Escape Special Characters in a key

Description

Escape Tabs, Newlines and Backslashes in a string which will be used as a key in a KVH file.

Usage

esc_kvh_k(s)

Arguments

Details

Escape is done by butting a backslash before a special character.'

Value

escaped string

Escape Special Characters in a value

Description

Escape Newlines and Backslashes in a string which will be used as a key in a KVH file.

Usage

esc_kvh_v(s)

Arguments

Details

Escape is done by butting a backslash before a special character.'

Value

escaped string

Get matrix from kvh file

Description

Given a read connection to kvh file and a vector of keys pointing to a matrix, return this matrix

Usage

kvh_get_matrix(f, v)

Arguments

Details

It is expected that matrix in the kvh file has its upper-leftmost item called "row_col" and it has rownames in the first column and colnames in the first row.

Value

matrix read from kvh

Examples

# write a test matrix
obj2kvh(list(comment="this is a test matrix",  m=diag(2)), "li", "test.kvh")
# read it back
mr=kvh_get_matrix(file("test.kvh"), c("li", "m"))
# clean
unlink("test.kvh")

Parse file in KVH format

Description

Returns a list with names formed form kvh keys and values formed from kvh values If a kvh value has sub-keys, it is returned as a nested list. Otherwise it is returned as a character string.

Usage

kvh_read(
  fn,
  comment_str = "",
  strip_white = FALSE,
  skip_blank = FALSE,
  split_str = "",
  follow_url = FALSE
)

Arguments

Writing/Adding an R Object to KVH File.

Description

Formats an object before writing it in kvh file.

Usage

obj2kvh(obj, objname = NULL, conct = stdout(), indent = 0)

Arguments

Details

Scalar, vector, matrix and list are pre-processed. Other objects are written as an output string of toString() function To add a content to existent file use "a" as open mode fcn=file("m.kvh", "a") obj2kvh() can be used along the code advancing in the calculations. Writing in a subfield of an already started key requires use of appropriate indent value. The file is started with indent=0 and every sub-field increments the indent by 1. If objname is NULL and obj is not a scalar value, the content of obj is written in kvh file without additional indent.

Value

None

Examples

m=matrix(1:6,2,3);
fcn=file("m.kvh", "w");
obj2kvh(m, "m", fcn);
close(fcn);
# clean
unlink("m.kvh")

Get Object Identified by its Keys.

Description

Given a named nested list returned by kvh_read(), get a particular item from it. The object is identified by a series of hierarchical keys, first key corresponds to the first hierarchical level, the second corresponds to the second and so on.

Usage

obj_by_keys(li, keys)

Arguments

Value

an object corresponding to li[[keys[1]][[keys[2]][[...]]. Return NULL if non valid keys.