libpkgconf: document path module

pull/100/head
William Pitcock 2016-12-10 20:14:42 -06:00
parent af503f210a
commit 4cc0d017da
3 changed files with 122 additions and 0 deletions

51
doc/libpkgconf-path.rst Normal file
View File

@ -0,0 +1,51 @@
libpkgconf `path` module
========================
The `path` module provides functions for manipulating lists of paths in a cross-platform manner. Notably,
it is used by the `pkgconf client` to parse the ``PKG_CONFIG_PATH``, ``PKG_CONFIG_LIBDIR`` and related environment
variables.
.. c:function:: void pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
Adds a path node to a path list.
:param char* text: The path text to add as a path node.
:param pkgconf_list_t* dirlist: The path list to add the path node to.
:return: nothing
.. c:function:: size_t pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
Splits a given text input and inserts paths into a path list.
:param char* text: The path text to split and add as path nodes.
:param pkgconf_list_t* dirlist: The path list to have the path nodes added to.
:return: number of path nodes added to the path list
:rtype: size_t
.. c:function:: size_t pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
Adds the paths specified in an environment variable to a path list. If the environment variable is not set,
an optional default set of paths is added.
:param char* environ: The environment variable to look up.
:param char* fallback: The fallback paths to use if the environment variable is not set.
:param pkgconf_list_t* dirlist: The path list to add the path nodes to.
:return: number of path nodes added to the path list
:rtype: size_t
.. c:function:: bool pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
Checks whether a path has a matching prefix in a path list.
:param char* path: The path to check against a path list.
:param pkgconf_list_t* dirlist: The path list to check the path against.
:return: true if the path list has a matching prefix, otherwise false
:rtype: bool
.. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist)
Releases any path nodes attached to the given path list.
:param pkgconf_list_t* dirlist: The path list to clean up.
:return: nothing

View File

@ -9,3 +9,4 @@ libpkgconf - an API for managing `pkg-config` modules
libpkgconf-cache libpkgconf-cache
libpkgconf-client libpkgconf-client
libpkgconf-dependency libpkgconf-dependency
libpkgconf-path

View File

@ -15,6 +15,28 @@
#include <libpkgconf/libpkgconf.h> #include <libpkgconf/libpkgconf.h>
/*
* !doc
*
* libpkgconf `path` module
* ========================
*
* The `path` module provides functions for manipulating lists of paths in a cross-platform manner. Notably,
* it is used by the `pkgconf client` to parse the ``PKG_CONFIG_PATH``, ``PKG_CONFIG_LIBDIR`` and related environment
* variables.
*/
/*
* !doc
*
* .. c:function:: void pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
*
* Adds a path node to a path list.
*
* :param char* text: The path text to add as a path node.
* :param pkgconf_list_t* dirlist: The path list to add the path node to.
* :return: nothing
*/
void void
pkgconf_path_add(const char *text, pkgconf_list_t *dirlist) pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
{ {
@ -26,6 +48,18 @@ pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
pkgconf_node_insert_tail(&node->lnode, node, dirlist); pkgconf_node_insert_tail(&node->lnode, node, dirlist);
} }
/*
* !doc
*
* .. c:function:: size_t pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
*
* Splits a given text input and inserts paths into a path list.
*
* :param char* text: The path text to split and add as path nodes.
* :param pkgconf_list_t* dirlist: The path list to have the path nodes added to.
* :return: number of path nodes added to the path list
* :rtype: size_t
*/
size_t size_t
pkgconf_path_split(const char *text, pkgconf_list_t *dirlist) pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
{ {
@ -47,6 +81,20 @@ pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
return count; return count;
} }
/*
* !doc
*
* .. c:function:: size_t pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
*
* Adds the paths specified in an environment variable to a path list. If the environment variable is not set,
* an optional default set of paths is added.
*
* :param char* environ: The environment variable to look up.
* :param char* fallback: The fallback paths to use if the environment variable is not set.
* :param pkgconf_list_t* dirlist: The path list to add the path nodes to.
* :return: number of path nodes added to the path list
* :rtype: size_t
*/
size_t size_t
pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist) pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
{ {
@ -63,6 +111,18 @@ pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgco
return 0; return 0;
} }
/*
* !doc
*
* .. c:function:: bool pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
*
* Checks whether a path has a matching prefix in a path list.
*
* :param char* path: The path to check against a path list.
* :param pkgconf_list_t* dirlist: The path list to check the path against.
* :return: true if the path list has a matching prefix, otherwise false
* :rtype: bool
*/
bool bool
pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist) pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
{ {
@ -79,6 +139,16 @@ pkgconf_path_match_list(const char *path, pkgconf_list_t *dirlist)
return false; return false;
} }
/*
* !doc
*
* .. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist)
*
* Releases any path nodes attached to the given path list.
*
* :param pkgconf_list_t* dirlist: The path list to clean up.
* :return: nothing
*/
void void
pkgconf_path_free(pkgconf_list_t *dirlist) pkgconf_path_free(pkgconf_list_t *dirlist)
{ {