Merge branch 'tintou/doc-build-examples' into 'master'

libtracker-sparql: Extract the examples to their own files

See merge request GNOME/tracker!127

7 files changed, 266 insertions, 222 deletions

diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
index 34aea4d6e..2f0a07885 100644
--- a/docs/reference/libtracker-sparql/examples.xml
+++ b/docs/reference/libtracker-sparql/examples.xml
@@ -1,4 +1,8 @@
 <?xml version='1.0' encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2001/XInclude'">
+]>
 
 <part id="tracker-examples">
   <title>Examples</title>
@@ -20,56 +24,18 @@
     </para>
 
     <para>
-<programlisting>
-#include &lt;tracker-sparql.h&gt;
-
-int main (int argc, char **argv)
-{
-  <type><link linkend="TrackerSparqlBuilder-struct">TrackerSparqlBuilder</link></type> *builder;
-  const gchar *iri = "urn:example:0001";
-  const gchar *query_str;
-  time_t now;
-
-  /* Create builder */
-  builder = <function><link linkend="tracker-sparql-builder-new-update">tracker_sparql_builder_new_update</link></function> ();
-
-  /* Insert new data */
-  <function><link linkend="tracker-sparql-builder-insert-open">tracker_sparql_builder_insert_open</link></function> (builder, NULL);
-
-  <function><link linkend="tracker-sparql-builder-subject-iri">tracker_sparql_builder_subject_iri</link></function> (builder, iri);
-
-  <function><link linkend="tracker-sparql-builder-predicate">tracker_sparql_builder_predicate</link></function> (builder, "a");
-  <function><link linkend="tracker-sparql-builder-object">tracker_sparql_builder_object</link></function> (builder, "nie:DataObject");
-  <function><link linkend="tracker-sparql-builder-object">tracker_sparql_builder_object</link></function> (builder, "nfo:FileDataObject");
-
-  now = time (NULL);
-  <function><link linkend="tracker-sparql-builder-predicate">tracker_sparql_builder_predicate</link></function> (builder, "nfo:fileLastModified");
-  <function><link linkend="tracker-sparql-builder-object-date">tracker_sparql_builder_object_date</link></function> (builder, &amp;now);
-
-  <function><link linkend="tracker-sparql-builder-insert-close">tracker_sparql_builder_insert_close</link></function> (builder);
-
-  /* Get query as string. Do NOT g_free() the resulting string! */
-  query_str = <function><link linkend="tracker-sparql-builder-get-result">tracker_sparql_builder_get_result</link></function> (builder);
-
-  /* Print it */
-  g_print ("Generated SPARQL query: '%s'\n", query_str);
-
-  /* Once builder no longer needed, unref it. Note that after
-   * this operation, you must not use the returned query result
-   * any more
-   */
-  g_object_unref (builder);
-
-  return 0;
-}
-</programlisting>
+    <informalexample>
+      <programlisting language="C">
+        <xi:include href="builder-example.c" parse="text"/>
+      </programlisting>
+    </informalexample>
 
       The previous code will generate the following SPARQL query:
 <programlisting>
-  DROP GRAPH &lt;urn:example:0001&gt;
-  INSERT INTO &lt;urn:example:0001&gt; {
-    &lt;urn:example:0001&gt; a nie:DataObject , nfo:FileDataObject ;
-                       nfo:fileLastModified "2010-08-04T13:09:26Z" .
+DROP GRAPH &lt;urn:example:0001&gt;
+INSERT INTO &lt;urn:example:0001&gt; {
+  &lt;urn:example:0001&gt; a nie:DataObject , nfo:FileDataObject ;
+                     nfo:fileLastModified "2010-08-04T13:09:26Z" .
 }
 </programlisting>
     </para>
@@ -106,64 +72,11 @@ int main (int argc, char **argv)
     <para>
       The following program shows how Read-Only queries can be done to the store in a
       synchronous way:
-
-<programlisting>
-#include &lt;tracker-sparql.h&gt;
-
-int main (int argc, const char **argv)
-{
-  GError *error = NULL;
-  <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> *connection;
-  <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type> *cursor;
-  const gchar *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject }";
-
-  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (NULL, &amp;error);
-  if (!connection) {
-    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
-                error ? error-&gt;message : "unknown error");
-    g_clear_error (&amp;error);
-
-    return 1;
-  }
-
-  /* Make a synchronous query to the store */
-  cursor = <function><link linkend="tracker-sparql-connection-query">tracker_sparql_connection_query</link></function> (connection,
-                                            query,
-                                            NULL,
-                                            &amp;error);
-
-  if (error) {
-    /* Some error happened performing the query, not good */
-    g_printerr ("Couldn't query the Tracker Store: '%s'",
-                error ? error-&gt;message : "unknown error");
-    g_clear_error (&amp;error);
-
-    return 1;
-  }
-
-  /* Check results... */
-  if (!cursor) {
-    g_print ("No results found :-/\n");
-  } else {
-    gint i = 0;
-
-    /* Iterate, synchronously, the results... */
-    while (<function><link linkend="tracker-sparql-cursor-next">tracker_sparql_cursor_next</link></function> (cursor, NULL, &amp;error)) {
-      g_print ("Result [%d]: %s\n",
-	       i++,
-	       <function><link linkend="tracker-sparql-cursor-get-string">tracker_sparql_cursor_get_string</link></function> (cursor, 0, NULL));
-    }
-
-    g_print ("A total of '%d' results were found\n", i);
-
-    g_object_unref (cursor);
-  }
-
-  g_object_unref (connection);
-
-  return 0;
-}
-</programlisting>
+      <informalexample>
+        <programlisting language="C">
+          <xi:include href="readonly-example.c" parse="text"/>
+        </programlisting>
+      </informalexample>
     </para>
   </chapter>
 
