ariadne
/
pkgconf
3
6
Fork 4
Code Issues 6 Pull Requests 2 Projects Releases 2 Wiki Activity

libpkgconf: document tuple module

pull/100/head
William Pitcock 2016-12-11 17:28:27 -06:00
parent 4967c85d49
commit e6c49153ff
3 changed files with 214 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
doc/libpkgconf-tuple.rst Normal file
View File

@ -0,0 +1,91 @@
libpkgconf `tuple` module
=========================
The `tuple` module provides key-value mappings backed by a linked list. The key-value
mapping is mainly used for variable substitution when parsing .pc files.
There are two sets of mappings: a ``pkgconf_pkg_t`` specific mapping, and a `global` mapping.
The `tuple` module provides convenience wrappers for managing the `global` mapping, which is
attached to a given client object.
.. c:function:: void pkgconf_tuple_add_global(pkgconf_client_t *client, const char *key, const char *value)
Defines a global variable, replacing the previous declaration if one was set.
:param pkgconf_client_t* client: The pkgconf client object to modify.
:param char* key: The key for the mapping (variable name).
:param char* value: The value for the mapped entry.
:return: nothing
.. c:function:: void pkgconf_tuple_find_global(const pkgconf_client_t *client, const char *key)
Looks up a global variable.
:param pkgconf_client_t* client: The pkgconf client object to access.
:param char* key: The key or variable name to look up.
:return: the contents of the variable or ``NULL``
:rtype: char *
.. c:function:: void pkgconf_tuple_free_global(pkgconf_client_t *client)
Delete all global variables associated with a pkgconf client object.
:param pkgconf_client_t* client: The pkgconf client object to modify.
:return: nothing
.. c:function:: void pkgconf_tuple_define_global(pkgconf_client_t *client, const char *kv)
Parse and define a global variable.
:param pkgconf_client_t* client: The pkgconf client object to modify.
:param char* kv: The variable in the form of ``key=value``.
:return: nothing
.. c:function:: pkgconf_tuple_t *pkgconf_tuple_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key, const char *value, bool parse)
Optionally parse and then define a variable.
:param pkgconf_client_t* client: The pkgconf client object to access.
:param pkgconf_list_t* list: The variable list to add the new variable to.
:param char* key: The name of the variable being added.
:param char* value: The value of the variable being added.
:param bool parse: Whether or not to parse the value for variable substitution.
:return: a variable object
:rtype: pkgconf_tuple_t *
.. c:function:: char *pkgconf_tuple_find(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key)
Look up a variable in a variable list.
:param pkgconf_client_t* client: The pkgconf client object to access.
:param pkgconf_list_t* list: The variable list to search.
:param char* key: The variable name to search for.
:return: the value of the variable or ``NULL``
:rtype: char *
.. c:function:: char *pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value)
Parse an expression for variable substitution.
:param pkgconf_client_t* client: The pkgconf client object to access.
:param pkgconf_list_t* list: The variable list to search for variables (along side the global variable list).
:param char* value: The ``key=value`` string to parse.
:return: the variable data with any variables substituted
:rtype: char *
.. c:function:: void pkgconf_tuple_free_entry(pkgconf_tuple_t *tuple, pkgconf_list_t *list)
Deletes a variable object, removing it from any variable lists and releasing any memory associated
with it.
:param pkgconf_tuple_t* tuple: The variable object to release.
:param pkgconf_list_t* list: The variable list the variable object is attached to.
:return: nothing
.. c:function:: void pkgconf_tuple_free(pkgconf_list_t *list)
Deletes a variable list and any variables attached to it.
:param pkgconf_list_t* list: The variable list to delete.
:return: nothing

1
doc/libpkgconf.rst
View File

@ -11,3 +11,4 @@ libpkgconf - an API for managing `pkg-config` modules
libpkgconf-dependency
libpkgconf-path
libpkgconf-queue
libpkgconf-tuple

122
libpkgconf/tuple.c
View File

