Bump version to 1.0a4 & housekeeping:

* Fix Python venv in Makefile
* Update some documentation
* Update roadmap in README

Doxyfile

@@ -748,7 +748,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from

Makefile

@@ -1,5 +1,7 @@
 # NOTE: only tested in GNU/Linux.
 
+SHELL := /bin/bash
+
 ## Binary dependencies.
 
 CC = gcc
@@ -162,6 +164,7 @@ clean:
 	rm -f $(LIBS) $(DBG_LIBS)
 	rm -f include/codec/grammar_*.h
 	rm -f src/codec/grammar_*.c src/codec/parser_*.c
+	rm -rf venv/
 
 
 .PHONY: uninstall ## Uninstall library (not the dependencies).
@@ -242,25 +245,34 @@ footprint: bin/perftest ## Measure memory footprint by generating and storing 10
 		"massif-visualizer or similar."
 
 
+venv:
+	test -d venv || python3 -m venv ./venv
+
+
 .PHONY: py
-py: codec  ## Build and install python library.
-	pip3 install build==0.8.0
-	pip3 uninstall -y lsup_rdf
-	python3 -m build
-	pip3 install --no-index --find-links=dist/ lsup_rdf
+py: venv codec  ## Build and install python library.
+	source ./venv/bin/activate && (\
+		pip3 install build~=1.2; \
+		pip3 uninstall -y lsup_rdf; \
+		python3 -m build; \
+		pip3 install --no-index --find-links=dist/ lsup_rdf \
+	)
 
 
 .PHONY: py_dbg
-py_dbg: codec_dbg  ## Build and install python library with debug symbols.
-	pip3 install build==0.8.0
-	pip3 uninstall -y lsup_rdf
-	DEBUG=1 python3 -m build
-	pip3 install --no-index --find-links=dist/ lsup_rdf
+py_dbg: venv codec_dbg  ## Build and install python library with debug symbols.
+	source ./venv/bin/activate && (\
+		pip3 install build~=1.2; \
+		pip3 uninstall -y lsup_rdf; \
+		DEBUG=1 python3 -m build; \
+		pip3 install --no-index --find-links=dist/ lsup_rdf \
+	)
 
 
 .PHONY: pytest
 pytest: py_dbg ## Run a test suite for the Python package.
-	python3 test/cpython_test.py
+	source ./venv/bin/activate && (\
+		python3 test/cpython_test.py )
 
 
 # Requires cinclude2dot (https://www.flourish.org/cinclude2dot) and Graphviz.

README.md

@@ -53,34 +53,32 @@ unpaid fun project, so don't be surprised if you find some gross stuff.
 The short-term goal is to support usage in Lakesuperior and a workable set
 of features as a standalone library:
 
-- Handling of graphs, triples, terms
-- Memory- and disk-backed (persistent) graph storage
-- Contexts (disk-backed only)
-- Handling of blank nodes
-- Namespace prefixes
-- Validation of literal and URI terms
-- Validation of RDF triples
-- Fast graph lookup using matching patterns
-- Graph boolean operations
-- Serialization and de-serialization to/from N-Triples and N-Quads
-- Serialization and de-serialization to/from Turtle and TriG
-- Compile-time configuration of max graph size (efficiency vs. capacity)
-- Python bindings
-- Basic command line utilities
-- Store interface for custom back end implementations
+- ✓ Handling of graphs, triples, terms
+- ✓ Memory- and disk-backed (persistent) graph storage
+- ✓ Contexts (disk-backed only)
+- ⚒ Handling of blank nodes
+- ✓ Namespace prefixes
+- ✓ Validation of literal and URI terms
+- ✓ Validation of RDF triples
+- ✓ Fast graph lookup using matching patterns
+- ✓ Graph boolean operations
+- ✓ Serialization and de-serialization to/from N-Triples and N-Quads
+- ✓ Serialization and de-serialization to/from Turtle and TriG
+- ✓ Compile-time configuration of max graph size (efficiency vs. capacity)
+- ⚒ Python bindings
+- ⚒ Basic command line utilities
+- ⚒ Store interface for custom back end implementations
 
 ### Possibly In scope – Long Term
 
 - Binary serialization and hashing of graphs
 - Binary protocol for synchronizing remote replicas
-- Support for non-local, software-defined storage (e.g. S3)
 - True plug-in architecture for 3rd-party store implementations
 
 ### Likely Out of Scope
 
 (Unless provided and maintained by external contributors)
 
-- C++ bindings
 - JSON-LD de/serialization
 - SPARQL support
 
@@ -88,7 +86,7 @@ of features as a standalone library:
 
 ### Requirements
 
