KVP: Key-Value Pairs

A KvpFrame is a set of associations between character strings (keys) and KvpValues. More...

Data Structures
struct	KvpFrameImpl
	Implements KvpFrame. More...
class	KvpFrameImpl::cstring_comparer
struct	KvpValue
	Implements KvpValue using boost::variant. More...

Typedefs
using	Path = std::vector< std::string >
using	KvpEntry = std::pair< std::vector< std::string >, KvpValue * >
using	KvpFrameImpl::map_type = std::map< const char *, KvpValue *, cstring_comparer >

Functions
bool	KvpFrameImpl::cstring_comparer::operator() (const char *one, const char *two) const
	KvpFrameImpl::KvpFrameImpl (const KvpFrameImpl &) noexcept
	Performs a deep copy.
	KvpFrameImpl::~KvpFrameImpl () noexcept
	Perform a deep delete.
KvpValue *	KvpFrameImpl::set (Path path, KvpValue *newvalue) noexcept
	Set the value with the key in the immediate frame, replacing and returning the old value if it exists or nullptr if it doesn't. More...
KvpValue *	KvpFrameImpl::set_path (Path path, KvpValue *newvalue) noexcept
	Set the value with the key in a subframe following the keys in path, replacing and returning the old value if it exists or nullptr if it doesn't. More...
std::string	KvpFrameImpl::to_string () const noexcept
	Make a string representation of the frame. More...
std::string	KvpFrameImpl::to_string (std::string const &) const noexcept
	Make a string representation of the frame with the specified string prefixed to every item in the frame. More...
std::vector< std::string >	KvpFrameImpl::get_keys () const noexcept
	Report the keys in the immediate frame. More...
KvpValue *	KvpFrameImpl::get_slot (Path keys) noexcept
	Get the value for the tail of the path or nullptr if it doesn't exist. More...
template<typename func_type , typename data_type >
void	KvpFrameImpl::for_each_slot_temp (func_type const &, data_type &) const noexcept
	The function should be of the form: <anything> func (char const *, KvpValue *, data_type &); Do not pass nullptr as the function.
template<typename func_type >
void	KvpFrameImpl::for_each_slot_temp (func_type const &) const noexcept
template<typename func_type , typename data_type >
void	KvpFrameImpl::for_each_slot_prefix (std::string const &prefix, func_type const &, data_type &) const noexcept
	Like for_each_slot, but doesn't traverse nested values. More...
template<typename func_type >
void	KvpFrameImpl::for_each_slot_prefix (std::string const &prefix, func_type const &) const noexcept
std::vector< KvpEntry >	KvpFrameImpl::flatten_kvp (void) const noexcept
	Returns all keys and values of this frame recursively, flattening the frame-containing values.
bool	KvpFrameImpl::empty () const noexcept
	Test for emptiness. More...
map_type::iterator	KvpFrameImpl::begin ()
map_type::iterator	KvpFrameImpl::end ()
int	compare (const KvpValueImpl *, const KvpValue *) noexcept

Friends
int	KvpFrameImpl::compare (const KvpFrameImpl &, const KvpFrameImpl &) noexcept
	If the first KvpFrameImpl has an item that the second does not, 1 is returned. More...
int	compare (const KvpFrameImpl &, const KvpFrameImpl &) noexcept
	If the first KvpFrameImpl has an item that the second does not, 1 is returned. More...
int	compare (const KvpFrameImpl *, const KvpFrameImpl *) noexcept
void	gvalue_from_kvp_value (const KvpValue *kval, GValue *val)
	Convert a kvp_value into a GValue. More...
KvpValue *	kvp_value_from_gvalue (const GValue *gval)
	Convert a gvalue into a kvpvalue. More...
void	qof_book_load_options (QofBook *book, GncOptionLoad load_cb, GncOptionDB *odb)
	Load a GncOptionsDB from KVP data. More...
void	qof_book_save_options (QofBook *book, GncOptionSave save_cb, GncOptionDB *odb, gboolean clear)
	Save a GncOptionsDB back to the book's KVP. More...
void	qof_book_set_option (QofBook *book, KvpValue *value, GSList *path)
	Save a single option value. More...
KvpValue *	qof_book_get_option (QofBook *book, GSList *path)
	Read a single option value. More...
void	qof_book_options_delete (QofBook *book, GSList *path)
	Delete the options. More...
gboolean	qof_instance_has_kvp (QofInstance *inst)
	Report whether a QofInstance has anything stored in KVP. More...
