Make nodes opaque

6 files changed, 87 insertions, 91 deletions

diff --git a/include/serd/env.h b/include/serd/env.h
index 3d4cafd0..7a03e80d 100644
--- a/include/serd/env.h
+++ b/include/serd/env.h
@@ -33,7 +33,7 @@ SERD_API void
 serd_env_free(SerdEnv* SERD_NULLABLE env);
 
 /// Get the current base URI
-SERD_API const SerdNode* SERD_NONNULL
+SERD_API const SerdNode* SERD_NULLABLE
 serd_env_base_uri(const SerdEnv* SERD_NONNULL env,
                   SerdURIView* SERD_NULLABLE  out);
 
@@ -62,10 +62,10 @@ serd_env_set_prefix_from_strings(SerdEnv* SERD_NONNULL    env,
 
 /// Qualify `uri` into a CURIE if possible
 SERD_API bool
-serd_env_qualify(const SerdEnv* SERD_NULLABLE env,
-                 const SerdNode* SERD_NONNULL uri,
-                 SerdNode* SERD_NONNULL       prefix,
-                 SerdStringView* SERD_NONNULL suffix);
+serd_env_qualify(const SerdEnv* SERD_NULLABLE                env,
+                 const SerdNode* SERD_NONNULL                uri,
+                 const SerdNode* SERD_NULLABLE* SERD_NONNULL prefix,
+                 SerdStringView* SERD_NONNULL                suffix);
 
 /**
    Expand `curie`.
@@ -74,17 +74,17 @@ serd_env_qualify(const SerdEnv* SERD_NULLABLE env,
    not defined in `env`.
 */
 SERD_API SerdStatus
-serd_env_expand(const SerdEnv* SERD_NULLABLE env,
-                const SerdNode* SERD_NONNULL curie,
-                SerdStringView* SERD_NONNULL uri_prefix,
-                SerdStringView* SERD_NONNULL uri_suffix);
+serd_env_expand(const SerdEnv* SERD_NULLABLE  env,
+                const SerdNode* SERD_NULLABLE curie,
+                SerdStringView* SERD_NONNULL  uri_prefix,
+                SerdStringView* SERD_NONNULL  uri_suffix);
 
 /**
    Expand `node`, which must be a CURIE or URI, to a full URI.
 
    Returns null if `node` can not be expanded.
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_env_expand_node(const SerdEnv* SERD_NULLABLE env,
                      const SerdNode* SERD_NONNULL node);
 
diff --git a/include/serd/node.h b/include/serd/node.h
index 73be120e..eb4f8c9e 100644
--- a/include/serd/node.h
+++ b/include/serd/node.h
@@ -20,24 +20,26 @@ SERD_BEGIN_DECLS
 */
 
 /**
-   Type of a node.
+   @defgroup serd_node_types Types
+   @{
+*/
 
-   An RDF node, in the abstract sense, can be either a resource, literal, or a
-   blank.  This type is more precise, because syntactically there are two ways
-   to refer to a resource (by URI or CURIE).
+/**
+   An RDF node.
 
-   There are also two ways to refer to a blank node in syntax (by ID or
-   anonymously), but this is handled by statement flags rather than distinct
-   node types.
+   A node in memory is a single contiguous chunk of data, but the
+   representation is opaque and may only be accessed through the API.
 */
-typedef enum {
-  /**
-     The type of a nonexistent node.
+typedef struct SerdNodeImpl SerdNode;
 
-     This type is useful as a sentinel, but is never emitted by the reader.
-  */
-  SERD_NOTHING = 0,
+/**
+   Type of a node.
 
+   An abstract RDF node can be either a resource or a literal.  This type is
+   more precise to preserve syntactic differences and support additional
+   features.
+*/
+typedef enum {
   /**
      Literal value.
 
@@ -88,39 +90,30 @@ typedef enum {
 /// Bitwise OR of #SerdNodeFlag values
 typedef uint32_t SerdNodeFlags;
 
-/// A syntactic RDF node
-typedef struct {
-  const char* SERD_NULLABLE buf;     ///< Value string
-  size_t                    n_bytes; ///< Size in bytes (excluding null)
-  SerdNodeFlags             flags;   ///< Node flags (string properties)
-  SerdNodeType              type;    ///< Node type
-} SerdNode;
-
-static const SerdNode SERD_NODE_NULL = {NULL, 0, 0, SERD_NOTHING};
-
 /**
-   Make a (shallow) node from `str`.
-
-   This measures, but does not copy, `str`.  No memory is allocated.
+   @}
+   @defgroup serd_node_dynamic_allocation Dynamic Allocation
+   @{
 */
-SERD_API SerdNode
-serd_node_from_string(SerdNodeType type, const char* SERD_NULLABLE str);
 
 /**
-   Make a (shallow) node from a prefix of `str`.
+   Create a new node from `str`.
+*/
+SERD_API SerdNode* SERD_ALLOCATED
+serd_new_string(SerdNodeType type, const char* SERD_NULLABLE str);
 
-   This measures, but does not copy, `str`.  No memory is allocated.
-   Note that the returned node may not be null terminated.
+/**
+   Create a new node from a prefix of `str`.
 */
-SERD_API SerdNode
-serd_node_from_substring(SerdNodeType              type,
-                         const char* SERD_NULLABLE str,
-                         size_t                    len);
+SERD_API SerdNode* SERD_ALLOCATED
+serd_new_substring(SerdNodeType              type,
+                   const char* SERD_NULLABLE str,
+                   size_t                    len);
 
 /**
    Create a new URI node from a node.
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_uri_from_node(const SerdNode* SERD_NONNULL     uri_node,
                        const SerdURIView* SERD_NULLABLE base,
                        SerdURIView* SERD_NULLABLE       out);
@@ -128,7 +121,7 @@ serd_new_uri_from_node(const SerdNode* SERD_NONNULL     uri_node,
 /**
    Create a new URI node from a string.
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_uri_from_string(const char* SERD_NULLABLE        str,
                          const SerdURIView* SERD_NULLABLE base,
                          SerdURIView* SERD_NULLABLE       out);
@@ -142,7 +135,7 @@ serd_new_uri_from_string(const char* SERD_NULLABLE        str,
    If `path` is relative, `hostname` is ignored.
    If `out` is not NULL, it will be set to the parsed URI.
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_file_uri(const char* SERD_NONNULL   path,
                   const char* SERD_NULLABLE  hostname,
                   SerdURIView* SERD_NULLABLE out);
@@ -157,7 +150,7 @@ serd_new_file_uri(const char* SERD_NONNULL   path,
    @param out Set to the parsing of the new URI (i.e. points only to
    memory owned by the new returned node).
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_uri(const SerdURIView* SERD_NONNULL  uri,
              const SerdURIView* SERD_NULLABLE base,
              SerdURIView* SERD_NULLABLE       out);
@@ -174,7 +167,7 @@ serd_new_uri(const SerdURIView* SERD_NONNULL  uri,
    @param out Set to the parsing of the new URI (i.e. points only to
    memory owned by the new returned node).
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_relative_uri(const SerdURIView* SERD_NONNULL  uri,
                       const SerdURIView* SERD_NULLABLE base,
                       const SerdURIView* SERD_NULLABLE root,
@@ -195,11 +188,11 @@ serd_new_relative_uri(const SerdURIView* SERD_NONNULL  uri,
    @param d The value for the new node.
    @param frac_digits The maximum number of digits after the decimal place.
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_decimal(double d, unsigned frac_digits);
 
 /// Create a new node by serialising `i` into an xsd:integer string
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_integer(int64_t i);
 
 /**
@@ -212,54 +205,62 @@ serd_new_integer(int64_t i);
    @param size Size of `buf`.
    @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
 */
-SERD_API SerdNode
+SERD_API SerdNode* SERD_ALLOCATED
 serd_new_blob(const void* SERD_NONNULL buf, size_t size, bool wrap_lines);
 
+/// Return a deep copy of `node`
+SERD_API SerdNode* SERD_ALLOCATED
+serd_node_copy(const SerdNode* SERD_NULLABLE node);
+
 /**
-   Make a deep copy of `node`.
+   Free any data owned by `node`.
+*/
+SERD_API void
+serd_node_free(SerdNode* SERD_NULLABLE node);
 
-   @return a node that the caller must free with serd_node_free().
+/**
+   @}
+   @defgroup serd_node_accessors Accessors
+   @{
 */
-SERD_API SerdNode
-serd_node_copy(const SerdNode* SERD_NULLABLE node);
 
 /// Return the type of a node
-SERD_PURE_API
-SerdNodeType
+SERD_PURE_API SerdNodeType
 serd_node_type(const SerdNode* SERD_NONNULL node);
 
 /// Return the length of a node's string in bytes, excluding the terminator
-SERD_PURE_API
-size_t
-serd_node_length(const SerdNode* SERD_NONNULL node);
+SERD_PURE_API size_t
+serd_node_length(const SerdNode* SERD_NULLABLE node);
 
 /// Return the additional flags of a node
-SERD_PURE_API
-SerdNodeFlags
+SERD_PURE_API SerdNodeFlags
 serd_node_flags(const SerdNode* SERD_NONNULL node);
 
 /// Return the string contents of a node
-SERD_PURE_API
-const char* SERD_NONNULL
+SERD_CONST_API const char* SERD_NONNULL
 serd_node_string(const SerdNode* SERD_NONNULL node);
 
-/// Return true iff `a` is equal to `b`
-SERD_PURE_API
-bool
-serd_node_equals(const SerdNode* SERD_NONNULL a,
-                 const SerdNode* SERD_NONNULL b);
+/**
+   @}
+   @defgroup serd_node_operators Operators
+   @{
+*/
 
 /**
-   Free any data owned by `node`.
+   Return true iff `a` is equal to `b`.
 
-   Note that if `node` is itself dynamically allocated (which is not the case
-   for nodes created internally by serd), it will not be freed.
+   For convenience, either argument may be null, which isn't considered equal
+   to any node.
+
+   @return True if `a` and `b` point to equal nodes, or are both null.
 */
-SERD_API void
-serd_node_free(SerdNode* SERD_NULLABLE node);
+SERD_PURE_API bool
+serd_node_equals(const SerdNode* SERD_NULLABLE a,
+                 const SerdNode* SERD_NULLABLE b);
 
 /**
    @}
+   @}
 */
 
 SERD_END_DECLS
diff --git a/include/serd/reader.h b/include/serd/reader.h
index 1d9e9a6b..e4bd9b2f 100644
--- a/include/serd/reader.h
+++ b/include/serd/reader.h
@@ -59,8 +59,7 @@ serd_reader_set_error_sink(SerdReader* SERD_NONNULL    reader,
                            void* SERD_NULLABLE         error_handle);
 
 /// Return the `handle` passed to serd_reader_new()
-SERD_PURE_API
-void* SERD_NULLABLE
+SERD_PURE_API void* SERD_NULLABLE
 serd_reader_handle(const SerdReader* SERD_NONNULL reader);
 
 /**
diff --git a/include/serd/status.h b/include/serd/status.h
index 5de96d1d..3ebdaf8f 100644
--- a/include/serd/status.h
+++ b/include/serd/status.h
@@ -40,8 +40,7 @@ typedef enum {
 } SerdStatus;
 
 /// Return a string describing a status code
-SERD_CONST_API
-const char* SERD_NONNULL
+SERD_CONST_API const char* SERD_NONNULL
 serd_strerror(SerdStatus status);
 
 /**
diff --git a/include/serd/uri.h b/include/serd/uri.h
index fc41c0c2..06cb97fb 100644
--- a/include/serd/uri.h
+++ b/include/serd/uri.h
@@ -53,8 +53,7 @@ serd_file_uri_parse(const char* SERD_NONNULL          uri,
                     char* SERD_NONNULL* SERD_NULLABLE hostname);
 
 /// Return true iff `utf8` starts with a valid URI scheme
-SERD_PURE_API
-bool
+SERD_PURE_API bool
 serd_uri_string_has_scheme(const char* SERD_NULLABLE utf8);
 
 /// Parse `utf8`, writing result to `out`
diff --git a/include/serd/writer.h b/include/serd/writer.h
index 35f44940..66c3d338 100644
--- a/include/serd/writer.h
+++ b/include/serd/writer.h
@@ -12,7 +12,6 @@
 #include "serd/status.h"
 #include "serd/stream.h"
 #include "serd/syntax.h"
-#include "serd/uri.h"
 
 #include <stddef.h>
 #include <stdint.h>
@@ -49,20 +48,19 @@ typedef uint32_t SerdWriterFlags;
 
 /// Create a new RDF writer
 SERD_API SerdWriter* SERD_ALLOCATED
-serd_writer_new(SerdSyntax                       syntax,
-                SerdWriterFlags                  flags,
-                SerdEnv* SERD_NONNULL            env,
-                const SerdURIView* SERD_NULLABLE base_uri,
-                SerdSink SERD_NONNULL            ssink,
-                void* SERD_NULLABLE              stream);
+serd_writer_new(SerdSyntax                    syntax,
+                SerdWriterFlags               flags,
+                SerdEnv* SERD_NONNULL         env,
+                const SerdNode* SERD_NULLABLE base_uri,
+                SerdSink SERD_NONNULL         ssink,
+                void* SERD_NULLABLE           stream);
 
 /// Free `writer`
 SERD_API void
 serd_writer_free(SerdWriter* SERD_NULLABLE writer);
 
 /// Return the env used by `writer`
-SERD_PURE_API
-SerdEnv* SERD_NONNULL
+SERD_PURE_API SerdEnv* SERD_NONNULL
 serd_writer_env(SerdWriter* SERD_NONNULL writer);
 
 /**