// Copyright 2011-2022 David Robillard <d@drobilla.net>
// SPDX-License-Identifier: ISC

#ifndef SERD_ENV_H
#define SERD_ENV_H

#include "serd/attributes.h"
#include "serd/node.h"
#include "serd/sink.h"
#include "serd/status.h"
#include "zix/allocator.h"
#include "zix/attributes.h"
#include "zix/string_view.h"

#include <stdbool.h>

SERD_BEGIN_DECLS

/**
   @defgroup serd_env Environment
   @ingroup serd_streaming
   @{
*/

/// Lexical environment for relative URIs or CURIEs (base URI and namespaces)
typedef struct SerdEnvImpl SerdEnv;

/// Create a new environment
SERD_API SerdEnv* ZIX_ALLOCATED
serd_env_new(ZixAllocator* ZIX_NULLABLE allocator, ZixStringView base_uri);

/// Copy an environment
SERD_API SerdEnv* ZIX_ALLOCATED
serd_env_copy(ZixAllocator* ZIX_NULLABLE  allocator,
              const SerdEnv* ZIX_NULLABLE env);

/// Return true iff `a` is equal to `b`
SERD_PURE_API bool
serd_env_equals(const SerdEnv* ZIX_NULLABLE a, const SerdEnv* ZIX_NULLABLE b);

/// Free `env`
SERD_API void
serd_env_free(SerdEnv* ZIX_NULLABLE env);

/// Get the current base URI
SERD_PURE_API const SerdNode* ZIX_NULLABLE
serd_env_base_uri(const SerdEnv* ZIX_NULLABLE env);

/// Set the current base URI
SERD_API SerdStatus
serd_env_set_base_uri(SerdEnv* ZIX_NONNULL env, ZixStringView uri);

/**
   Set the current base URI to a filesystem path.

   This will set the base URI to a properly formatted file URI that points to
   the canonical version of `path`.  Note that this requires the path to
   actually exist.
*/
SERD_API SerdStatus
serd_env_set_base_path(SerdEnv* ZIX_NONNULL env, ZixStringView path);

/**
   Set a namespace prefix.

   A namespace prefix is used to expand CURIE nodes, for example, with the
   prefix "xsd" set to "http://www.w3.org/2001/XMLSchema#", "xsd:decimal" will
   expand to "http://www.w3.org/2001/XMLSchema#decimal".
*/
SERD_API SerdStatus
serd_env_set_prefix(SerdEnv* ZIX_NONNULL env,
                    ZixStringView        name,
                    ZixStringView        uri);

/**
   Unset a namespace prefix.

   This removes the namespace prefix with the given name, if present.  No such
   prefix being found is not considered an error, that is, the call is
   successful as long as the prefix is not set in the env upon return.

   @return #SERD_SUCCESS if the prefix was removed or not present, or an error.
*/
SERD_API SerdStatus
serd_env_unset_prefix(SerdEnv* ZIX_NONNULL env, ZixStringView name);

/**
   Qualify `uri` into a prefix and suffix (like a CURIE) if possible.

   @param env Environment with prefixes to use.

   @param uri URI to qualify.

   @param prefix On success, pointed to a prefix string slice, which is only
   valid until the next time `env` is mutated.

   @param suffix On success, pointed to a suffix string slice, which is only
   valid until the next time `env` is mutated.

   @return #SERD_SUCCESS, or #SERD_FAILURE if `uri` can not be qualified with
   `env`.
*/
SERD_API SerdStatus
serd_env_qualify(const SerdEnv* ZIX_NULLABLE env,
                 ZixStringView               uri,
                 ZixStringView* ZIX_NONNULL  prefix,
                 ZixStringView* ZIX_NONNULL  suffix);

/**
   Expand `curie` to an absolute URI if possible.

   For example, if `env` has the prefix "rdf" set to
   <http://www.w3.org/1999/02/22-rdf-syntax-ns#>, then calling this with curie
   "rdf:type" will produce <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>.

   Returns null if `node` can not be expanded.
*/
SERD_API SerdNode* ZIX_ALLOCATED
serd_env_expand_curie(const SerdEnv* ZIX_NULLABLE env, ZixStringView curie);

/**
   Expand `node` to an absolute URI if possible.

   Returns null if `node` can not be expanded.
*/
SERD_API SerdNode* ZIX_ALLOCATED
serd_env_expand_node(const SerdEnv* ZIX_NULLABLE  env,
                     const SerdNode* ZIX_NULLABLE node);

/// Write all prefixes in `env` to `sink`
SERD_API SerdStatus
serd_env_write_prefixes(const SerdEnv* ZIX_NONNULL  env,
                        const SerdSink* ZIX_NONNULL sink);

/**
   @}
*/

SERD_END_DECLS

#endif // SERD_ENV_H