void	qof_instance_set_kvp (QofInstance *, GValue const *value, unsigned count,...)
	Sets a KVP slot to a value from a GValue. More...
void	qof_instance_get_kvp (QofInstance *, GValue *value, unsigned count,...)
	Retrieves the contents of a KVP slot into a provided GValue. More...

Detailed Description

A KvpFrame is a set of associations between character strings (keys) and KvpValues.

A KvpValue is notionally a union with possible types enumerated in the KvpValue::Type enum, and includes, among other things, ints, doubles, strings, guids, lists, time and numeric values. KvpValues may also be other frames, so KVP is inherently hierarchical.

Values are stored in a 'slot' associated with a key. Pointers passed as arguments into set_slot and get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

A 'path' is a sequence of keys that can be followed to a value. Paths are passed as either '/'-delimited strings or as std::vectors of keys. Unlike file system paths, the tokens '.' and '..' have no special meaning.

KVP is an implementation detail whose direct use should be avoided; create an abstraction object in libqof to keep KVP encapsulated here and ensure that KVP modifications are written to the database. Two generic abstractions are provided:

• qof_book_set_option and qof_book_get_option provide similar access for book options.

KVP Values used By GnuCash provides a catolog of KVP entries including what objects they're part of and how they're used.

Purpose

KVP is used to extend the class structure without directly reflecting the extension in the database or xML schema. The backend will directly load and store KVP slots without any checking, which allows older versions of GnuCash to load the database without complaint and without damaging the KVP data that they don't understand.

When a feature is entirely implemented in KVP and doesn't affect the meaning of the books or other features, this isn't a problem, but when it's not true then it should be registered in Features so that older versions of GnuCash will refuse to load the database.

Policy

• Document every KVP slot in src/engine/kvp_doc.txt so that it is presented in KVP Values used By GnuCash.
• Register a feature in Features if the use of the KVP in any way affects the books or business computations.
• Key strings should be all lower case with '-', not spaces, separating words and '/' separating frames. Prefer longer and more descriptive names to abbreviations, and define a global const char[] to the key or path string so that the compiler will catch any typos.
• Make good use of the hierarchical nature of KVP by using frames to group related slots.
• Don't use the KVP API directly outside of libqof, and prefer to use the QofInstance and QofBook functions whenever feasible. If those functions aren't feasible write a class in libqof to abstract the use of KVP.
• Avoid re-using key names in different contexts (e.g. Transactions and Splits) unless the slot is used for the same purpose in both.

Function Documentation

compare()

int compare ( const KvpFrameImpl &  one, const KvpFrameImpl &  two  )

noexcept

If the first KvpFrameImpl has an item that the second does not, 1 is returned.

The first item within the two KvpFrameImpl that is not similar, that comparison is returned. If all the items within the first KvpFrameImpl match items within the second, but the second has more elements, -1 is returned. Otherwise, 0 is returned.

Definition at line 216 of file kvp-frame.cpp.

{
    for (const auto & a : one.m_valuemap)
    {
        auto otherspot = two.m_valuemap.find(a.first);
        if (otherspot == two.m_valuemap.end())
        {
            return 1;
        }
        auto comparison = compare(a.second,otherspot->second);

        if (comparison != 0)
            return comparison;
    }

    if (one.m_valuemap.size() < two.m_valuemap.size())
        return -1;
    return 0;
}

empty()

bool KvpFrameImpl::empty ( ) const

inlinenoexcept

Test for emptiness.

Returns

true if the frame contains nothing.

Definition at line 226 of file kvp-frame.hpp.

{ return m_valuemap.empty(); }

for_each_slot_prefix()

template<typename func_type , typename data_type >

void KvpFrameImpl::for_each_slot_prefix ( std::string const &  prefix, func_type const &  , data_type &    ) const

noexcept

Like for_each_slot, but doesn't traverse nested values.

This will only loop over root-level values whose keys match the specified prefix.

get_keys()

std::vector< std::string > KvpFrameImpl::get_keys ( ) const

noexcept

Report the keys in the immediate frame.

Be sensible about using this, it isn't a very efficient way to iterate.

Returns

std::vector of keys as std::strings.

Definition at line 188 of file kvp-frame.cpp.

{
    std::vector<std::string> ret;
    ret.reserve (m_valuemap.size());
    std::for_each(m_valuemap.begin(), m_valuemap.end(),
        [&ret](const KvpFrameImpl::map_type::value_type &a)
        {
            ret.push_back(a.first);
        }
    );
    return ret;
}

get_slot()

KvpValue * KvpFrameImpl::get_slot ( Path  keys )