@@ -189,57 +102,11 @@ int main (int argc, const char **argv)
 
     <para>
       The following program shows how a synchronous update can be done to the store:
-
-<programlisting>
-#include &lt;tracker-sparql.h&gt;
-
-int main (int argc, const char **argv)
-{
-  GError *error = NULL;
-  <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> *connection;
-  const gchar *query =
-    "INSERT { "
-    "  _:tag a nao:Tag ; "
-    "        nao:prefLabel 'mylabel' . "
-    "} WHERE { "
-    "  OPTIONAL { "
-    "    ?tag a nao:Tag ; "
-    "    nao:prefLabel 'mylabel' "
-    "  } . "
-    "FILTER (!bound(?tag)) "
-    "}";
-
-  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (NULL, &amp;error);
-  if (!connection) {
-    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
-                error ? error-&gt;message : "unknown error");
-    g_clear_error (&amp;error);
-
-    return 1;
-  }
-
-  /* Run a synchronous update query */
-  <function><link linkend="tracker-sparql-connection-update">tracker_sparql_connection_update</link></function> (connection,
-                                            query,
-                                            G_PRIORITY_DEFAULT,
-                                            NULL,
-                                            &amp;error);
-  if (error) {
-    /* Some error happened performing the query, not good */
-    g_printerr ("Couldn't update the Tracker store: %s",
-                error ? error-&gt;message : "unknown error");
-
-    g_clear_error (&amp;error);
-    g_object_unref (connection);
-
-    return 1;
-  }
-
-  g_object_unref (connection);
-
-  return 0;
-}
-</programlisting>
+      <informalexample>
+        <programlisting language="C">
+          <xi:include href="writeonly-example.c" parse="text"/>
+        </programlisting>
+      </informalexample>
     </para>
   </chapter>
 
@@ -286,71 +153,11 @@ int main (int argc, const char **argv)
 
     <para>
       The following program shows how a synchronous blank node update can be done to the store:
-
-<programlisting>
-#include &lt;tracker-sparql.h&gt;
-
-int main (int argc, const char **argv)
-{
-  GError *error = NULL;
-  GVariant *v;
-  <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> *connection;
-  const gchar *query =
-    "INSERT { _:foo a nie:InformationElement } WHERE { ?x a rdfs:Class }";
-
-  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (NULL, &amp;error);
-  if (!connection) {
-    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
-                error ? error-&gt;message : "unknown error");
-    g_clear_error (&amp;error);
-
-    return 1;
-  }
-
-  /* Run a synchronous blank node update query */
-  v = <function><link linkend="tracker-sparql-connection-update-blank">tracker_sparql_connection_update_blank</link></function> (connection,
-  				              query,
-  				              G_PRIORITY_DEFAULT,
-  				              NULL,
-  				              &amp;error);
-
-  if (error) {
-    /* Some error happened performing the query, not good */
-    g_printerr ("Couldn't update the Tracker store: %s",
-                error ? error-&gt;message : "unknown error");
-
-    g_clear_error (&amp;error);
-    g_object_unref (connection);
-
-    return 1;
-  }
-
-  if (!v) {
-    g_print ("No results were returned\n");
-  } else {
-    GVariantIter iter1, *iter2, *iter3;
-    const gchar *node;
-    const gchar *urn;
-
-    g_print ("Results:\n");
-
-    g_variant_iter_init (&amp;iter1, v);
-    while (g_variant_iter_loop (&amp;iter1, "aa{ss}", &amp;iter2)) { /* aa{ss} */
-      while (g_variant_iter_loop (iter2, "a{ss}", &amp;iter3)) { /* a{ss} */
-        while (g_variant_iter_loop (iter3, "{ss}", &amp;node, &amp;urn)) { /* {ss} */
-	  g_print ("  Node:'%s', URN:'%s'\n", node, urn);
-	}
-      }
-    }
-
-    g_variant_unref (v);
-  }
-
-  g_object_unref (connection);
-
-  return 0;
-}
-</programlisting>
+      <informalexample>
+        <programlisting language="C">
+          <xi:include href="writeonly-with-blank-nodes-example.c" parse="text"/>
+        </programlisting>
+      </informalexample>
     </para>
   </chapter>
 
