GNOME.org
 

[tracker/direct-access-documentation: 3/5] libtracker-sparql: Avoid tmpl files in documentation

commit ad02140d92c4d23f42d72e5ba8257966c0ae8d2b
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Tue Aug 3 16:13:46 2010 +0200

    libtracker-sparql: Avoid tmpl files in documentation

 .../libtracker-sparql/tmpl/tracker-misc.sgml       |   51 ---
 .../tmpl/tracker-sparql-builder.sgml               |  391 --------------------
 src/libtracker-sparql/tracker-builder.vala         |  326 ++++++++++++++++-
 src/libtracker-sparql/tracker-utils.vala           |   12 +
 4 files changed, 337 insertions(+), 443 deletions(-)
---
diff --git a/src/libtracker-sparql/tracker-builder.vala b/src/libtracker-sparql/tracker-builder.vala
index bde2a22..09f9d70 100644
--- a/src/libtracker-sparql/tracker-builder.vala
+++ b/src/libtracker-sparql/tracker-builder.vala
@@ -17,8 +17,90 @@
  * Boston, MA  02110-1301, USA.
  */
 
+
+/**
+ * SECTION: tracker-sparql-builder
+ * @short_description: Creating insertion/update SPARQL queries.
+ * @title: TrackerSparqlBuilder
+ * @stability: Stable
+ * @include: tracker-sparql.h
+ *
+ * <para>
+ * #TrackerSparqlBuilder is an object what will gather a set of
+ * subject/predicate/object triples, together with an optional WHERE clause,
+ * in order to create a query that may be issued to tracker-store.
+ * </para>
+ *
+ * <para>
+ * When using #TrackerSparqlBuilder, note that you may append several predicates
+ * for the same subject, and several objects for the same predicate.
+ * </para>
+ *
+ * <example id="example-sparql-builder">
+ *   <title>Using TrackerSparqlBuilder</title>
+ *   <programlisting>
+ *   TrackerSparqlBuilder *builder;
+ *   const gchar *iri = "urn:example:0001";
+ *   gchar *query_str;
+ * &nbsp;&nbsp;
+ *   /&ast; Create builder &ast;/
+ *   builder = tracker_sparql_builder_new_update ();
+ * &nbsp;&nbsp;
+ *   /&ast; Drop previous data &ast;/
+ *   tracker_sparql_builder_drop_graph (builder, iri);
+ * &nbsp;&nbsp;
+ *   /&ast; Insert new data &ast;/
+ *   tracker_sparql_builder_insert_open (builder, iri);
+ * &nbsp;&nbsp;
+ *   tracker_sparql_builder_subject_iri (builder, iri);
+ * &nbsp;&nbsp;
+ *   tracker_sparql_builder_predicate (builder, "a");
+ *   tracker_sparql_builder_object (builder, "nie:DataObject");
+ *   tracker_sparql_builder_object (builder, "nfo:FileDataObject");
+ * &nbsp;&nbsp;
+ *   tracker_sparql_builder_predicate (builder, "nfo:fileLastModified");
+ *   tracker_sparql_builder_object_date (builder, time (NULL));
+ * &nbsp;&nbsp;
+ *   tracker_sparql_builder_insert_close (builder);
+ * &nbsp;&nbsp;
+ *   /&ast; Get query as string &ast;/
+ *   query_str = tracker_sparql_builder_get_result (builder);
+ *   </programlisting>
+ * </example>
+ */
+
+
+/**
+ * TrackerSparqlBuilder:
+ *
+ * The <structname>TrackerSparqlBuilder</structname> object represents an
+ * insertion/update SPARQL query.
+ */
+
+/**
+ * tracker_sparql_builder_new:
+ *
+ * Creates a stateless #TrackerSparqlBuilder.
+ *
+ * Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+ *
+ */
 public class Tracker.Sparql.Builder : Object {
 
+	/**
+	 * TrackerSparqlBuilderState:
+	 * @TRACKER_SPARQL_BUILDER_STATE_UPDATE: Builder is generating an UPDATE
+	 * @TRACKER_SPARQL_BUILDER_STATE_INSERT: Builder is generating an INSERT
+	 * @TRACKER_SPARQL_BUILDER_STATE_DELETE: Builder is generating a DELETE
+	 * @TRACKER_SPARQL_BUILDER_STATE_SUBJECT: Builder is generating the subject of the query
+	 * @TRACKER_SPARQL_BUILDER_STATE_PREDICATE: Builder is generating the predicate of the query
+	 * @TRACKER_SPARQL_BUILDER_STATE_OBJECT: Builder is generating the object of the query
+	 * @TRACKER_SPARQL_BUILDER_STATE_BLANK: Builder is generating a blank node subject
+	 * @TRACKER_SPARQL_BUILDER_STATE_WHERE: Builder is generating the WHERE clause contents
+	 * @TRACKER_SPARQL_BUILDER_STATE_EMBEDDED_INSERT: Builder is generating an embedded INSERT
+	 *
+	 * Enumeration with the possible states of the SPARQL Builder
+	 */
 	public enum State {
 		UPDATE,
 		INSERT,
@@ -31,38 +113,111 @@ public class Tracker.Sparql.Builder : Object {
 		EMBEDDED_INSERT
 	}
 
+	/**
+	 * TrackerSparqlBuilder:result:
+	 *
+	 * String containing the constructed SPARQL in the #TrackerSparqlBuilder.
+	 */
 	public string result {
+		/**
+		 * tracker_sparql_builder_get_result:
+		 * @self: a #TrackerSparqlBuilder
+		 *
+		 * Returns the constructed SPARQL query as a string.
+		 *
+		 * Returns: the created SPARQL query. The string is contained in the
+		 *  #TrackerSparqlBuilder object, and should not be freed by the caller.
+		 */
 		get {
 			warn_if_fail (states.length == 1);
 			return str.str;
 		}
 	}
 
-	public int length { get; private set; }
+	/**
+	 * TrackerSparqlBuilder:length:
+	 *
+	 * Number of objects added to the #TrackerSparqlBuilder.
+	 */
+	public int length {
+		/**
+		 * tracker_sparql_builder_get_length:
+		 * @self: a #TrackerSparqlBuilder
+		 *
+		 * Returns the number of objects added to @self.
+		 *
+		 * Returns: the number of objects contained.
+		 */
+		get;
+		private set;
+	}
 
+	/**
+	 * TrackerSparqlBuilder:state:
+	 *
+	 * Current state of the #TrackerSparqlBuilder.
+	 */
 	public State state {
+		/**
+		 * tracker_sparql_builder_get_state:
+		 * @self: a #TrackerSparqlBuilder
+		 *
+		 * Returns the current state of @self
+		 *
+		 * Returns: a #TrackerSparqlBuilderState defining the current state of @self
+		 */
 		get { return states[states.length - 1]; }
 	}
 
 	State[] states;
 	StringBuilder str = new StringBuilder ();
 
+	/**
+	 * tracker_sparql_builder_new_update:
+	 *
+	 * Creates an empty #TrackerSparqlBuilder for an update query.
+	 *
+	 * Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+	 */
 	public Builder.update () {
 		states += State.UPDATE;
 	}
 
+	/**
+	 * tracker_sparql_builder_new_embedded_insert:
+	 *
+	 * Creates a #TrackerSparqlBuilder ready to be embedded in another query. In embedded
+	 * inserts, the subject is implied (responsibility of the embedder), so only calls to
+	 * append predicates and objects for the given subject are allowed.
+	 *
+	 * Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+	 */
 	public Builder.embedded_insert () {
 		states += State.EMBEDDED_INSERT;
 		states += State.INSERT;
 		states += State.SUBJECT;
 	}
 
+	/**
+	 * tracker_sparql_builder_drop_graph:
+	 * @self: a #TrackerSparqlBuilder
+	 * @iri: a graph name.
+	 *
+	 * Appends a DROP GRAPH clause.
+	 */
 	public void drop_graph (string iri)
 		requires (state == State.UPDATE)
 	{
 		str.append ("DROP GRAPH <%s>\n".printf (iri));
 	}
 
+	/**
+	 * tracker_sparql_builder_insert_open:
+	 * @self: a #TrackerSparqlBuilder
+	 * @graph: graph name, or %NULL.
+	 *
+	 * Opens an insertion statement.
+	 */
 	public void insert_open (string? graph)
 		requires (state == State.UPDATE)
 	{
@@ -73,6 +228,13 @@ public class Tracker.Sparql.Builder : Object {
 			str.append ("INSERT {\n");
 	}
 
+	/**
+	 * tracker_sparql_builder_insert_silent_open:
+	 * @self: a #TrackerSparqlBuilder
+	 * @graph: graph name, or %NULL.
+	 *
+	 * Opens a silent insertion statement.
+	 */
 	public void insert_silent_open (string? graph)
 		requires (state == State.UPDATE)
 	{
@@ -83,6 +245,12 @@ public class Tracker.Sparql.Builder : Object {
 			str.append ("INSERT SILENT {\n");
 	}
 
+	/**
+	 * tracker_sparql_builder_insert_close:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Closes an insertion statement opened with tracker_sparql_builder_insert_open().
+	 */
 	public void insert_close ()
 		requires (state == State.INSERT || state == State.OBJECT)
 	{
@@ -97,6 +265,14 @@ public class Tracker.Sparql.Builder : Object {
 		}
 	}
 
+	/**
+	 * tracker_sparql_builder_delete_open:
+	 * @self: a #TrackerSparqlBuilder
+	 * @graph: graph name, or %NULL.
+	 *
+	 * Opens a DELETE clause. Data triples may be appended in order to prepare
+	 * a query to delete them.
+	 */
 	public void delete_open (string? graph)
 		requires (state == State.UPDATE)
 	{
@@ -107,6 +283,12 @@ public class Tracker.Sparql.Builder : Object {
 			str.append ("DELETE {\n");
 	}
 
+	/**
+	 * tracker_sparql_builder_delete_close:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Closes a DELETE clause opened through tracker_sparql_builder_delete_open().
+	 */
 	public void delete_close ()
 		requires (state == State.DELETE || state == State.OBJECT)
 	{
@@ -119,6 +301,13 @@ public class Tracker.Sparql.Builder : Object {
 		str.append ("}\n");
 	}
 
+	/**
+	 * tracker_sparql_builder_where_open:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Opens a WHERE clause. Data triples may be appended then to narrow the scope
+	 * to which the update query applies.
+	 */
 	public void where_open ()
 	       requires (state == State.UPDATE)
 	{
@@ -126,6 +315,12 @@ public class Tracker.Sparql.Builder : Object {
 		str.append ("WHERE {\n");
 	}
 
+	/**
+	 * tracker_sparql_builder_where_close:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Closes a WHERE clause opened through tracker_sparql_builder_where_open().
+	 */
 	public void where_close ()
 		requires (state == State.WHERE || state == State.OBJECT)
 	{
@@ -137,18 +332,47 @@ public class Tracker.Sparql.Builder : Object {
 		str.append ("}\n");
 	}
 
+	/**
+	 * tracker_sparql_builder_subject_variable:
+	 * @self: a #TrackerSparqlBuilder
+	 * @var_name: variable name, without leading '?'
+	 *
+	 * Appends a subject as a SPARQL variable, such as "?urn".
+	 */
 	public void subject_variable (string var_name) {
 		subject ("?%s".printf (var_name));
 	}
 
+	/**
+	 * tracker_sparql_builder_object_variable:
+	 * @self: a #TrackerSparqlBuilder
+	 * @var_name: variable name, without leading '?'
+	 *
+	 * Appends an object as a SparQL variable, such as "?urn".
+	 */
 	public void object_variable (string var_name) {
 		object ("?%s".printf (var_name));
 	}
 
+	/**
+	 * tracker_sparql_builder_subject_iri:
+	 * @self: a #TrackerSparqlBuilder
+	 * @iri: IRI name, without leading and trailing greater/less than symbols.
+	 *
+	 * Appends a subject as an IRI, such as "&lt;urn:file:1234-5678&gt;". IRIs
+	 * univocally identify a resource in tracker-store.
+	 */
 	public void subject_iri (string iri) {
 		subject ("<%s>".printf (iri));
 	}
 
+	/**
+	 * tracker_sparql_builder_subject:
+	 * @self: a #TrackerSparqlBuilder
+	 * @s: subject string
+	 *
+	 * Appends a subject.
+	 */
 	public void subject (string s)
 		requires (state == State.INSERT || state == State.OBJECT || state == State.EMBEDDED_INSERT || state == State.DELETE || state == State.WHERE)
 	{
@@ -160,10 +384,24 @@ public class Tracker.Sparql.Builder : Object {
 		states += State.SUBJECT;
 	}
 
+	/**
+	 * tracker_sparql_builder_predicate_iri:
+	 * @self: a #TrackerSparqlBuilder
+	 * @iri: IRI name, without leading and trailing greater/less than symbols.
+	 *
+	 * Appends a predicate as an IRI.
+	 */
 	public void predicate_iri (string iri) {
 		predicate ("<%s>".printf (iri));
 	}
 
+	/**
+	 * tracker_sparql_builder_predicate:
+	 * @self: a #TrackerSparqlBuilder
+	 * @s: predicate string
+	 *
+	 * Appends a predicate for the previously appended subject.
+	 */
 	public void predicate (string s)
 		requires (state == State.SUBJECT || state == State.OBJECT || state == State.BLANK)
 	{
@@ -176,10 +414,24 @@ public class Tracker.Sparql.Builder : Object {
 		states += State.PREDICATE;
 	}
 
+	/**
+	 * tracker_sparql_builder_object_iri:
+	 * @self: a #TrackerSparqlBuilder
+	 * @iri: IRI name, without leading and trailing greater/less than symbols.
+	 *
+	 * Appends an object as an IRI.
+	 */
 	public void object_iri (string iri) {
 		object ("<%s>".printf (iri));
 	}
 
+	/**
+	 * tracker_sparql_builder_object:
+	 * @self: a #TrackerSparqlBuilder
+	 * @s: object string
+	 *
+	 * Appends a free-form object for the previously appended subject and predicate.
+	 */
 	public void object (string s)
 		requires (state == State.PREDICATE || state == State.OBJECT)
 	{
@@ -194,6 +446,14 @@ public class Tracker.Sparql.Builder : Object {
 		length++;
 	}
 
+	/**
+	 * tracker_sparql_builder_object_string:
+	 * @self: a #TrackerSparqlBuilder
+	 * @literal: string object
+	 *
+	 * Appends an object formatted as an string. @literal will be escaped and surrounded
+	 * by double quotes.
+	 */
 	public void object_string (string literal)
 		requires (state == State.PREDICATE || state == State.OBJECT)
 	{
@@ -238,6 +498,13 @@ public class Tracker.Sparql.Builder : Object {
 		length++;
 	}
 
+	/**
+	 * tracker_sparql_builder_object_unvalidated:
+	 * @self: a #TrackerSparqlBuilder
+	 * @value: possibly UTF-8 invalid string.
+	 *
+	 * Appends a string not validated as UTF-8 as an object.
+	 */
 	public void object_unvalidated (string value) {
 		char* end;
 
@@ -254,24 +521,61 @@ public class Tracker.Sparql.Builder : Object {
 		object_string (value);
 	}
 
+	/**
+	 * tracker_sparql_builder_object_boolean:
+	 * @self: a #TrackerSparqlBuilder
+	 * @literal: object as a #gboolean
+	 *
+	 * Appends a #gboolean value as an object.
+	 */
 	public void object_boolean (bool literal) {
 		object (literal ? "true" : "false");
 	}
 
+	/**
+	 * tracker_sparql_builder_object_int64:
+	 * @self: a #TrackerSparqlBuilder
+	 * @literal: object as a #gint64
+	 *
+	 * Appends a #gint64 value as an object.
+	 */
 	public void object_int64 (int64 literal) {
 		object (literal.to_string ());
 	}
 
+	/**
+	 * tracker_sparql_builder_object_date:
+	 * @self: a #TrackerSparqlBuilder
+	 * @literal: object as a #time_t
+	 *
+	 * Appends a #time_t value as an object. @literal will be converted
+	 * to a string in the date format used by tracker-store.
+	 */
 	public void object_date (ref time_t literal) {
 		var tm = Time.gm (literal);
 
 		object_string ("%04d-%02d-%02dT%02d:%02d:%02dZ".printf (tm.year + 1900, tm.month + 1, tm.day, tm.hour, tm.minute, tm.second));
 	}
 
+	/**
+	 * tracker_sparql_builder_object_double:
+	 * @self: a #TrackerSparqlBuilder
+	 * @literal: object as a #gdouble
+	 *
+	 * Appends a #gdouble value as an object.
+	 */
 	public void object_double (double literal) {
 		object (literal.to_string ());
 	}
 
+	/**
+	 * tracker_sparql_builder_object_blank_open:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Opens an anonymous blank node. In insertions this can be used to create
+	 * anonymous nodes for not previously known data without the need of a
+	 * separate insertion.
+	 */
 	public void object_blank_open ()
 		requires (state == State.PREDICATE || state == State.OBJECT)
 	{
@@ -283,6 +587,12 @@ public class Tracker.Sparql.Builder : Object {
 		states += State.BLANK;
 	}
 
+	/**
+	 * tracker_sparql_builder_object_blank_close:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Closes an anomymous blank node opened with tracker_sparql_builder_object_blank_open()
+	 */
 	public void object_blank_close ()
 		requires (state == State.OBJECT && states[states.length - 3] == state.BLANK)
 	{
@@ -293,11 +603,25 @@ public class Tracker.Sparql.Builder : Object {
 		length++;
 	}
 
+	/**
+	 * tracker_sparql_builder_prepend:
+	 * @self: a #TrackerSparqlBuilder
+	 * @raw: raw content to prepend.
+	 *
+	 * Prepends raw, unvalidated content to @self.
+	 */
 	public void prepend (string raw)
 	{
 		str.prepend ("%s\n".printf (raw));
 	}
 
+	/**
+	 * tracker_sparql_builder_append:
+	 * @self: a #TrackerSparqlBuilder
+	 * @raw: raw content to append.
+	 *
+	 * Appends raw, unvalidated content to @self.
+	 */
 	public void append (string raw)
 	{
 		if (state == State.OBJECT) {
diff --git a/src/libtracker-sparql/tracker-utils.vala b/src/libtracker-sparql/tracker-utils.vala
index 5faacac..c7a568c 100644
--- a/src/libtracker-sparql/tracker-utils.vala
+++ b/src/libtracker-sparql/tracker-utils.vala
@@ -17,6 +17,18 @@
  * Boston, MA  02110-1301, USA.
  */
 
+/**
+ * SECTION: tracker-misc
+ * @short_description: General purpose utilities provided by the library
+ * @title: Utilities
+ * @stability: Stable
+ * @include: tracker-sparql.h
+ *
+ * <para>
+ * The libtracker-sparql utilities help in the creation of proper SPARQL queries.
+ * </para>
+ */
+
 // Imported from tracker-uri.c
 public extern string tracker_sparql_escape_uri_vprintf (string format, va_list args);
 public extern string tracker_sparql_escape_uri_printf (string format, ...);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]