aboutsummaryrefslogtreecommitdiffstats
path: root/doc/c/overview_code.c
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/overview_code.c
parentac0ac05ccf96dee4406db8bdd4d098d3de61c01f (diff)
downloadserd-f8a59da9c492b7df38f53ba96505313e931d76cc.tar.gz
serd-f8a59da9c492b7df38f53ba96505313e931d76cc.tar.bz2
serd-f8a59da9c492b7df38f53ba96505313e931d76cc.zip
Add high-level documentation
Diffstat (limited to 'doc/c/overview_code.c')
-rw-r--r--doc/c/overview_code.c459
1 files changed, 459 insertions, 0 deletions
diff --git a/doc/c/overview_code.c b/doc/c/overview_code.c
new file mode 100644
index 00000000..0b7b5600
--- /dev/null
+++ b/doc/c/overview_code.c
@@ -0,0 +1,459 @@
+/*
+ Copyright 2021 David Robillard <d@drobilla.net>
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/*
+ Example code that is included in the documentation. Code in the
+ documentation is included from here rather than written inline so that it can
+ be tested and avoid rotting. The code here doesn't make much sense, but is
+ written such that it at least compiles and will run without crashing.
+*/
+
+#include "serd/serd.h"
+
+#include <assert.h>
+#include <stdbool.h>
+#include <stdio.h>
+
+#if defined(__GNUC__)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wunused-variable"
+#endif
+
+static void
+string_views(void)
+{
+ static const char* const string_pointer = "some string";
+
+ // begin make-empty-string
+ SerdStringView empty = SERD_EMPTY_STRING();
+ // end make-empty-string
+
+ // begin make-static-string
+ SerdStringView hello = SERD_STRING("hello");
+ // end make-static-string
+
+ // begin measure-string
+ SerdStringView view = SERD_STRING(string_pointer);
+ // end measure-string
+
+ // begin make-string-view
+ SerdStringView slice = SERD_SUBSTRING(string_pointer, 4);
+ // end make-string-view
+}
+
+static void
+statements(void)
+{
+ SerdNodes* nodes = serd_nodes_new(NULL);
+
+ // begin statement-new
+ SerdStatement* statement = serd_statement_new(
+ NULL,
+ serd_nodes_uri(nodes, SERD_STRING("http://example.org/drobilla")),
+ serd_nodes_uri(nodes, SERD_STRING("http://example.org/firstName")),
+ serd_nodes_string(nodes, SERD_STRING("David")),
+ NULL,
+ NULL);
+ // end statement-new
+
+ serd_statement_free(NULL, statement);
+ serd_nodes_free(nodes);
+}
+
+static void
+statements_accessing_fields(void)
+{
+ SerdNode* ss = serd_new_uri(NULL, SERD_STRING("http://example.org/s"));
+ SerdNode* sp = serd_new_uri(NULL, SERD_STRING("http://example.org/p"));
+ SerdNode* so = serd_new_uri(NULL, SERD_STRING("http://example.org/o"));
+
+ SerdStatement* statement = serd_statement_new(NULL, ss, sp, so, NULL, NULL);
+
+ // begin get-subject
+ const SerdNode* s = serd_statement_node(statement, SERD_SUBJECT);
+ // end get-subject
+
+ // begin get-pog
+ const SerdNode* p = serd_statement_predicate(statement);
+ const SerdNode* o = serd_statement_object(statement);
+ const SerdNode* g = serd_statement_graph(statement);
+ // end get-pog
+
+ // begin get-caret
+ const SerdCaret* c = serd_statement_caret(statement);
+ // end get-caret
+}
+
+static void
+statements_comparison(void)
+{
+ SerdNode* ss = serd_new_uri(NULL, SERD_STRING("http://example.org/s"));
+ SerdNode* sp = serd_new_uri(NULL, SERD_STRING("http://example.org/p"));
+ SerdNode* so = serd_new_uri(NULL, SERD_STRING("http://example.org/o"));
+
+ SerdStatement* statement1 = serd_statement_new(NULL, ss, sp, so, NULL, NULL);
+ SerdStatement* statement2 = serd_statement_new(NULL, ss, sp, so, NULL, NULL);
+
+ // begin statement-equals
+ if (serd_statement_equals(statement1, statement2)) {
+ printf("Match\n");
+ }
+ // end statement-equals
+
+ SerdStatement* statement = statement1;
+
+ // begin statement-matches
+ SerdNode* eg_name =
+ serd_new_uri(NULL, SERD_STRING("http://example.org/name"));
+
+ if (serd_statement_matches(statement, NULL, eg_name, NULL, NULL)) {
+ printf("%s has name %s\n",
+ serd_node_string(serd_statement_subject(statement)),
+ serd_node_string(serd_statement_object(statement)));
+ }
+ // end statement-matches
+}
+
+static void
+statements_lifetime(void)
+{
+ SerdStatement* statement = NULL;
+
+ // begin statement-copy
+ SerdStatement* copy = serd_statement_copy(NULL, statement);
+ // end statement-copy
+
+ // begin statement-free
+ serd_statement_free(NULL, copy);
+ // end statement-free
+}
+
+static void
+world(void)
+{
+ // begin world-new
+ SerdWorld* world = serd_world_new(NULL);
+ // end world-new
+
+ // begin get-blank
+ const SerdNode* world_blank = serd_world_get_blank(world);
+ SerdNode* my_blank = serd_node_copy(NULL, world_blank);
+ // end get-blank
+}
+
+static void
+model(void)
+{
+ SerdWorld* world = serd_world_new(NULL);
+
+ // begin model-new
+ SerdModel* model = serd_model_new(world, SERD_ORDER_SPO, 0u);
+ // end model-new
+
+ // begin fancy-model-new
+ SerdModel* fancy_model =
+ serd_model_new(world, SERD_ORDER_SPO, SERD_STORE_CARETS);
+
+ serd_model_add_index(fancy_model, SERD_ORDER_PSO);
+ // end fancy-model-new
+
+ // begin model-copy
+ SerdModel* copy = serd_model_copy(NULL, model);
+
+ assert(serd_model_equals(copy, model));
+ // end model-copy
+
+ // begin model-size
+ if (serd_model_empty(model)) {
+ printf("Model is empty\n");
+ } else if (serd_model_size(model) > 1000) {
+ printf("Model has over 1000 statements\n");
+ }
+ // end model-size
+
+ // begin model-free
+ serd_model_free(copy);
+ // end model-free
+
+ // begin model-add
+ SerdNodes* nodes = serd_nodes_new(NULL);
+
+ serd_model_add(
+ model,
+ serd_nodes_uri(nodes, SERD_STRING("http://example.org/thing")), // S
+ serd_nodes_uri(nodes, SERD_STRING("http://example.org/name")), // P
+ serd_nodes_string(nodes, SERD_STRING("Thing")), // O
+ NULL); // G
+ // end model-add
+
+ SerdModel* other_model = model;
+
+ // begin model-insert
+ const SerdCursor* cursor = serd_model_begin(other_model);
+
+ serd_model_insert(model, serd_cursor_get(cursor));
+ // end model-insert
+
+ // begin model-add-range
+ SerdCursor* other_range = serd_model_begin(other_model);
+
+ serd_model_insert_statements(model, other_range);
+
+ serd_cursor_free(other_range);
+ // end model-add-range
+
+ // begin model-begin-end
+ SerdCursor* i = serd_model_begin(model);
+ if (serd_cursor_equals(i, serd_model_end(model))) {
+ printf("Model is empty\n");
+ } else {
+ const SerdStatement* s = serd_cursor_get(i);
+
+ printf("First statement subject: %s\n",
+ serd_node_string(serd_statement_subject(s)));
+ }
+ // end model-begin-end
+
+ // begin iter-next
+ if (!serd_cursor_advance(i)) {
+ const SerdStatement* s = serd_cursor_get(i);
+
+ printf("Second statement subject: %s\n",
+ serd_node_string(serd_statement_subject(s)));
+ }
+ // end iter-next
+
+ // begin iter-free
+ serd_cursor_free(i);
+ // end iter-free
+
+ // begin model-all
+ SerdCursor* all = serd_model_begin(model);
+ // end model-all
+
+ // begin range-next
+ if (serd_cursor_is_end(all)) {
+ printf("Model is empty\n");
+ } else {
+ const SerdStatement* s = serd_cursor_get(all);
+
+ printf("First statement subject: %s\n",
+ serd_node_string(serd_statement_subject(s)));
+ }
+
+ if (!serd_cursor_advance(all)) {
+ const SerdStatement* s = serd_cursor_get(all);
+
+ printf("Second statement subject: %s\n",
+ serd_node_string(serd_statement_subject(s)));
+ }
+ // end range-next
+
+ // begin model-ask
+ const SerdNode* rdf_type = serd_nodes_uri(
+ nodes, SERD_STRING("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"));
+
+ if (serd_model_ask(model, NULL, rdf_type, NULL, NULL)) {
+ printf("Model contains a type statement\n");
+ }
+ // end model-ask
+
+ // Add a statement so that the searching examples below work
+ SerdNode* inst = serd_new_uri(NULL, SERD_STRING("http://example.org/i"));
+ SerdNode* type = serd_new_uri(NULL, SERD_STRING("http://example.org/T"));
+ serd_model_add(model, inst, rdf_type, type, NULL);
+
+ // begin model-find
+ SerdCursor* it = serd_model_find(model, NULL, rdf_type, NULL, NULL);
+
+ const SerdStatement* statement = serd_cursor_get(it);
+ const SerdNode* instance =
+ statement ? serd_statement_subject(statement) : NULL;
+ // end model-find
+
+ // begin model-count
+ size_t n = serd_model_count(model, instance, rdf_type, NULL, NULL);
+ printf("Instance has %zu types\n", n);
+ // end model-count
+
+ // begin model-range
+ SerdCursor* range = serd_model_find(model,
+ instance, // Subject = instance
+ rdf_type, // Predicate = rdf:type
+ NULL, // Object = anything
+ NULL); // Graph = anything
+
+ for (; !serd_cursor_is_end(range); serd_cursor_advance(range)) {
+ const SerdStatement* s = serd_cursor_get(range);
+
+ printf("Instance has type %s\n",
+ serd_node_string(serd_statement_object(s)));
+ }
+
+ serd_cursor_free(range);
+ // end model-range
+
+ // begin model-get
+ const SerdNode* t = serd_model_get(model,
+ instance, // Subject
+ rdf_type, // Predicate
+ NULL, // Object
+ NULL); // Graph
+ if (t) {
+ printf("Instance has type %s\n", serd_node_string(t));
+ }
+ // end model-get
+
+ // begin model-get-statement
+ const SerdStatement* ts =
+ serd_model_get_statement(model, instance, rdf_type, NULL, NULL);
+
+ if (ts) {
+ printf("Instance %s has type %s\n",
+ serd_node_string(serd_statement_subject(ts)),
+ serd_node_string(serd_statement_object(ts)));
+ }
+ // end model-get-statement
+
+ // begin model-erase
+ SerdCursor* some_type = serd_model_find(model, NULL, rdf_type, NULL, NULL);
+ serd_model_erase(model, some_type);
+ serd_cursor_free(some_type);
+ // end model-erase
+
+ // begin model-erase-range
+ SerdCursor* all_types = serd_model_find(model, NULL, rdf_type, NULL, NULL);
+ serd_model_erase_statements(model, all_types);
+ serd_cursor_free(all_types);
+ // end model-erase-range
+}
+
+static void
+reading_writing(void)
+{
+ SerdWorld* world = serd_world_new(NULL);
+
+ // begin env-new
+ SerdStringView host = SERD_EMPTY_STRING();
+ SerdStringView path = SERD_STRING("/some/file.ttl");
+ SerdNode* base = serd_new_file_uri(NULL, path, host);
+ SerdEnv* env = serd_env_new(world, serd_node_string_view(base));
+ // end env-new
+
+ // begin env-set-prefix
+ serd_env_set_prefix(
+ env,
+ SERD_STRING("rdf"),
+ SERD_STRING("http://www.w3.org/1999/02/22-rdf-syntax-ns#"));
+ // end env-set-prefix
+
+ // begin byte-sink-new
+ SerdOutputStream out = serd_open_output_file("/tmp/eg.ttl");
+ // end byte-sink-new
+
+ // clang-format off
+ // begin writer-new
+ SerdWriter* writer = serd_writer_new(
+ world, // World
+ SERD_TURTLE, // Syntax
+ 0, // Writer flags
+ env, // Environment
+ &out, // Output stream
+ 4096); // Block size
+ // end writer-new
+
+ // begin reader-new
+ SerdReader* reader = serd_reader_new(
+ world, // World
+ SERD_TURTLE, // Syntax
+ 0, // Reader flags
+ env, // Environment
+ serd_writer_sink(writer), // Target sink
+ 4096); // Block size
+ // end reader-new
+
+ // clang-format on
+
+ // begin read-document
+ SerdStatus st = serd_reader_read_document(reader);
+ if (st) {
+ printf("Error reading document: %s\n", serd_strerror(st));
+ }
+ // end read-document
+
+ // begin reader-writer-free
+ serd_reader_free(reader);
+ serd_writer_free(writer);
+ // end reader-writer-free
+
+ // begin byte-sink-free
+ serd_close_output(&out);
+ // end byte-sink-free
+
+ // begin inserter-new
+ SerdModel* model = serd_model_new(world, SERD_ORDER_SPO, 0u);
+ SerdSink* inserter = serd_inserter_new(model, NULL);
+ // end inserter-new
+
+ // begin model-reader-new
+ SerdReader* const model_reader =
+ serd_reader_new(world, SERD_TURTLE, 0, env, inserter, 4096);
+
+ st = serd_reader_read_document(model_reader);
+ if (st) {
+ printf("Error loading model: %s\n", serd_strerror(st));
+ }
+ // end model-reader-new
+
+ // begin write-range
+ serd_describe_range(serd_model_begin(model), serd_writer_sink(writer), 0);
+ // end write-range
+
+ // begin canon-new
+ SerdSink* canon = serd_canon_new(world, inserter, 0);
+ // end canon-new
+
+ SerdNode* rdf_type = NULL;
+
+ // begin filter-new
+ SerdSink* filter = serd_filter_new(world, // World
+ inserter, // Target
+ NULL, // Subject
+ rdf_type, // Predicate
+ NULL, // Object
+ NULL, // Graph
+ true); // Inclusive
+ // end filter-new
+}
+
+int
+main(void)
+{
+ string_views();
+ statements();
+ statements_accessing_fields();
+ statements_comparison();
+ statements_lifetime();
+ world();
+ model();
+ reading_writing();
+
+ return 0;
+}
+
+#if defined(__GNUC__)
+# pragma GCC diagnostic pop
+#endif