lsup_rdf/include/lsup/namespace.h

#ifndef _LSUP_NAMESPACE_H
#define _LSUP_NAMESPACE_H

#include "hashmap.h"

#include "core.h"


/** @defgroup namespace Namespace module
 * @ingroup public
 * @{
 */

/** @brief Namespace prefix length, including terminator.
 */
#define PFX_LEN 8


/** @brief Namespace map structure.
 *
 * It contains a double hash map of pfx->ns and ns->pfx for fast 2-way lookup.
 *
 * FIXME that's not true, currently ns lookup by prefix involves an iteration.
 *
 * Prefixes are fixed PFX_LEN-size strings, namespaces are arbitrary sized
 * strings.
 */
typedef struct hashmap LSUP_NSMap;

/** @brief Namespace prefix type.
 */
typedef char LSUP_ns_pfx[PFX_LEN];


/** @brief Create a new namespace map.
 *
 * @return A pointer to an empty map. It must be freed with #LSUP_nsmap_free().
 */
LSUP_NSMap *
LSUP_nsmap_new (void);


/** @brief Free a namespace map and its internal structures.
 *
 * @param[in] map The map to free.
 */
void
LSUP_nsmap_free (LSUP_NSMap *map);


/** @brief Add a prefix -> namespace pair to the map or update it.
 *
 * If the prefix already exists, it is quietly updated with the new value.
 *
 * @param[in] map The map to add to.
 *
 * @param[in] pfx The namespace prefix.
 *
 * @param[in] nsstr Fully qualified namespace.
 *
 * @return LSUP_OK if the record was added or replaced; LSUP_MEM_ERR if an
 * allocation error occurred.
 */
LSUP_rc
LSUP_nsmap_add (LSUP_NSMap *map, const char *pfx, const char *nsstr);


/** @brief Remove a prefix -> namespace pair from a map.
 *
 * @param[in] map The map to remove from.
 *
 * @param[in] pfx The namespace prefix to remove.
 *
 * @return LSUP_OK on successful delete; LSUP_NOACTION if no record was found.
 */
LSUP_rc
LSUP_nsmap_remove (LSUP_NSMap *map, const char *pfx);


/** @brief Get the namespace for a prefix.
 *
 * @param[in] map The map to look up the namespace in.
 *
 * @param[in] pfx The prefix to look up.
 *
 * @return A pointer to the namespace string. Note that this is not a copy and
 *  should not be modified directly.
 */
const char *
LSUP_nsmap_get_ns (const LSUP_NSMap *map, const char *pfx);


/** @brief Get the prefix for a namespace.
 *
 * @param[in] map The map to look up the prefix in.
 *
 * @param[in] ns The namespace to look up.
 *
 * @return Found prefix, or NULL if the namespace is not mapped.
 */
const char *
LSUP_nsmap_get_pfx (const LSUP_NSMap *map, const char *ns);


/** @brief Convert a namespace-prefixed string to a FQ URI sring if mapped.
 *
 * @param[in] map Namespace map to look up.
 *
 * @param[in] pfx_uri URI string to denormalize.
 *
 * @param[out] fq_uri String pointer to be filled with the FQ URI. The caller
 *  is in charge of freeing the memory. If the namespace is not in the map or
 *  an error occurred, this will be NULL. This is to inform the caller that the
 *  result is not normalized and a TERM_NS_IRIREF should not be construed with
 *  it.
 *
 * @return LSUP_OK on success, LSUP_NORESULT if no entry was found in the map,
 *  LSUP_MEM_ERR if a memory allocation error ocurred.
 */
LSUP_rc
LSUP_nsmap_normalize_uri (
        const LSUP_NSMap *map, const char *pfx_uri, char **fq_uri);


/** @brief Convert a FQ URI string to a prefixed string if the prefix is found.
 *
 * @todo Note that this function does not attempt to find the longest or
 * shortest namespace prefix in case of conflicts (e.g. when both
 * `http://example.edu/` and `http://example.edu/data/` are mapped and
 * `http://example.edu/data/51937642` is being denormalized). In such
 * case, the first prefix that is found is assigned.
 *
 * @param[in] map Namespace map to look up.
 *
 * @param[in] fq_uri URI string to normalize.
 *
 * @param[out] pfx_uri String pointer to be filled with the prefixed URI. The
 *  caller is in charge of freeing the memory. If the namespace is not in the
 *  map or an error occurred, this will be NULL. This is to inform the caller
 *  that the result is not denormalized and a TERM_IRIREF should not be
 *  construed with it.
 *
 * @return LSUP_OK on success, LSUP_NORESULT if no entry was found in the map,
 *  LSUP_MEM_ERR if a memory allocation error ocurred.
 */
LSUP_rc
LSUP_nsmap_denormalize_uri (
        const LSUP_NSMap *map, const char *fq_uri, char **pfx_uri);


/** @brief Dump all entries of a namespace map.
 *
 * @param[in] map Map to dump.
 *
 * @return 2-dimensional array of strings, with as many rows as namespace
 *  entries, and two columns: the first for the namespace prefix, the second
 *  for the namespace. The last entry is NULL. Prefix and namespace strings
 *  pointed to by the array are owned by the namespace map, but the individual
 *  pointers must be freed along with the parent array. E.g.:
 *
 *      const char ***nsm_data = LSUP_nsmap_dump (nsm);
 *      // [...]
 *      for (size_t i = 0; nsm_data[i] != NULL; i++)
 *          free (nsm_data[i]);
 *      free (nsm_data);
 */
const char ***
LSUP_nsmap_dump (const LSUP_NSMap *map);

/// @}  END defgroup namespace
#endif