Update style and switch to 2-clause BSD license.

git-svn-id: http://svn.drobilla.net/sord/trunk@41 3d64ff67-21c5-427c-a301-fe4f08042e5a

1 files changed, 246 insertions, 143 deletions

diff --git a/sord/sord.h b/sord/sord.h
index c632815..f496811 100644
--- a/sord/sord.h
+++ b/sord/sord.h
@@ -1,72 +1,87 @@
-/* Sord, a lightweight RDF model library.
- * Copyright 2010-2011 David Robillard <d@drobilla.net>
- *
- * Sord is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * Sord is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
- * License for details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- */
-
-/** @file sord.h
- * Public Sord API.
- */
+/*
+  Copyright 2011 David Robillard <http://drobilla.net>
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+
+  1. Redistributions of source code must retain the above copyright notice,
+     this list of conditions and the following disclaimer.
+
+  2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+  AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+  OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+  THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/**
+   @file sord.h API for Sord, a lightweight RDF model library.
+*/
 
 #ifndef SORD_SORD_H
 #define SORD_SORD_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 #include <stdbool.h>
+#include <stddef.h>
 #include <stdint.h>
+#include <stdio.h>
 
 #include "serd/serd.h"
 
-#if defined _WIN32 || defined __CYGWIN__
-	#define SORD_LIB_IMPORT __declspec(dllimport)
-	#define SORD_LIB_EXPORT __declspec(dllexport)
-#else
-	#define SORD_LIB_IMPORT __attribute__ ((visibility("default")))
-	#define SORD_LIB_EXPORT __attribute__ ((visibility("default")))
-#endif
-
-#ifdef SORD_SHARED  // Building a shared library
-	#ifdef SORD_INTERNAL  // Building SORD (not using it)
+#ifdef SORD_SHARED
+	#if defined _WIN32 || defined __CYGWIN__
+		#define SORD_LIB_IMPORT __declspec(dllimport)
+		#define SORD_LIB_EXPORT __declspec(dllexport)
+	#else
+		#define SORD_LIB_IMPORT __attribute__ ((visibility("default")))
+		#define SORD_LIB_EXPORT __attribute__ ((visibility("default")))
+	#endif
+	#ifdef SORD_INTERNAL
 		#define SORD_API SORD_LIB_EXPORT
 	#else
 		#define SORD_API SORD_LIB_IMPORT
 	#endif
-#else  // Building a static library
+#else
 	#define SORD_API
 #endif
 