noexcept

Get the value for the tail of the path or nullptr if it doesn't exist.

Parameters

path	Path of keys leading to the desired value.

Returns

The value at the key or nullptr.

Definition at line 144 of file kvp-frame.cpp.

{
    auto key = path.back();
    path.pop_back();
    auto target = get_child_frame_or_nullptr (path);
    if (!target)
        return nullptr;
    auto spot = target->m_valuemap.find (key.c_str ());
    if (spot != target->m_valuemap.end ())
        return spot->second;
    return nullptr;
}

gvalue_from_kvp_value()

void gvalue_from_kvp_value	(	const KvpValue *	kval,
		GValue *	val
	)

Convert a kvp_value into a GValue.

Frames aren't converted.

Parameters

kval	A KvpValue.
val	The GValue in which to store the converted value.

Definition at line 237 of file kvp-frame.cpp.

{
    if (kval == NULL) return;
    g_value_unset(val);

    switch (kval->get_type())
    {
        case KvpValue::Type::INT64:
            g_value_init (val, G_TYPE_INT64);
            g_value_set_int64 (val, kval->get<int64_t>());
            break;
        case KvpValue::Type::DOUBLE:
            g_value_init (val, G_TYPE_DOUBLE);
            g_value_set_double (val, kval->get<double>());
            break;
        case KvpValue::Type::NUMERIC:
            g_value_init (val, GNC_TYPE_NUMERIC);
            g_value_set_static_boxed (val, kval->get_ptr<gnc_numeric>());
            break;
        case KvpValue::Type::STRING:
            g_value_init (val, G_TYPE_STRING);
            g_value_set_static_string (val, kval->get<const char*>());
            break;
        case KvpValue::Type::GUID:
            g_value_init (val, GNC_TYPE_GUID);
            g_value_set_static_boxed (val, kval->get<GncGUID*>());
            break;
        case KvpValue::Type::TIME64:
            g_value_init (val, GNC_TYPE_TIME64);
            g_value_set_boxed (val, kval->get_ptr<Time64>());
            break;
        case KvpValue::Type::GDATE:
            g_value_init (val, G_TYPE_DATE);
            g_value_set_static_boxed (val, kval->get_ptr<GDate>());
            break;
        default:
/* No transfer outside of QofInstance-derived classes! */
            PWARN ("Error! Invalid attempt to transfer Kvp type %d", kval->get_type());
            break;
    }
}

kvp_value_from_gvalue()

KvpValue* kvp_value_from_gvalue

(

const GValue *

gval

)

Convert a gvalue into a kvpvalue.

Parameters

gval	A GValue of a type KvpValue can digest.

Returns

KvpValue created from the GValue's contents.

Definition at line 280 of file kvp-frame.cpp.

{
    KvpValue *val = NULL;
    GType type;
    if (gval == NULL)
        return NULL;
    type = G_VALUE_TYPE (gval);
    g_return_val_if_fail (G_VALUE_TYPE (gval), NULL);

    if (type == G_TYPE_INT64)
        val = new KvpValue(g_value_get_int64 (gval));
    else if (type == G_TYPE_DOUBLE)
        val = new KvpValue(g_value_get_double (gval));
    else if (type == G_TYPE_BOOLEAN)
    {
        auto bval = g_value_get_boolean(gval);
        if (bval)
            val = new KvpValue(g_strdup("true"));
    }
    else if (type == GNC_TYPE_NUMERIC)
        val = new KvpValue(*(gnc_numeric*)g_value_get_boxed (gval));
    else if (type == G_TYPE_STRING)
    {
        auto string = g_value_get_string(gval);
        if (string != nullptr)
            val = new KvpValue(g_strdup(string));
    }
    else if (type == GNC_TYPE_GUID)
    {
        auto boxed = g_value_get_boxed(gval);
        if (boxed != nullptr)
            val = new KvpValue(guid_copy(static_cast<GncGUID*>(boxed)));
    }
    else if (type == GNC_TYPE_TIME64)
        val = new KvpValue(*(Time64*)g_value_get_boxed (gval));
    else if (type == G_TYPE_DATE)
        val = new KvpValue(*(GDate*)g_value_get_boxed (gval));
    else
        PWARN ("Error! Don't know how to make a KvpValue from a %s",
               G_VALUE_TYPE_NAME (gval));

    return val;
}

qof_book_get_option()

KvpValue* qof_book_get_option	(	QofBook *	book,
		GSList *	path
	)

Read a single option value.

