[tracker/tintou/doc-update] libtracker-sparql: Replace the SPARQL building example with a new example

[Corentin Noël <corentinnoel src gnome org>]

commit 10448a90bdc1db687795e4aa2509888197f0a143
Author: Corentin Noël <corentin noel collabora com>
Date:   Tue Sep 3 12:18:46 2019 +0200

    libtracker-sparql: Replace the SPARQL building example with a new example

 docs/reference/libtracker-sparql/examples.xml      | 72 ++++++----------------
 .../libtracker-sparql/examples/insert-example.c    | 63 +++++++++++++++++++
 .../libtracker-sparql/examples/meson.build         |  6 ++
 docs/reference/libtracker-sparql/meson.build       |  4 +-
 4 files changed, 91 insertions(+), 54 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
index 34aea4d6e..e4a35d055 100644
--- a/docs/reference/libtracker-sparql/examples.xml
+++ b/docs/reference/libtracker-sparql/examples.xml
@@ -1,4 +1,9 @@
 <?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>
@@ -10,68 +15,29 @@
 
 
   <chapter id="tracker-examples-builder">
-    <title>SPARQL query builder</title>
+    <title>Executing a SPARQL query</title>
 
     <para>
-      The Tracker SPARQL library provides an easy and secure way of creating
-      SPARQL queries with the proper syntax. This is achieved using the
-      <type><link linkend="TrackerSparqlBuilder-struct">TrackerSparqlBuilder</link></type>
-      object.
+      The Tracker SPARQL library provides an easy way to execute queries.
+      The <type><link linkend="TrackerSparqlStatement">TrackerSparqlStatement</link></type> object
+      allows querries to be reused by replacing only the values of the query at execution time.
     </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="insert-example.c" parse="text"/>
+      </programlisting>
+    </informalexample>
 
+    <para>
       The previous code will generate the following SPARQL query:
-<programlisting>
-  DROP GRAPH &lt;urn:example:0001&gt;
-  INSERT INTO &lt;urn:example:0001&gt; {
+      <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" .
 }
-</programlisting>
+      </programlisting>
     </para>
   </chapter>
 
diff --git a/docs/reference/libtracker-sparql/examples/insert-example.c 
b/docs/reference/libtracker-sparql/examples/insert-example.c
new file mode 100644
index 000000000..d8c0c99c4
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/insert-example.c
@@ -0,0 +1,63 @@
+#include <libtracker-sparql/tracker-sparql.h>
+
+int main (int argc, char **argv)
+{
+  TrackerSparqlConnection *connection;
+  TrackerSparqlStatement *statement;
+  TrackerSparqlCursor *cursor;
+  GError *error = NULL;
+  GDateTime *new_datetime;
+  gchar *formated_datetime;
+  const gchar *iri = "<urn:example:0001>";
+  const gchar *query_str =
+    "DROP GRAPH ~iri\n"
+    "INSERT INTO ~iri {\n"
+    "~iri a nie:DataObject , nfo:FileDataObject ;\n"
+    "       nfo:fileLastModified \"~time\"\n"
+    "}";
+
+  /* Get the SparqlConnection */
+  connection = tracker_sparql_connection_get (NULL, &error);
+  if (error) {
+    g_critical ("Error getting a SPARQL connection: %s", error->message);
+    g_clear_error (&error);
+    return -1;
+  }
+
+  /* Create a new Statement */
+  statement = tracker_sparql_connection_query_statement (connection,
+                                                         query_str,
+                                                         NULL,
+                                                         &error);
+  if (error) {
+    g_critical ("Error querying the statement: %s", error->message);
+    g_clear_error (&error);
+    g_object_unref (connection);
+    return -1;
+  }
+
+  /* Repace all the ~iri occurences with the actual iri */
+  tracker_sparql_statement_bind_string (statement, "iri", iri);
+
+  /* Repace all the ~time occurences with the current time */
+  new_datetime = g_date_time_new_now_local ();
+  formated_datetime = g_date_time_format (new_datetime, "%Y-%m-%dT%H:%M:%S%z");
+  g_date_time_unref (new_datetime);
+  tracker_sparql_statement_bind_string (statement, "time", formated_datetime);
+  g_free (formated_datetime);
+
+  cursor = tracker_sparql_statement_execute (statement, NULL, &error);
+  if (error) {
+    const gchar *sparql_query = tracker_sparql_statement_get_sparql (statement);
+    g_critical ("Error executing the statement: %s\n[Query]\n%s", error->message, sparql_query);
+    g_clear_error (&error);
+    g_object_unref (statement);
+    g_object_unref (connection);
+    return -1;
+  }
+
+  g_object_unref (cursor);
+  g_object_unref (statement);
+  g_object_unref (connection);
+  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..cbcfaf31a
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples/meson.build
@@ -0,0 +1,6 @@
+executable(
+  'insert-example',
+  'insert-example.c',
+  dependencies: tracker_sparql_dep,
+  build_by_default: true
+)
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index e86e0b459..f70ee95f9 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -23,7 +23,7 @@ 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/insert-example.c',
 ]
 
 gnome.gtkdoc('libtracker-sparql',
@@ -33,3 +33,5 @@ gnome.gtkdoc('libtracker-sparql',
     dependencies: tracker_sparql_dep,
     fixxref_args: fixxref_args,
     install: true)
+
+subdir('examples')