-/** @defgroup sord Sord
- * A lightweight RDF model library.
- * Sord stores RDF (subject object predicate) triples, where triples may
- * have an added "context" field, i.e. (subject object predicate context).
- * @{
- */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+   @defgroup sord Sord
+   A lightweight RDF model library.
+
+   Sord stores RDF (subject object predicate context) quads, where the context
+   may be omitted (to represent triples in the default graph).
+   @{
+*/
 
 typedef struct _SordWorld* SordWorld;  ///< Sord world (library state)
 typedef struct _SordModel* SordModel;  ///< Quad store
 typedef struct _SordIter*  SordIter;   ///< Store iterator
 typedef struct _SordNode*  SordNode;   ///< Node
 
-/** Quad of IDs (statement), or a quad pattern.
- * Nodes are ordered (S P O G).  The ID of the default graph is 0.
- */
+/**
+   Quad of IDs (statement), or a quad pattern.
+
+   Nodes are ordered (S P O G).  The ID of the default graph is 0.
+*/
 typedef SordNode SordQuad[4];
 
-/** Index into a SordQuad. */
+/**
+   Index into a SordQuad.
+*/
 typedef enum {
 	SORD_SUBJECT   = 0,  ///< Subject
 	SORD_PREDICATE = 1,  ///< Predicate (a.k.a. "key")
@@ -74,14 +89,18 @@ typedef enum {
 	SORD_GRAPH     = 3   ///< Graph     (a.k.a. "context")
 } SordQuadIndex;
 
-/** Type of a node. */
+/**
+   Type of a node.
+*/
 typedef enum {
 	SORD_URI     = 1,  ///< URI
 	SORD_BLANK   = 2,  ///< Blank node identifier
-	SORD_LITERAL = 3   ///< Literal (string with optional lang and/or type)
+	SORD_LITERAL = 3   ///< Literal (string with optional lang or datatype)
 } SordNodeType;
 
-/** Indexing option. */
+/**
+   Indexing option.
+*/
 typedef enum {
 	SORD_SPO = 1,       ///< Subject,   Predicate, Object
 	SORD_SOP = 1 << 1,  ///< Subject,   Object,    Predicate
@@ -91,9 +110,10 @@ typedef enum {
 	SORD_POS = 1 << 5   ///< Predicate, Object,    Subject
 } SordIndexOption;
 
-/** @name World
- * @{
- */
+/**
+   @name World
+   @{
+*/
 
 SORD_API
 SordWorld
@@ -103,223 +123,305 @@ SORD_API
 void
 sord_world_free(SordWorld world);
 
-/** @} */
-/** @name Nodes
- * A Node is a component of a Quad.  Nodes may be URIs, blank nodes, or
- * (in the case of quad objects only) string literals.  Literal nodes may
- * have an associate language or datatype (but not both).
- * @{
- */
+/**
+   @}
+   @name Nodes
+   A Node is a component of a Quad.  Nodes may be URIs, blank nodes, or
+   (in the case of quad objects only) string literals.  Literal nodes may
+   have an associate language or datatype (but not both).
+   @{
+*/
 
-/** Find a URI, creating a new one if necessary iff @a create is true.
- * Use sord_get_uri_counted instead if the length of @a str is known.
- */
+/**
+   Find a URI, creating a new one if necessary iff @a create is true.
+
+   Use sord_get_uri_counted instead if the length of @a str is known.
+*/
 SORD_API
 SordNode
 sord_new_uri(SordWorld world, const uint8_t* str);
 
-/** Find a URI, creating a new one if necessary iff @a create is true. */
+/**
+   Find a URI, creating a new one if necessary iff @a create is true.
+*/
 SORD_API
 SordNode
-sord_new_uri_counted(SordWorld world, const uint8_t* str, int str_len);
+sord_new_uri_counted(SordWorld      world,
+                     const uint8_t* str,
+                     int            str_len);
 
-/** Find a blank, creating a new one if necessary iff @a create is true
- * Use sord_get_blank_counted instead if the length of @a str is known.
- */
+/**
+   Find a blank, creating a new one if necessary iff @a create is true.
+
+   Use sord_get_blank_counted instead if the length of @a str is known.
+*/
 SORD_API
 SordNode
 sord_new_blank(SordWorld world, const uint8_t* str);
 
-/** Find a blank, creating a new one if necessary iff @a create is true. */
+/**
+   Find a blank, creating a new one if necessary iff @a create is true.
+*/
 SORD_API
 SordNode
-sord_new_blank_counted(SordWorld world, const uint8_t* str, int str_len);
+sord_new_blank_counted(SordWorld      world,
+                       const uint8_t* str,
+                       int            str_len);
 
-/** Find a literal, creating a new one if necessary iff @a create is true.
- * Use sord_get_literal_counted instead if the length of @a str is known.
- */
+/**
+   Find a literal, creating a new one if necessary iff @a create is true.
+
+   Use sord_get_literal_counted instead if the length of @a str is known.
+*/
 SORD_API
 SordNode
-sord_new_literal(SordWorld world, SordNode datatype,
-                 const uint8_t* str, const char* lang);
+sord_new_literal(SordWorld      world,
+                 SordNode       datatype,
+                 const uint8_t* str,
+                 const char*    lang);
 
-/** Find a literal, creating a new one if necessary iff @a create is true. */
+/**
+   Find a literal, creating a new one if necessary iff @a create is true.
+*/
 SORD_API
 SordNode
-sord_new_literal_counted(SordWorld world, SordNode datatype,
-                         const uint8_t* str,  int     str_len,
-                         const char*    lang, uint8_t lang_len);
+sord_new_literal_counted(SordWorld      world,
+                         SordNode       datatype,
+                         const uint8_t* str,
+                         int            str_len,
+                         const char*    lang,
+                         uint8_t        lang_len);
 
-/** Copy a node. */
+/**
+   Copy a node.
+*/
 SORD_API
 SordNode
 sord_node_copy(SordNode node);
 
-/** Free a node. */
+/**
+   Free a node.
+*/
 SORD_API
 void
 sord_node_free(SordNode node);
 
-/** Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL). */
+/**
+   Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL).
+*/
 SORD_API
 SordNodeType
 sord_node_get_type(SordNode node);
 
-/** Return the string value of a node. */
+/**
+   Return the string value of a node.
+*/
 SORD_API
 const uint8_t*
 sord_node_get_string(SordNode node);
 
-/** Return the string value of a node, and set @a len to its length. */
+/**
+   Return the string value of a node, and set @a len to its length.
+*/
 SORD_API
 const uint8_t*
 sord_node_get_string_counted(SordNode node, size_t* len);
 
-/** Return the language of a literal node (or NULL). */
+/**
+   Return the language of a literal node (or NULL).
+*/
 SORD_API
 const char*
 sord_node_get_language(SordNode node);
 
-/** Return the datatype URI of a literal node (or NULL). */
+/**
+   Return the datatype URI of a literal node (or NULL).
+*/
 SORD_API
 SordNode
 sord_node_get_datatype(SordNode node);
 
-/** Return true iff @a a is equal to @a b.
- * Note this is much faster than comparing the node's strings.
- */
+/**
+   Return true iff @a a is equal to @a b.
+
+   Note this is much faster than comparing the node's strings.
+*/
 SORD_API
 bool
-sord_node_equals(const SordNode a, const SordNode b);
+sord_node_equals(const SordNode a,
+                 const SordNode b);
 
 /** @} */
 /** @name Model
  * @{
  */
 
-/** Create a new store.
- * @param indices SordIndexOption flags (e.g. SORD_SPO|SORD_OPS).
- *        Be sure to choose indices such that there is an index where the most
- *        significant node(s) are not variables for your queries.  For example,
- *        if you are going to make (? P O) queries, you should enable either
- *        SORD_OPS or SORD_POS.
- * @param graphs If true, store (and index) graph contexts.
- */
+/**
+   Create a new store.
+
+   @param world The world in which to make this store.
+
+   @param indices SordIndexOption flags (e.g. SORD_SPO|SORD_OPS).  Be sure to
+   choose indices such that there is an index where the most significant
+   node(s) are not variables for your queries.  For example, if you are going
+   to make (? P O) queries, you should enable either SORD_OPS or SORD_POS.
+
+   @param graphs If true, store (and index) graph contexts.
+*/
 SORD_API
 SordModel
-sord_new(SordWorld world, unsigned indices, bool graphs);
+sord_new(SordWorld world,
+         unsigned  indices,
+         bool      graphs);
 
-/** Close and free @a sord. */
+/**
+   Close and free @a sord.
+*/
 SORD_API
 void
 sord_free(SordModel model);
 
+/**
+   Get the world associated with @a model.
+*/
 SORD_API
 SordWorld
 sord_get_world(SordModel model);
 
-/** Return the number of nodes stored in @a sord.
- * Nodes are included in this count iff they are a part of a quad in @a sord.
- */
+/**
+   Return the number of nodes stored in @a sord.
+
+   Nodes are included in this count iff they are a part of a quad in @a sord.
+*/
 SORD_API
 int
 sord_num_nodes(SordWorld world);
 
-/** Return the number of quads stored in @a sord. */
+/**
+   Return the number of quads stored in @a sord.
+*/
 SORD_API
 int
 sord_num_quads(SordModel model);
 
-/** Return an iterator to the start of the store. */
+/**
+   Return an iterator to the start of the store.
+*/
 SORD_API
 SordIter
 sord_begin(SordModel model);
 
-/** Return an iterator that will iterate over each graph URI. */
+/**
+   Return an iterator that will iterate over each graph URI.
+*/
 SORD_API
 SordIter
 sord_graphs_begin(SordModel model);
 
-/** Search for a triple pattern.
- * @return an iterator to the first match, or NULL if no matches found
- */
+/**
+   Search for a triple pattern.
+   @return an iterator to the first match, or NULL if no matches found.
+*/
 SORD_API
 SordIter
 sord_find(SordModel model, const SordQuad pat);
 
-/** Add a quad to the store. */
+/**
+   Add a quad to the store.
+*/
 SORD_API
 void
 sord_add(SordModel model, const SordQuad quad);
 
-/** Remove a quad from the store.
- * This function invalidates all iterators to @a sord (use sord_remove_iter
- * if this is undesirable)
- */
+/**
+   Remove a quad from the store.
+
+   This function invalidates all iterators to @a sord (use sord_remove_iter
+   if this is undesirable)
+*/
 SORD_API
 void
 sord_remove(SordModel model, const SordQuad quad);
 
-/** Remove a quad from the store by iterator.
- * @a iter will be incremented to point at the next value.
- */
+/**
+   Remove a quad from the store by iterator.
+
+   @a iter will be incremented to point at the next value.
+*/
 SORD_API
 void
 sord_remove_iter(SordModel model, SordIter iter);
 
-/** Remove a graph from the store. */
+/**
+   Remove a graph from the store.
+*/
 SORD_API
 void
 sord_remove_graph(SordModel model, SordNode graph);
 
-/** @} */
-/** @name Iteration
- * @{
- */
+/**
+   @}
+   @name Iteration
+   @{
+*/
 
-/** Set @a id to the quad pointed to by @a iter. */
+/**
+   Set @a id to the quad pointed to by @a iter.
+*/
 SORD_API
 void
 sord_iter_get(SordIter iter, SordQuad quad);
 
-/** Return the store pointed to by @a iter. */
+/**
+   Return the store pointed to by @a iter.
+*/
 SORD_API
 SordModel
 sord_iter_get_model(SordIter iter);
 
-/** Increment @a iter to point to the next statement. */
+/**
+   Increment @a iter to point to the next statement.
+*/
 SORD_API
 bool
 sord_iter_next(SordIter iter);
 
-/** Return true iff @a iter is at the end of its range. */
+/**
+   Return true iff @a iter is at the end of its range.
+*/
 SORD_API
 bool
 sord_iter_end(SordIter iter);
 
-/** Free @a iter. */
+/**
+   Free @a iter.
+*/
 SORD_API
 void
 sord_iter_free(SordIter iter);
 
-/** @} */
-/** @name Utilities
- * @{
- */
+/**
+   @}
+   @name Utilities
+   @{
+*/
 
-/** Match two quads (using ID comparison only).
- * This function is a straightforward and fast equivalence match with wildcard
- * support (ID 0 is a wildcard).  It never performs any database access.
- * @return true iff @a x and @a y match.
- */
+/**
+   Match two quads (using ID comparison only).
+
+   This function is a straightforward and fast equivalence match with wildcard
+   support (ID 0 is a wildcard). It does not actually read node data.
+   @return true iff @a x and @a y match.
+*/
 SORD_API
 bool
 sord_quad_match(const SordQuad x, const SordQuad y);
 
-/** @} */
-/** @name Serialisation
- * @{
- */
+/**
+   @}
+   @name Serialisation
+   @{
+*/
 
 SORD_API
 bool
@@ -366,12 +468,13 @@ sord_write_string(SordModel      model,
                   const uint8_t* base_uri);
 
 
-/** @} */
-
-/** @} */
+/**
+   @}
+   @}
+*/
 
 #ifdef __cplusplus
-} /* extern "C" */
+}  /* extern "C" */
 #endif
 
-#endif // SORD_SORD_H
+#endif  /** SORD_SORD_H */