diff --git a/docs/reference/libtracker-sparql/examples/builder-example.c b/docs/reference/libtracker-sparql/examples/builder-example.c
new file mode 100644
index 000000000..c538ea563
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/builder-example.c
@@ -0,0 +1,41 @@
+#include <libtracker-sparql/tracker-sparql.h>
+
+int main (int argc, char **argv)
+{
+  TrackerSparqlBuilder *builder;
+  const gchar *iri = "urn:example:0001";
+  const gchar *query_str;
+  time_t now;
+
+  /* Create builder */
+  builder = tracker_sparql_builder_new_update ();
+
+  /* Insert new data */
+  tracker_sparql_builder_insert_open (builder, NULL);
+
+  tracker_sparql_builder_subject_iri (builder, iri);
+
+  tracker_sparql_builder_predicate (builder, "a");
+  tracker_sparql_builder_object (builder, "nie:DataObject");
+  tracker_sparql_builder_object (builder, "nfo:FileDataObject");
+
+  now = time (NULL);
+  tracker_sparql_builder_predicate (builder, "nfo:fileLastModified");
+  tracker_sparql_builder_object_date (builder, &now);
+
+  tracker_sparql_builder_insert_close (builder);
+
+  /* Get query as string. Do NOT g_free() the resulting string! */
+  query_str = tracker_sparql_builder_get_result (builder);
+
+  /* Print it */
+  g_print ("Generated SPARQL query: '%s'\n", query_str);
+
+  /* Once builder no longer needed, unref it. Note that after
+   * this operation, you must not use the returned query result
+   * any more
+   */
+  g_object_unref (builder);
+
+  return 0;
+}
diff --git a/docs/reference/libtracker-sparql/examples/meson.build b/docs/reference/libtracker-sparql/examples/meson.build
new file mode 100644
index 000000000..8b2ba17a0
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/meson.build
@@ -0,0 +1,27 @@
+executable(
+  'builder-example',
+  'builder-example.c',
+  dependencies: tracker_sparql_dep,
+  build_by_default: true
+)
+
+executable(
+  'readonly-example',
+  'readonly-example.c',
+  dependencies: tracker_sparql_dep,
+  build_by_default: true
+)
+
+executable(
+  'writeonly-example',
+  'writeonly-example.c',
+  dependencies: tracker_sparql_dep,
+  build_by_default: true
+)
+
+executable(
+  'writeonly-with-blank-nodes-example',
+  'writeonly-with-blank-nodes-example.c',
+  dependencies: tracker_sparql_dep,
+  build_by_default: true
+)
diff --git a/docs/reference/libtracker-sparql/examples/readonly-example.c b/docs/reference/libtracker-sparql/examples/readonly-example.c
new file mode 100644
index 000000000..ac89cab26
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/readonly-example.c
@@ -0,0 +1,55 @@
+#include <libtracker-sparql/tracker-sparql.h>
+
+int main (int argc, const char **argv)
+{
+  GError *error = NULL;
+  TrackerSparqlConnection *connection;
+  TrackerSparqlCursor *cursor;
+  const gchar *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject }";
+
+  connection = tracker_sparql_connection_get (NULL, &error);
+  if (!connection) {
+    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
+                error ? error->message : "unknown error");
+    g_clear_error (&error);
+
+    return 1;
+  }
+
+  /* Make a synchronous query to the store */
+  cursor = tracker_sparql_connection_query (connection,
+                                          query,
+                                          NULL,
+                                          &error);
+
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_printerr ("Couldn't query the Tracker Store: '%s'",
+                error ? error->message : "unknown error");
+    g_clear_error (&error);
+
+    return 1;
+  }
+
+  /* Check results... */
+  if (!cursor) {
+    g_print ("No results found :-/\n");
+  } else {
+    gint i = 0;
+
+    /* Iterate, synchronously, the results... */
+    while (tracker_sparql_cursor_next (cursor, NULL, &error)) {
+      g_print ("Result [%d]: %s\n",
+               i++,
+               tracker_sparql_cursor_get_string (cursor, 0, NULL));
+    }
+
+    g_print ("A total of '%d' results were found\n", i);
+
+    g_object_unref (cursor);
+  }
+
+  g_object_unref (connection);
+
+  return 0;
+}
diff --git a/docs/reference/libtracker-sparql/examples/writeonly-example.c b/docs/reference/libtracker-sparql/examples/writeonly-example.c
new file mode 100644
index 000000000..854763099
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/writeonly-example.c
@@ -0,0 +1,48 @@
+#include <libtracker-sparql/tracker-sparql.h>
+
+int main (int argc, const char **argv)
+{
+  GError *error = NULL;
+  TrackerSparqlConnection *connection;
+  const gchar *query =
+    "INSERT { "
+    "  _:tag a nao:Tag ; "
+    "        nao:prefLabel 'mylabel' . "
+    "} WHERE { "
+    "  OPTIONAL { "
+    "    ?tag a nao:Tag ; "
+    "    nao:prefLabel 'mylabel' "
+    "  } . "
+    "FILTER (!bound(?tag)) "
+    "}";
+
+  connection = tracker_sparql_connection_get (NULL, &error);
+  if (!connection) {
+    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
+                error ? error->message : "unknown error");
+    g_clear_error (&error);
+
+    return 1;
+  }
+
+  /* Run a synchronous update query */
+  tracker_sparql_connection_update (connection,
+                                    query,
+                                    G_PRIORITY_DEFAULT,
+                                    NULL,
+                                    &error);
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_printerr ("Couldn't update the Tracker store: %s",
+                error ? error->message : "unknown error");
+
+    g_clear_error (&error);
+    g_object_unref (connection);
+
+    return 1;
+  }
+
+  g_object_unref (connection);
+
+  return 0;
+}
diff --git a/docs/reference/libtracker-sparql/examples/writeonly-with-blank-nodes-example.c b/docs/reference/libtracker-sparql/examples/writeonly-with-blank-nodes-example.c
new file mode 100644
index 000000000..44114b556
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/writeonly-with-blank-nodes-example.c
@@ -0,0 +1,62 @@
+#include <libtracker-sparql/tracker-sparql.h>
+
+int main (int argc, const char **argv)
+{
+  GError *error = NULL;
+  GVariant *v;
+  TrackerSparqlConnection *connection;
+  const gchar *query =
+    "INSERT { _:foo a nie:InformationElement } WHERE { ?x a rdfs:Class }";
+
+  connection = tracker_sparql_connection_get (NULL, &error);
+  if (!connection) {
+    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
+                error ? error->message : "unknown error");
+    g_clear_error (&error);
+
+    return 1;
+  }
+
+  /* Run a synchronous blank node update query */
+  v = tracker_sparql_connection_update_blank (connection,
+                                              query,
+                                              G_PRIORITY_DEFAULT,
+                                              NULL,
+                                              &error);
+
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_printerr ("Couldn't update the Tracker store: %s",
+                error ? error->message : "unknown error");
+
+    g_clear_error (&error);
+    g_object_unref (connection);
+
+    return 1;
+  }
+
+  if (!v) {
+    g_print ("No results were returned\n");
+  } else {
+    GVariantIter iter1, *iter2, *iter3;
+    const gchar *node;
+    const gchar *urn;
+
+    g_print ("Results:\n");
+
+    g_variant_iter_init (&iter1, v);
+    while (g_variant_iter_loop (&iter1, "aa{ss}", &iter2)) { /* aa{ss} */
+      while (g_variant_iter_loop (iter2, "a{ss}", &iter3)) { /* a{ss} */
+        while (g_variant_iter_loop (iter3, "{ss}", &node, &urn)) { /* {ss} */
+          g_print ("  Node:'%s', URN:'%s'\n", node, urn);
+        }
+      }
+    }
+
+    g_variant_unref (v);
+  }
+
+  g_object_unref (connection);
+
+  return 0;
+}
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index e86e0b459..b09b1207e 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -23,7 +23,9 @@ example_files = [
     'examples/ontologies/defining-properties-3.txt', 'examples/ontologies/defining-properties-4.rq',
     'examples/ontologies/defining-uniqueness-1.txt', 'examples/ontologies/defining-uniqueness-2.rq',
     'examples/ontologies/example.description', 'examples/ontologies/predefined-elements-1.txt',
-    'examples/ontologies/predefined-elements-2.rq'
+    'examples/ontologies/predefined-elements-2.rq', 'examples/builder-example.c',
+    'examples/readonly-example.c', 'examples/writeonly-example.c',
+    'examples/writeonly-with-blank-nodes-example.c',
 ]
 
 gnome.gtkdoc('libtracker-sparql',
@@ -33,3 +35,5 @@ gnome.gtkdoc('libtracker-sparql',
     dependencies: tracker_sparql_dep,
     fixxref_args: fixxref_args,
     install: true)
+
+subdir('examples')