The library is named after its key-value based interface which indicates the great importance of such feature. Indeed, KeyValue's goal is to provide a handy interface for end-users and programmers.
In a key-value based interface, parameters are passed to functions through key-value pairs in contrast to the standard positional interfaces of LibreOffice Calc, Excel, C/C++, etc.
For instance, consider a function which requires stock prices at different dates. Two vectors have to be passed: A vector of dates and a vector of prices. In a positional interface these two vectors would be provided in a specific order, say, first the vector of dates followed by the vector of prices. In contrast, KeyValue allows a label (or key) to be attached to each vector (the value associated to the key) in order to distinguish their meanings. In the example, the keys could be Dates and Prices while the values would be the vectors of dates and prices themselves.
How do spreadsheet users profit from KeyValue interface?
A typical application of KeyValue is making LibreOffice and Excel act as GUIs for complex computational C++ libraries. Normally, the spreadsheets involved are also complex and to improve usability they normally have explaining labels (keys) in cells adjacent to user provided data. KeyValue takes advantage of this fact and implements a parsing scheme that can break down big pieces of data into key-value pairs.
Consider the stock prices example again. On a spreadsheet the vectors of dates and prices would be organized in a two column table whose head row contain Dates and Prices. Users can pass the whole table (including the head) to KeyValue which parses it and recognizes the meaning of each column. This example is deeper explored in the introduction of the user's manual.
How do programmers profit from KeyValue interface?
Because KeyValue is based on keys and values, these are central concepts of the design. Therefore, they are modeled by C++ classes which provide a rich set of functionalities.
Being classes, keys can encapsulate much more information than just the text label. For instance, a key knows the constraints that a value must verify.
In the stock prices example, the key Dates may be implemented in a way that only vectors of dates in strictly increasing order are accepted. In practice this means that a simple call similar to
will either returns a vector of strictly increasing dates or throw an exception informing that the provided dates are invalid. Notice that this avoids code duplication since the programmer does not have to verify validity each time this key is used. Moreover, it reduces the level of noise in the code making it clearer.
Apart from validating input data, keys have another responsibility, namely, mapping names of special values to the values themselves. For instance, considering the first date, say 20/03/2010, of a vector as a start date, then a following entry "1Y" (where "Y" stands for "year") is automatically converted to 20/03/2011. Thanks to the key, the user provides a meaningful text and the core library receives a meaningful date.
Finally a word on values. KeyValue calls the third party library which
returns results that are then forwarded to the front-end. The values
returned by the library can be of several types:
Additionally, they can be vectors or matrices of the previous types.
KeyValue implements a consistent way of receiving data from the library.
Returning functions always return a
Value type and the
programmer do not need to make any conversion because KeyValue takes
care of that. In practice, a simple
will work for a great number of types.