-- It is recommended to build and run LSUP_RDF on a Linux system. No other
+- It is recommended to build and run `lsup_rdf` on a Linux system. No other
   OS has been tested so far.
 - A C compiler. This has been only tested with `gcc` so far.
 - [LMDB](https://symas.com/lmdb/) libraries and headers.

include/buffer.h

@@ -44,19 +44,19 @@ typedef enum {
 } LSUP_TriplePos;
 
 
-/** Initialize or reuse a buffer handle.
+/** @brief Initialize or reuse a buffer handle.
  *
  * The handle must have been created with #LSUP_buffer_new*().
  *
  * The data block is resized without being freed first. The handle must be
  * eventually freed with #LSUP_buffer_done() after use.
  *
- * @param buf[in] A buffer handle obtained with #LSUP_buffer_new or by manual
+ * @param[in] buf A buffer handle obtained with #LSUP_buffer_new or by manual
  *  allocation.
  *
- * @param size[in] New size.
+ * @param[in] size New size.
  *
- * @param data[in] If not NULL, data to replace the existing ones. The size
+ * @param[in] data If not NULL, data to replace the existing ones. The size
  *  of the data to be copied is determined by the size parameter. If NULL, the
  *  existing data are preserved as with a normal realloc().
  */
@@ -71,9 +71,9 @@ LSUP_buffer_init (
  *
  * To copy a buffer just do buf2 = LSUP_buffer_new (buf1->addr, buf1->size);
  *
- * @param size[in] Length of the data.
+ * @param[in] size Length of the data.
  *
- * @param data[in] Optional data to initially populate the object with. If
+ * @param[in] data Optional data to initially populate the object with. If
  *  NULL, the buffer data are garbage.
  *
  * @return LSUP_Buffer pointer. It must be freed with #LSUP_buffer_free. NULL
@@ -132,7 +132,7 @@ void LSUP_buffer_print (const LSUP_Buffer *buf);
  *
  * The string has non-printable characters escaped as "\xNN".
  *
- * @param buf[in] Buffer to convert.
+ * @param[in] buf Buffer to convert.
  *
  * @return Formatted string. It must be freed with free().
  */
@@ -169,15 +169,37 @@ inline bool LSUP_buffer_eq (const LSUP_Buffer *buf1, const LSUP_Buffer *buf2)
  * Buffer triples.
  */
 
+/** @brief Create a new buffer triple.
+ *
+ * @important The triple must be freed with #LSUP_btriple_free().
+ *
+ * @param[in] sspo Serialized triple pointer to initialize.
+ *
+ * @param[in] s Subject as a serialized buffer.
+ *
+ * @param[in] p Predicate as a serialized buffer.
+ *
+ * @param[in] o Object as a serialized buffer.
+ *
+ * @return New triple.
+ */
 LSUP_BufferTriple *
 LSUP_btriple_new(LSUP_Buffer *s, LSUP_Buffer *p, LSUP_Buffer *o);
 
 
 /** @brief Initialize internal term pointers in a heap-allocated buffer triple.
  *
- * The triple must be freed with #LSUP_btriple_free().
+ * @important The triple must be freed with #LSUP_btriple_free().
  *
- * @param sspo[in] Serialized triple pointer to initialize.
+ * @param[in] sspo Serialized triple pointer to initialize.
+ *
+ * @param[in] s Subject as a serialized buffer.
+ *
+ * @param[in] p Predicate as a serialized buffer.
+ *
+ * @param[in] o Object as a serialized buffer.
+ *
+ * @return LSUP_OK on success.
  */
 LSUP_rc
 LSUP_btriple_init (
@@ -187,7 +209,7 @@ LSUP_btriple_init (
 
 /** @brief Free the internal pointers of a buffer triple.
  *
- * @param sspo[in] Buffer triple to be freed.
+ * @param[in] sspo Buffer triple to be freed.
  */
 void
 LSUP_btriple_done (LSUP_BufferTriple *sspo);
@@ -195,10 +217,10 @@ LSUP_btriple_done (LSUP_BufferTriple *sspo);
 
 /** @brief Free a buffer triple and all its internal pointers.
  *
- * NOTE: If the buffer pointers are not to be freed (e.g. they are owned by a
- * back end), use a simple free(sspo) instead of this.
+ * @important If the buffer pointers are not to be freed (e.g. they are owned
+ * by a back end), use a simple free(sspo) instead of this.
  *
- * @param sspo[in] Buffer triple to be freed.
+ * @param[in] sspo Buffer triple to be freed.
  */
 void
 LSUP_btriple_free (LSUP_BufferTriple *sspo);
@@ -218,9 +240,9 @@ LSUP_btriple_free_shallow (LSUP_BufferTriple *sspo);
  *
  * Useful for looping over all terms.
  *
- * @param trp[in] Serialized triple pointer.
+ * @param[in] btrp Serialized triple pointer.
  *
- * @param n[in] A number between 0÷2.
+ * @param[in] n A number between 0÷2.
  *
  * @return Corresponding serialized term or NULL if n is out of range.
  */
@@ -237,7 +259,12 @@ LSUP_btriple_pos (const LSUP_BufferTriple *btrp, LSUP_TriplePos n)
 
 /** @brief Hash a buffer triple.
  *
- * TODO This doesn't handle blank nodes correctly.
+ * @todo This doesn't handle blank nodes correctly. RDF_Canon should be ported
+ * to this library.
+ *
+ * @param[in] strp Serialized triple to hash.
+ *
+ * @return Hash value.
  */
 inline LSUP_Key
 LSUP_btriple_hash (const LSUP_BufferTriple *strp)

include/codec.h

@@ -71,8 +71,8 @@ typedef LSUP_rc (*term_enc_fn_t)(
  * the codec for namespace prefixing. The graph may only be freed after the
  * loop is finalized.
  *
- * @return A codec iterator handle to be passed to a #gr_codec_iter_fn_t
- * function and, eventually, to a #gr_codec_done_fn_t function. This
+ * @return A codec iterator handle to be passed to a #gr_encode_iter_fn_t
+ * function and, eventually, to a #gr_encode_done_fn_t function. This
  * structure is opaque and defined by each codec according to its own needs.
  */
 typedef void * (*gr_encode_init_fn_t)(const LSUP_Graph *gr);
@@ -220,7 +220,7 @@ inline uint8_t
  *
  * @param[in] in Input string.
  *
- * @param out[out] Output string.
+ * @param[out] out Output string.
  *
  * @return LSUP_OK on success; LSUP_MEM_ERR on memory error.
  */
@@ -271,7 +271,7 @@ unescape_char (const char c)
 }
 
 
-/** @brief Replace \uxxxx and \Uxxxxxxxx with Unicode bytes.
+/** @brief Replace `\uxxxx` and `\Uxxxxxxxx` with Unicode bytes.
  *
  * @param[in] esc_str Escaped string.
  *

include/codec/parser_nt.h

@@ -22,16 +22,18 @@ LSUP_nt_parse_term (const char *rep, const LSUP_NSMap *map, LSUP_Term **term);
 
 /** @brief Parse a N-Triples document from a file handle.
  *
- * @param[in] doc N-Triples document.
+ * @param[in] stream N-Triples doc file handler.
  *
- * @param[out] Pointer to a graph handle to be created. The new graph will have
- *  a random UUID URN.
+ * @param[out] gr Pointer to a graph handle to be created. The new graph will
+ * have a random UUID URN.
  *
  * @param[out] ct If not NULL it is populated with the number of triples
  *  parsed. This may be more than the triples in the resulting graph.
  *
+ * @param[out] err String handle to be populated with an error message.
+ *
  * @return LSUP_OK on success, LSUP_VALUE_ERR if a parsing error was
- *  encountered. TODO Add line/char info for parsing error
+ *  encountered. On error, `err` will contain the error message.
  */
 LSUP_rc
 LSUP_nt_parse_doc (FILE *stream, LSUP_Graph **gr, size_t *ct, char **err);

include/codec/parser_ttl.h

@@ -8,14 +8,16 @@
  *
  * @param[in] doc N-Triples document.
  *
- * @param[out] Pointer to a graph handle to be created. The new graph will have
- *  a random UUID URN.
+ * @param[out] gr Pointer to a graph handle to be created. The new graph will
+ * have a random UUID URN.
  *
  * @param[out] ct If not NULL it is populated with the number of triples
  *  parsed. This may be more than the triples in the resulting graph.
  *
+ * @param[out] err String handle to be populated with an error message.
+ *
  * @return LSUP_OK on success, LSUP_VALUE_ERR if a parsing error was
- *  encountered. TODO Add line/char info for parsing error
+ *  encountered. On error, `err` will contain the error message.
  */
 LSUP_rc
 LSUP_ttl_parse_doc (FILE *stream, LSUP_Graph **gr, size_t *ct, char **err);

include/core.h

@@ -235,7 +235,7 @@ LSUP_strerror (LSUP_rc rc);
  *
  * @author Ondřej Hruška <ondra@ondrovo.com>
  *
- * @license MIT
+ * @copyright MIT
  *
  * @param out - output buffer (min 5 characters), will be 0-terminated
  * @param utf - code point 0-0x10FFFF

include/environment.h

@@ -31,8 +31,8 @@ extern LSUP_Buffer *LSUP_default_ctx_buf; /// Serialized default context.
  * The default environment is cleaned up automatically on exit.
  *
  * This environment should suit most cases, unless an application needs to use
- * multiple environments and call #LSUP_env_init with specific handles. Such
- * other environment(s) must be freed up manually with #LSUP_env_done().
+ * multiple environments and call #LSUP_init with specific handles. Such
+ * other environment(s) must be freed up manually with #LSUP_done().
  */
 LSUP_rc
 LSUP_init (void);

include/graph.h

@@ -201,7 +201,7 @@ LSUP_graph_add_init_txn (void *txn, LSUP_Graph *gr);
 
 /** @brief Add a single triple to the store.
  *
- * @param[in] it Iterator obtained with #LSUP_graph_add_init().
+ * @param[in] it Iterator obtained with #LSUP_graph_add_init_txn().
  *
  * @param[in] spo Triple to add. Caller retains ownership.
  */
@@ -211,7 +211,8 @@ LSUP_graph_add_iter (LSUP_GraphIterator *it, const LSUP_Triple *spo);
 
 /** @brief Finalize an add iteration loop and free the iterator.
  *
- * DO NOT USE with iterators obtained with other than #LSUP_graph_add_init().
+ * DO NOT USE with iterators obtained with other than
+ * #LSUP_graph_add_init_txn().
  *
  * @param[in] it Iterator to finalize.
  */
@@ -260,7 +261,7 @@ LSUP_graph_remove_txn (
 #define LSUP_graph_remove(...) LSUP_graph_remove_txn (NULL, __VA_ARGS__)
 
 
-/** Look up triples by a matching pattern and yield an iterator.
+/** @brief Look up triples by a matching pattern and yield an iterator.
  *
  * @param[in] txn Transaction handle. It may be NULL.
  *
@@ -304,7 +305,7 @@ LSUP_graph_iter_graph (LSUP_GraphIterator *it);
 
 /** @brief Free a graph iterator.
  *
- * DO NOT USE with iterators obtained with #LSUP_graph_add_init(). Use
+ * DO NOT USE with iterators obtained with #LSUP_graph_add_init_txn(). Use
  * #LSUP_graph_add_done() with those.
  *
  * @param[in] it Iterator to finalize.
@@ -371,7 +372,7 @@ LSUP_graph_unique_terms (const LSUP_Graph *gr, LSUP_TriplePos pos);
  * that, triples are added with the given term as the subject, the predicate,
  * or the object.
  *
- * @param[in] it Graph iterator obtained with #LSUP_graph_add_init().
+ * @param[in] it Graph iterator obtained with #LSUP_graph_add_init_txn().
  *
  * @param[in] t Term to be associated with the collection list.
  *
@@ -391,7 +392,7 @@ LSUP_graph_add_link_map (
  *
  * @param[in] it Graph iterator to use for insertion.
  *
- * @param[in] ol NUL-terminated term array.
+ * @param[in] ts Source term set.
  *
  * @return Blank node representing the first list item.
  */

include/lsup_rdf.h

@@ -4,4 +4,4 @@
 #include "codec/codec_nt.h"
 #include "codec/codec_ttl.h"
 
-#endif
+#endif  // _LSUP_RDF_H

include/term.h

@@ -222,10 +222,10 @@ LSUP_iriref_absolute (const LSUP_Term *root, const LSUP_Term *iri);
  * This works with namespace-prefixed IRIs and returns a term of the same type
  * as the input.
  *
- * @param[in] iri Full IRI.
- *
  * @param[in] root Root IRI that the new IRI should be relative to.
  *
+ * @param[in] iri Full IRI.
+ *
  * @return New IRI, or NULL if either term is not an IRI. If the input IRI is
  * not a path under the root IRI, the result will be identical to the input.
  */

setup.py

@@ -80,7 +80,7 @@ class LSUPInstallCmd(install):
 
 setup(
     name="lsup_rdf",
-    version="1.0a3",
+    version="1.0a4",
     description="Ultra-compact RDF library.",
     # long_description=long_description,
     # long_description_content_type="text/markdown",

src/codec/lexer_nt.re

@@ -282,7 +282,7 @@ LSUP_nt_parse_doc (FILE *fh, LSUP_Graph **gr_p, size_t *ct, char **err_p)
         int ttype = lex (&parse_it, &term);
 
         if (ttype == -1) {
-            char token[16] = {'\0'};
+            char token[16] = {};
             strncpy (token, (const char *)parse_it.tok, 15);
 
             char *err_start = "Parse error near token `";