Used from Scheme, the KvpValue<–>SCM translation is handled by the functions in kvp-scm.c and automated by SWIG. The starting element is set as KVP_OPTION_PATH in qofbookslots.h.

Parameters

book	The book.
path	A GSList of keys which form a path under KVP_OPTION_PATH.

Definition at line 1374 of file qofbook.cpp.

{
    KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
    return root->get_slot(gslist_to_option_path(path));
}

qof_book_load_options()

void qof_book_load_options	(	QofBook *	book,
		GncOptionLoad	load_cb,
		GncOptionDB *	odb
	)

Load a GncOptionsDB from KVP data.

Parameters

book	The book.
load_cb	A callback function that does the loading.
odb	The GncOptionDB to load.

Definition at line 1316 of file qofbook.cpp.

{
    load_cb (odb, book);
}

qof_book_options_delete()

void qof_book_options_delete	(	QofBook *	book,
		GSList *	path
	)

Delete the options.

Primarily used from Scheme to clear out the options before saving a new set.

Parameters

book	The book.
list	A GList of keys which from a path under KVP_OPTION_PATH. If GList is Null, the whole option is deleted.

Definition at line 1381 of file qofbook.cpp.

{
    KvpFrame *root = qof_instance_get_slots(QOF_INSTANCE (book));
    if (path != nullptr)
    {
        Path path_v {str_KVP_OPTION_PATH};
        Path tmp_path;
        for (auto item = path; item != nullptr; item = g_slist_next(item))
            tmp_path.push_back(static_cast<const char*>(item->data));
        delete root->set_path(gslist_to_option_path(path), nullptr);
    }
    else
        delete root->set_path({str_KVP_OPTION_PATH}, nullptr);
}

qof_book_save_options()

void qof_book_save_options	(	QofBook *	book,
		GncOptionSave	save_cb,
		GncOptionDB *	odb,
		gboolean	clear
	)

Save a GncOptionsDB back to the book's KVP.

Parameters

book	The book.
save_cb	A callback function that does the saving.
odb	The GncOptionsDB to save from.
clear	Should the GncOptionsDB be emptied after the save?

Definition at line 1322 of file qofbook.cpp.

{
    /* Wrap this in begin/commit so that it commits only once instead of doing
     * so for every option. Qof_book_set_option will take care of dirtying the
     * book.
     */
    qof_book_begin_edit (book);
    save_cb (odb, book, clear);
    qof_book_commit_edit (book);
}

qof_book_set_option()

void qof_book_set_option	(	QofBook *	book,
		KvpValue *	value,
		GSList *	path
	)

Save a single option value.

Used from Scheme, the KvpValue<–>SCM translation is handled by the functions in kvp-scm.c and automated by SWIG. The starting element is set as KVP_OPTION_PATH in qofbookslots.h.

Parameters

book	The book.
value	The KvpValue to store.
path	A GSList of keys which form a path under KVP_OPTION_PATH.

Definition at line 1361 of file qofbook.cpp.

{
    KvpFrame *root = qof_instance_get_slots (QOF_INSTANCE (book));
    qof_book_begin_edit (book);
    delete root->set_path(gslist_to_option_path(path), value);
    qof_instance_set_dirty (QOF_INSTANCE (book));
    qof_book_commit_edit (book);

    // Also, mark any cached value as invalid
    book->cached_num_field_source_isvalid = FALSE;
}

qof_instance_get_kvp()

void qof_instance_get_kvp	(	QofInstance *	,
		GValue *	value,
		unsigned	count,
			...
	)

Retrieves the contents of a KVP slot into a provided GValue.

Parameters

inst	The QofInstance
key	The path to the slot.
value	A GValue into which to store the value of the slot. It will be set to the correct type.

Definition at line 1099 of file qofinstance.cpp.

{
    std::vector<std::string> path;
    va_list args;
    va_start (args, count);
    for (unsigned i{0}; i < count; ++i)
        path.push_back (va_arg (args, char const *));
    va_end (args);
    gvalue_from_kvp_value (inst->kvp_data->get_slot (path), value);
}

qof_instance_has_kvp()

gboolean qof_instance_has_kvp

(

QofInstance *

inst

)

Report whether a QofInstance has anything stored in KVP.

Parameters

inst	The QofInstance

Returns

TRUE if Kvp isn't empty.

Definition at line 1045 of file qofinstance.cpp.

{
    return (inst->kvp_data != nullptr && !inst->kvp_data->empty());
}

qof_instance_set_kvp()

void qof_instance_set_kvp	(	QofInstance *	,
		GValue const *	value,
		unsigned	count,
			...
	)

