1 files changed, 124 insertions, 0 deletions
diff --git a/doc/cpp/statements.rst b/doc/cpp/statements.rst
new file mode 100644
index 00000000..a77c8050
--- /dev/null
+++ b/doc/cpp/statements.rst
@@ -0,0 +1,124 @@
+Statements
+==========
+
+.. default-domain:: cpp
+.. highlight:: cpp
+.. namespace:: serd
+
+A :struct:`Statement` 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 on the subject.
+
+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 :class:`Statement` 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 :class:`Statement`:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin statement-new
+   :end-before: end statement-new
+   :dedent: 2
+
+Statements also have an additional field, the graph,
+which is used to group statements together.
+For example, this can be used to store the document where statements originated,
+or to keep schema data separate from application data.
+A statement with a graph can be constructed by passing the graph as the fourth parameter:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin statement-new-graph
+   :end-before: end statement-new-graph
+   :dedent: 2
+
+Finally, a :class:`Caret` may also be passed which records a position in the file that the statement was loaded from.
+This is typically used for printing useful error messages.
+The cursor is considered metadata and not part of the statement itself,
+for example,
+it is not considered in equality comparison.
+Typically, the cursor will be automatically set by a reader,
+but a statement with a cursor can be constructed manually by passing the cursor as the last parameter:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin statement-new-cursor
+   :end-before: end statement-new-cursor
+   :dedent: 2
+
+.. literalinclude:: overview.cpp
+   :start-after: begin statement-new-graph-cursor
+   :end-before: end statement-new-graph-cursor
+   :dedent: 2
+
+
+Accessing Fields
+----------------
+
+Statement fields can be accessed with the :func:`~StatementWrapper::node` method, for example:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin get-subject
+   :end-before: end get-subject
+   :dedent: 2
+
+Alternatively, an accessor function is provided for each field:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin get-pog
+   :end-before: end get-pog
+   :dedent: 2
+
+Every statement has a subject, predicate, and object,
+but the graph is optional.
+The caret is also optional,
+and can be accessed with the :func:`~StatementWrapper::caret` method:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin get-caret
+   :end-before: end get-caret
+   :dedent: 2
+
+Comparison
+----------
+
+Two statements can be compared with the equals operator:
+
+.. literalinclude:: overview.cpp
+   :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 with the :func:`~StatementWrapper::matches` method,
+where empty parameters act as wildcards:
+
+.. literalinclude:: overview.cpp
+   :start-after: begin statement-matches
+   :end-before: end statement-matches
+   :dedent: 2