- infos = Information about YAJL plugin is in keys below - infos/author = Markus Raab <elektra@libelektra.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](http://lloyd.github.com/yajl/) 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](http://www.json.org). A validator can be found [here](http://jsonlint.com/). Supports every KeySet except when arrays are intermixed with other keys. Has only limited support for metadata. ## Installation See [installation](/doc/INSTALL.md). 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. ```sh # 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](../directoryvalue/) plugin. ```sh # 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](../type/README.md) plugin to map arbitrary values to true and false. ```sh # 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: ```bash kdb mount --resolver=resolver_fm_xhp_x color/settings/openicc-devices.json \ /org/freedesktop/openicc yajl rename cut=org/freedesktop/openicc ``` or: ```bash kdb mount-openicc ``` Then you can copy the `OpenICC_device_config_DB.json` to systemwide or user config, e.g. ```bash 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 ```bash 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: ```bash kdb export system:/org/freedesktop/openicc simpleini > dump.ini ``` or import it: ```bash kdb import system:/org/freedesktop/openicc ini < dump.ini ```