@ -15,12 +15,50 @@
#include <libpkgconf/libpkgconf.h>
/*
* !doc
*
* libpkgconf `tuple` module
* =========================
*
* The `tuple` module provides key-value mappings backed by a linked list. The key-value
* mapping is mainly used for variable substitution when parsing .pc files.
*
* There are two sets of mappings: a ``pkgconf_pkg_t`` specific mapping, and a `global` mapping.
* The `tuple` module provides convenience wrappers for managing the `global` mapping, which is
* attached to a given client object.
*/
/*
* !doc
*
* .. c:function:: void pkgconf_tuple_add_global(pkgconf_client_t *client, const char *key, const char *value)
*
* Defines a global variable, replacing the previous declaration if one was set.
*
* :param pkgconf_client_t* client: The pkgconf client object to modify.
* :param char* key: The key for the mapping (variable name).
* :param char* value: The value for the mapped entry.
* :return: nothing
*/
void
pkgconf_tuple_add_global(pkgconf_client_t *client, const char *key, const char *value)
{
pkgconf_tuple_add(client, &client->global_vars, key, value, false);
}
/*
* !doc
*
* .. c:function:: void pkgconf_tuple_find_global(const pkgconf_client_t *client, const char *key)
*
* Looks up a global variable.
*
* :param pkgconf_client_t* client: The pkgconf client object to access.
* :param char* key: The key or variable name to look up.
* :return: the contents of the variable or ``NULL``
* :rtype: char *
*/
char *
pkgconf_tuple_find_global(const pkgconf_client_t *client, const char *key)
{
@ -37,12 +75,33 @@ pkgconf_tuple_find_global(const pkgconf_client_t *client, const char *key)
return NULL;
}
/*
* !doc
*
* .. c:function:: void pkgconf_tuple_free_global(pkgconf_client_t *client)
*
* Delete all global variables associated with a pkgconf client object.
*
* :param pkgconf_client_t* client: The pkgconf client object to modify.
* :return: nothing
*/
void
pkgconf_tuple_free_global(pkgconf_client_t *client)
{
pkgconf_tuple_free(&client->global_vars);
}
/*
* !doc
*
* .. c:function:: void pkgconf_tuple_define_global(pkgconf_client_t *client, const char *kv)
*
* Parse and define a global variable.
*
* :param pkgconf_client_t* client: The pkgconf client object to modify.
* :param char* kv: The variable in the form of ``key=value``.
* :return: nothing
*/
void
pkgconf_tuple_define_global(pkgconf_client_t *client, const char *kv)
{
@ -76,6 +135,21 @@ pkgconf_tuple_find_delete(pkgconf_list_t *list, const char *key)
}
}
/*
* !doc
*
* .. c:function:: pkgconf_tuple_t *pkgconf_tuple_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key, const char *value, bool parse)
*
* Optionally parse and then define a variable.
*
* :param pkgconf_client_t* client: The pkgconf client object to access.
* :param pkgconf_list_t* list: The variable list to add the new variable to.
* :param char* key: The name of the variable being added.
* :param char* value: The value of the variable being added.
* :param bool parse: Whether or not to parse the value for variable substitution.
* :return: a variable object
* :rtype: pkgconf_tuple_t *
*/
pkgconf_tuple_t *
pkgconf_tuple_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key, const char *value, bool parse)
{
@ -94,6 +168,19 @@ pkgconf_tuple_add(const pkgconf_client_t *client, pkgconf_list_t *list, const ch
return tuple;
}
/*
* !doc
*
* .. c:function:: char *pkgconf_tuple_find(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key)
*
* Look up a variable in a variable list.
*
* :param pkgconf_client_t* client: The pkgconf client object to access.
* :param pkgconf_list_t* list: The variable list to search.
* :param char* key: The variable name to search for.
* :return: the value of the variable or ``NULL``
* :rtype: char *
*/
char *
pkgconf_tuple_find(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key)
{
@ -114,6 +201,19 @@ pkgconf_tuple_find(const pkgconf_client_t *client, pkgconf_list_t *list, const c
return NULL;
}
/*
* !doc
*
* .. c:function:: char *pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value)
*
* Parse an expression for variable substitution.
*
* :param pkgconf_client_t* client: The pkgconf client object to access.
* :param pkgconf_list_t* list: The variable list to search for variables (along side the global variable list).
* :param char* value: The ``key=value`` string to parse.
* :return: the variable data with any variables substituted
* :rtype: char *
*/
char *
pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value)
{
@ -177,6 +277,18 @@ pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const
return strdup(buf);
}
/*
* !doc
*
* .. c:function:: void pkgconf_tuple_free_entry(pkgconf_tuple_t *tuple, pkgconf_list_t *list)
*
* Deletes a variable object, removing it from any variable lists and releasing any memory associated
* with it.
*
* :param pkgconf_tuple_t* tuple: The variable object to release.
* :param pkgconf_list_t* list: The variable list the variable object is attached to.
* :return: nothing
*/
void
pkgconf_tuple_free_entry(pkgconf_tuple_t *tuple, pkgconf_list_t *list)
{
@ -187,6 +299,16 @@ pkgconf_tuple_free_entry(pkgconf_tuple_t *tuple, pkgconf_list_t *list)
free(tuple);
}
/*
* !doc
*
* .. c:function:: void pkgconf_tuple_free(pkgconf_list_t *list)
*
* Deletes a variable list and any variables attached to it.
*
* :param pkgconf_list_t* list: The variable list to delete.
* :return: nothing
*/
void
pkgconf_tuple_free(pkgconf_list_t *list)
{