.TH "md_src_plugins_ni_README" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
md_src_plugins_ni_README \- README 

.IP "\(bu" 2
infos = Information about ni plugin is in keys below
.IP "\(bu" 2
infos/author = Markus Raab elektra@libelektra.org
.IP "\(bu" 2
infos/licence = BSD
.IP "\(bu" 2
infos/needs =
.IP "\(bu" 2
infos/provides = storage
.IP "\(bu" 2
infos/placements = getstorage setstorage
.IP "\(bu" 2
infos/description = Reads and writes the nickel ini format
.PP
.PP
This plugin uses the nickel library in order to read/write \fBmetakeys\fP in the nickel ini format\&. It's purpose is to be used in the \fCspec\fP-namespace or when any metadata should be stored\&.
.PP
For ini files for applications, e\&.g\&. smb\&.conf you should prefer the \fBini plugin\fP\&.
.PP
.SS "Usage"
.PP
To mount a ni plugin you can simply use: 
.PP
.nf
kdb mount file.ini spec/ni ni

.fi
.PP
.PP
The strength and usage of this plugin is that it supports arbitrary meta data and is still human readable\&. E\&.g\&. 
.PP
.nf
[key]
meta=foo

.fi
.PP
.PP
creates the key with meta data key \fCmeta\fP and meta data value \fCfoo\fP: 
.PP
.nf
$ kdb getmeta user/ni/key meta
foo

.fi
.PP
.PP
the meta data for the parent key has following syntax: 
.PP
.nf
[]
meta=foo

.fi
.PP
.PP
Line continuation works by ending the line with \fC\\\\\fP\&.
.PP
Exporting a KeySet to the nickle format: 
.PP
.nf
kdb export spec/ni ni > example.ni

.fi
.PP
.PP
For in-detail explanation of the syntax (nested keys are not supported by the plugin, however) \fCsee nickel-1\&.1\&.0/include/bohr/ni\&.h\fP
.PP
.SS "Limitations"
.PP
.IP "\(bu" 2
Supports most KeySets, but \fCkdb test\fP currently reports some errors (likely because of the UTF-8 handling happening within ni)\&.
.IP "\(bu" 2
Keys have a random order when written out\&.
.IP "\(bu" 2
No comments are preserved, they are simply removed\&.
.IP "\(bu" 2
Parse errors simply result to ignoring (and removing) these parts\&.
.PP
.PP
.SS "Nickel"
.PP
This plugin is based on the Nickel Library written by author: charles@chaoslizard.org
.PP
Nickel (Ni) has its strength in building up a hierarchical recursive Node structure which is perfect for parsing and generating ini files\&. With them arbitrary deep nested hierarchy are possible, but limited in a keyname of a fixed size\&.
.PP
The API of nickel is very suited for elektra, it can use \fCFILE*\fP pointers (using that elektra could open and lock files), the node-hierarchy can be transformed to keysets, but it lacks of many features like comments and types\&.
.PP
The format is more general then the kde-ini format, it can handle their configuration well, when the section names do not exceed the specified length\&. Nesting is only required in the first depth, any deeper is not understood by kde config parser\&.
.PP
The memory footprint is for a 190\&.000 (reduced to 35\&.000 when rewrote first ) line ini file with 1\&.1MB size is 16\&.88 MB\&. The sort order is not stable, even not with the same file rewritten again\&.
.PP
\fBsrc_plugins_ni_bohr\fP libraries 'https://github\&.com/chazomaticus/bohr'