infos = Information about YAJL plugin is in keys below
infos/author = Markus Raab elekt.nosp@m.ra@l.nosp@m.ibele.nosp@m.ktra.nosp@m..org
infos/licence = BSD
infos/provides = storage/json
infos/needs = directoryvalue type
infos/recommends = rebase comment
infos/placements = getstorage setstorage
infos/status = maintained coverage unittest
infos/description = JSON using YAJL

Introduction

This is a plugin reading and writing JSON files using the library yail

The plugin was tested with yajl version 1.0.8-1 from Debian 6 and yajl version 2.0.4-2 from Debian 7.

Examples of files which are used for testing can be found below the folder in "src/plugins/yajl/yajl".

The JSON grammar can be found here.

A validator can be found here.

Supports every KeySet except when arrays are intermixed with other keys. Has only limited support for metadata.

Installation

See installation. The package is called libelektra5-yajl.

Dependencies

libyajl-dev (version 1 and 2 should work)

Types

The type of the data is available via the metadata type:

string: The JSON string type.
boolean: The JSON boolean type (true or false)
double: For JSON numbers.

If no metadata type is given, the type is either:

null on binary null-key
string otherwise

Any other type/value will still be treated as string, but the warning C03200 will be added because of the potential data loss.

Special values

In JSON it is possible to have empty arrays and objects. In Elektra this is mapped using the special names

###empty_array

and

___empty_map

Arrays are mapped to Elektra’s array convention #0, #1,..

Restrictions

Only UTF-8 is supported. Use the iconv plugin if your locale are not UTF-8. When using non-UTF-8 the plugin will be able to write the file, but cannot parse it back again. You will error C03100, invalid bytes in UTF8 string.
Everything is string if not tagged by metakey "type" Only valid JSON types can be used in type, otherwise there are some fall backs to string but warnings are produced.
Arrays will be normalized (to #0, #1, ..)
Comments of various JSON-dialects are discarded.
Mixing of arrays and maps is not detected and leads to corrupted JSON files. Please specify arrays to avoid such situations.
The plugin creates adds an empty root key to the database, even if you did not add this key (see http://issues.libelektra.org/2132).

Because of these potential problems a type checker and comments filter are highly recommended.

Usage

The following example shows you how you can read and write data using this plugin.

# Mount the plugin to the cascading namespace `/tests/yajl`
sudo kdb mount config.json /tests/yajl yajl
 
# Manually add a key-value pair to the database
printf '{ "number": 1337 }' > `kdb file user:/tests/yajl`
 
# Retrieve the new value
kdb get user:/tests/yajl/number
#> 1337
 
# Determine the data type of the value
kdb meta-get user:/tests/yajl/number type
#> double
 
# Add another key-value pair
kdb set user:/tests/yajl/key value
# STDOUT-REGEX: .*Create a new key user:/tests/yajl/key with string "value"
 
# Retrieve the new value
kdb get user:/tests/yajl/key
#> value
 
# Check the format of the configuration file
kdb file user:/tests/yajl/ | xargs cat
#> {
#>     "key": "value",
#>     "number": 1337
#> }
 
# Add an array
kdb set user:/tests/yajl/piggy/#0 straw
kdb set user:/tests/yajl/piggy/#1 sticks
kdb set user:/tests/yajl/piggy/#2 bricks
 
# Retrieve an array key
kdb get user:/tests/yajl/piggy/#2
#> bricks
 
# Check the format of the configuration file
kdb file user:/tests/yajl | xargs cat
#> {
#>     "key": "value",
#>     "number": 1337,
#>     "piggy": [
#>         "straw",
#>         "sticks",
#>         "bricks"
#>     ]
#> }
 
# Undo modifications to the database
kdb rm -r user:/tests/yajl
sudo kdb umount /tests/yajl

Directory Values

The YAJL plugin support values in directory keys via the Directory Value plugin.

# Mount the plugin to `user:/tests/yajl`
sudo kdb mount config.json user:/tests/yajl yajl
 
# Add two directory keys and one leaf key
kdb set user:/tests/yajl/roots 'Things Fall Apart'
kdb set user:/tests/yajl/roots/bloody 'Radical Face'
kdb set user:/tests/yajl/roots/bloody/roots 'No Roots'
 
# Add an array containing two elements
kdb set user:/tests/yajl/now ', Now'
# Elektra arrays require the metakey `array` to the parent.
# Otherwise the keys below `user:/tests/yajl/now` would be
# interpreted as normal key-value pairs.
kdb meta-set user:/tests/yajl/now array ''
kdb set user:/tests/yajl/now/#0 'Neighbors'
kdb set user:/tests/yajl/now/#1 'Threads'
 
kdb ls user:/tests/yajl
#> user:/tests/yajl/now
#> user:/tests/yajl/now/#0
#> user:/tests/yajl/now/#1
#> user:/tests/yajl/roots
#> user:/tests/yajl/roots/bloody
#> user:/tests/yajl/roots/bloody/roots
 
# Retrieve directory values
kdb get user:/tests/yajl/roots
#> Things Fall Apart
kdb get user:/tests/yajl/roots/bloody
#> Radical Face
 
# Retrieve leaf value
kdb get user:/tests/yajl/roots/bloody/roots
#> No Roots
 
# Check array
kdb get user:/tests/yajl/now
#> , Now
kdb meta-get user:/tests/yajl/now array
#> #1
kdb get user:/tests/yajl/now/#0
#> Neighbors
kdb get user:/tests/yajl/now/#1
#> Threads
 
# Undo modifications to the database
kdb rm -r user:/tests/yajl
sudo kdb umount user:/tests/yajl

Booleans

The YAJL plugin maps "1" and "true" to its true bool type, and "0" and "false" to its false bool type. However, it always returns 1 or 0.

You can take advantage of the type plugin to map arbitrary values to true and false.

# Type plugin is automatically mounted since yajl depends on it
sudo kdb mount conf.json user:/tests/yajl yajl
kdb set user:/tests/yajl 1
kdb get user:/tests/yajl
#> 1
kdb meta-set user:/tests/yajl type boolean
kdb set user:/tests/yajl on
kdb get user:/tests/yajl
#> 1
kdb set user:/tests/yajl/subkey disable
kdb meta-set user:/tests/yajl/subkey type boolean
kdb get user:/tests/yajl/subkey
#> 0
 
# Undo modifications to the database
kdb rm -r user:/tests/yajl
sudo kdb umount user:/tests/yajl

OpenICC Device Config

This plugin was specifically designed and tested for the OpenICC_device_config_DB although it is of course not limited to it.

Mount the plugin:

kdb mount --resolver=resolver_fm_xhp_x color/settings/openicc-devices.json \

/org/freedesktop/openicc yajl rename cut=org/freedesktop/openicc

or:

kdb mount-openicc

Then you can copy the OpenICC_device_config_DB.json to systemwide or user config, e.g.

cp src/plugins/yajl/examples/OpenICC_device_config_DB.json /etc/xdg
cp src/plugins/yajl/examples/OpenICC_device_config_DB.json ~/.config
 
kdb ls system:/org/freedesktop/openicc

prints out then all device entries available in the config

kdb get system:/org/freedesktop/openicc/device/camera/0/EXIF_manufacturer

prints out "Glasshuette" with the example config in source

You can export the whole system openicc config to ini with:

kdb export system:/org/freedesktop/openicc simpleini > dump.ini

or import it:

kdb import system:/org/freedesktop/openicc ini < dump.ini