Sets a KVP slot to a value from a GValue.

Intermediate container frames will be created if necessary. Commits the change to the QofInstance.

Parameters

inst	The QofInstance on which to set the value.
key	The path to the slot.
value	A GValue containing an item of a type which KvpValue knows how to store.

Definition at line 1056 of file qofinstance.cpp.

{
    std::vector<std::string> path;
    va_list args;
    va_start (args, count);
    for (unsigned i{0}; i < count; ++i)
        path.push_back (va_arg (args, char const *));
    va_end (args);
    delete inst->kvp_data->set_path (path, kvp_value_from_gvalue (value));
}

set()

KvpValue * KvpFrameImpl::set ( Path  path, KvpValue *  newvalue  )

noexcept

Set the value with the key in the immediate frame, replacing and returning the old value if it exists or nullptr if it doesn't.

Takes ownership of new value and releases ownership of the returned old value. Values must be allocated on the free store with operator new.

Parameters

key	The key to insert/replace.
newvalue	The value to set at key.

Returns

The old value if there was one or nullptr. Set the value with the key in a subframe following the keys in path, replacing and returning the old value if it exists or nullptr if it doesn't. Takes ownership of new value and releases ownership of the returned old value. Values must be allocated on the free store with operator new.

Parameters

key	The key to insert/replace.

Exceptions

invalid_argument

if the path doesn't exist.

Parameters

path	The path of subframes leading to the frame in which to insert/replace.
newvalue	The value to set at key.

Returns

The old value if there was one or nullptr.

Definition at line 120 of file kvp-frame.cpp.

{
    if (path.empty())
        return nullptr;
    auto key = path.back ();
    path.pop_back ();
    auto target = get_child_frame_or_nullptr (path);
    if (!target)
        return nullptr;
    return target->set_impl (key, value);
}

set_path()

KvpValue * KvpFrameImpl::set_path ( Path  path, KvpValue *  newvalue  )

noexcept

Set the value with the key in a subframe following the keys in path, replacing and returning the old value if it exists or nullptr if it doesn't.

Creates any missing intermediate frames.Takes ownership of new value and releases ownership of the returned old value. Values must be allocated on the free store with operator new.

Parameters

path	The path of subframes as a std::vector leading to the frame in which to insert/replace.
newvalue	The value to set at key.

Returns

The old value if there was one or nullptr.

Definition at line 133 of file kvp-frame.cpp.

{
    auto key = path.back();
    path.pop_back();
    auto target = get_child_frame_or_create (path);
    if (!target)
        return nullptr;
    return target->set_impl (key, value);
}

to_string() [1/2]

std::string KvpFrameImpl::to_string ( ) const

noexcept

Make a string representation of the frame.

Mostly useful for debugging.

Returns

A std::string representing the frame and all its children.

Definition at line 158 of file kvp-frame.cpp.

{
    return to_string("");
}

to_string() [2/2]

std::string KvpFrameImpl::to_string ( std::string const &  prefix ) const

noexcept

Make a string representation of the frame with the specified string prefixed to every item in the frame.

Returns

A std::string representing all the children of the frame.

Definition at line 164 of file kvp-frame.cpp.

{
    if (!m_valuemap.size())
        return prefix;
    std::ostringstream ret;
    std::for_each(m_valuemap.begin(), m_valuemap.end(),
        [&ret,&prefix](const map_type::value_type &a)
        {
            std::string new_prefix {prefix};
            if (a.first)
            {
                new_prefix += a.first;
                new_prefix += "/";
            }
            if (a.second)
                ret << a.second->to_string(new_prefix) << "\n";
            else
                ret << new_prefix << "(null)\n";
        }
    );
    return ret.str();
}

Friends

compare

int compare ( const KvpFrameImpl &  , const KvpFrameImpl &    )

friend

If the first KvpFrameImpl has an item that the second does not, 1 is returned.

The first item within the two KvpFrameImpl that is not similar, that comparison is returned. If all the items within the first KvpFrameImpl match items within the second, but the second has more elements, -1 is returned. Otherwise, 0 is returned.

Definition at line 216 of file kvp-frame.cpp.

{
    for (const auto & a : one.m_valuemap)
    {
        auto otherspot = two.m_valuemap.find(a.first);
        if (otherspot == two.m_valuemap.end())
        {
            return 1;
        }
        auto comparison = compare(a.second,otherspot->second);

        if (comparison != 0)
            return comparison;
    }

    if (one.m_valuemap.size() < two.m_valuemap.size())
        return -1;
    return 0;
}