From e6c49153ffcc2e46cc63e2a08fbeacdc409a9a48 Mon Sep 17 00:00:00 2001 From: William Pitcock Date: Sun, 11 Dec 2016 17:28:27 -0600 Subject: [PATCH] libpkgconf: document tuple module --- doc/libpkgconf-tuple.rst | 91 +++++++++++++++++++++++++++++ doc/libpkgconf.rst | 1 + libpkgconf/tuple.c | 122 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+) create mode 100644 doc/libpkgconf-tuple.rst diff --git a/doc/libpkgconf-tuple.rst b/doc/libpkgconf-tuple.rst new file mode 100644 index 0000000..b87751d --- /dev/null +++ b/doc/libpkgconf-tuple.rst @@ -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 diff --git a/doc/libpkgconf.rst b/doc/libpkgconf.rst index da31a05..76b8d8a 100644 --- a/doc/libpkgconf.rst +++ b/doc/libpkgconf.rst @@ -11,3 +11,4 @@ libpkgconf - an API for managing `pkg-config` modules libpkgconf-dependency libpkgconf-path libpkgconf-queue + libpkgconf-tuple diff --git a/libpkgconf/tuple.c b/libpkgconf/tuple.c index 03803fc..2097876 100644 --- a/libpkgconf/tuple.c +++ b/libpkgconf/tuple.c @@ -15,12 +15,50 @@ #include +/* + * !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) {