aboutsummaryrefslogtreecommitdiffstats
path: root/doc/c/statements.rst
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2021-03-28 13:42:35 -0400
committerDavid Robillard <d@drobilla.net>2022-01-28 21:57:29 -0500
commitf8a59da9c492b7df38f53ba96505313e931d76cc (patch)
tree5bf1e44e67f8662894a37fbc84d770585f5957dd /doc/c/statements.rst
parentac0ac05ccf96dee4406db8bdd4d098d3de61c01f (diff)
downloadserd-f8a59da9c492b7df38f53ba96505313e931d76cc.tar.gz
serd-f8a59da9c492b7df38f53ba96505313e931d76cc.tar.bz2
serd-f8a59da9c492b7df38f53ba96505313e931d76cc.zip
Add high-level documentation
Diffstat (limited to 'doc/c/statements.rst')
-rw-r--r--doc/c/statements.rst123
1 files changed, 123 insertions, 0 deletions
diff --git a/doc/c/statements.rst b/doc/c/statements.rst
new file mode 100644
index 00000000..da7b8a03
--- /dev/null
+++ b/doc/c/statements.rst
@@ -0,0 +1,123 @@
+Statements
+==========
+
+.. default-domain:: c
+.. highlight:: c
+
+A :struct:`SerdStatement` is a tuple of either 3 or 4 nodes:
+the `subject`, `predicate`, `object`, and optional `graph`.
+Statements declare that a subject has some property.
+The predicate identifies the property,
+and the object is its value.
+
+A statement can be thought of as a very simple machine-readable sentence.
+The subject and object are as in natural language,
+and the predicate is something like a verb, but more general.
+For example, we could make a statement in English about your intrepid author:
+
+ drobilla has the first name "David"
+
+We can break this statement into 3 pieces like so:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Subject
+ - Predicate
+ - Object
+ * - drobilla
+ - has the first name
+ - "David"
+
+To make a :struct:`SerdStatement` out of this, we need to define some URIs.
+In RDF, the subject and predicate must be *resources* with an identifier
+(for example, neither can be a string).
+Conventionally, predicate names do not start with "has" or similar words,
+since that would be redundant in this context.
+So, we assume that ``http://example.org/drobilla`` is the URI for drobilla,
+and that ``http://example.org/firstName`` has been defined somewhere to be
+a property with the appropriate meaning,
+and can make an equivalent :struct:`SerdStatement`:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin statement-new
+ :end-before: end statement-new
+ :dedent: 2
+
+The last two fields are the graph and the cursor.
+The graph is another node that can be used to group statements,
+for example by the URI of the document they were loaded from.
+The cursor represents the location in a document where the statement was loaded from, if applicable.
+
+Accessing Fields
+----------------
+
+Statement fields can be accessed with
+:func:`serd_statement_node`, for example:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin get-subject
+ :end-before: end get-subject
+ :dedent: 2
+
+Alternatively, an accessor function is provided for each field:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin get-pog
+ :end-before: end get-pog
+ :dedent: 2
+
+Every statement has a subject, predicate, and object,
+but the graph may be null.
+The cursor may also be null (as it would be in this case),
+but if available it can be accessed with :func:`serd_statement_caret`:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin get-caret
+ :end-before: end get-caret
+ :dedent: 2
+
+Comparison
+----------
+
+Two statements can be compared with :func:`serd_statement_equals`:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin statement-equals
+ :end-before: end statement-equals
+ :dedent: 2
+
+Statements are equal if all four corresponding pairs of nodes are equal.
+The cursor is considered metadata, and is ignored for comparison.
+
+It is also possible to match statements against a pattern using ``NULL`` as a wildcard,
+with :func:`serd_statement_matches`:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin statement-matches
+ :end-before: end statement-matches
+ :dedent: 2
+
+Lifetime
+--------
+
+A statement only contains const references to nodes,
+it does not own nodes or manage their lifetimes internally.
+The cursor, however, is owned by the statement.
+A statement can be copied with :func:`serd_statement_copy`:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin statement-copy
+ :end-before: end statement-copy
+ :dedent: 2
+
+The copied statement will refer to exactly the same nodes,
+though the cursor will be deep copied.
+
+In most cases, statements come from a reader or model which manages them internally,
+but a statement owned by the application must be freed with :func:`serd_statement_free`:
+
+.. literalinclude:: overview_code.c
+ :start-after: begin statement-free
+ :end-before: end statement-free
+ :dedent: 2