[folks] Rebase FieldDetails upon an abstract and generic version of itself.

[Travis Reitter <treitter src gnome org>]

commit 5f0ab0032ba17ce54334387a129ea0ee0f7c64c9
Author: Travis Reitter <travis reitter collabora co uk>
Date:   Thu Jul 7 11:10:58 2011 -0700

    Rebase FieldDetails upon an abstract and generic version of itself.
    
    This should be useful for cases where the value has a very specific type
    (eg, for PostalAddressDetails.postal_addresses). We'll create subclasses of
    FieldDetails for those cases.
    
    When we've created all the appropriate derived classes, we'll remove
    FieldDetails entirely.
    
    Helps: bgo#653679 - Change PostalAddressDetails.postal_addresses to
    support vCard-like arbitrary parameters

 NEWS                                        |    2 +
 backends/tracker/lib/trf-persona-store.vala |    4 +-
 folks/Makefile.am                           |    1 +
 folks/abstract-field-details.vala           |  169 +++++++++++++++++++++++++++
 folks/field-details.vala                    |  122 +++-----------------
 5 files changed, 189 insertions(+), 109 deletions(-)
---
diff --git a/NEWS b/NEWS
index 0117be6..c18e01d 100644
--- a/NEWS
+++ b/NEWS
@@ -49,6 +49,8 @@ API changes:
 * Add ObjectCache class
 * Remove leaked internal PotentialMatch.result_to_string() method
 * Add RoleDetails:role property
+* Rebase FieldDetails upon AbstractFieldDetails (requiring the use of the
+  equivalent AbstractFieldDetails functions in place of the FieldDetails ones).
 
 Overview of changes from libfolks 0.5.1 to libfolks 0.5.2
 =========================================================
diff --git a/backends/tracker/lib/trf-persona-store.vala b/backends/tracker/lib/trf-persona-store.vala
index 06b5515..1556286 100644
--- a/backends/tracker/lib/trf-persona-store.vala
+++ b/backends/tracker/lib/trf-persona-store.vala
@@ -2348,7 +2348,7 @@ public class Trf.PersonaStore : Folks.PersonaStore
       int i = 0;
       foreach (var p in attribs)
         {
-          FieldDetails fd = null;
+          AbstractFieldDetails fd = null;
           PostalAddress pa = null;
 
           string affl = "_:a%d".printf (i);
@@ -2388,7 +2388,7 @@ public class Trf.PersonaStore : Folks.PersonaStore
                   {
                     related_connection = Trf.OntologyDefs.NCO_WEBSITE;
                   }
-                attr = "'%s'".printf (fd.value);
+                attr = "'%s'".printf (((FieldDetails) fd).value);
                 break;
               case Trf.Attrib.IM_ADDRESSES:
               default:
diff --git a/folks/Makefile.am b/folks/Makefile.am
index 82d9044..e71c637 100644
--- a/folks/Makefile.am
+++ b/folks/Makefile.am
@@ -12,6 +12,7 @@ lib_LTLIBRARIES = libfolks.la
 
 # Vala files to compile into libfolks.la
 libfolks_la_SOURCES = \
+	abstract-field-details.vala \
 	alias-details.vala \
 	avatar-details.vala \
 	backend.vala \
diff --git a/folks/abstract-field-details.vala b/folks/abstract-field-details.vala
new file mode 100644
index 0000000..15ee926
--- /dev/null
+++ b/folks/abstract-field-details.vala
@@ -0,0 +1,169 @@
+/*
+ * Copyright (C) 2011 Collabora Ltd.
+ *
+ * This library is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 2.1 of the License, or
+ * (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authors:
+ *       Marco Barisione <marco barisione collabora co uk>
+ *       Travis Reitter <travis reitter collabora co uk>
+ */
+
+using GLib;
+using Gee;
+
+/**
+ * Object representing any type of value that can have some vCard-like
+ * parameters associated with it.
+ *
+ * Some contact details, like phone numbers or URLs, can have some
+ * extra details associated with them.
+ * For instance, a phone number expressed in vcard notation as
+ * `tel;type=work,voice:(111) 555-1234` would be represented as
+ * a AbstractFieldDetails with value "(111) 555-1234" and with parameters
+ * `['type': ('work', 'voice')]`.
+ *
+ * The parameter name "TYPE" with values "work", "home", or "other" are common
+ * amongst most vCard attributes (and thus most AbstractFieldDetails-derived
+ * classes). A TYPE of "perf" may be used to indicate a preferred
+ * AbstractFieldDetails.value amongst many. See specific classes for information
+ * on additional parameters and values specific to that class.
+ *
+ * See [[http://www.ietf.org/rfc/rfc2426.txt|RFC2426]] for more details on
+ * pre-defined parameter names and values.
+ *
+ * @since UNRELEASED
+ */
+public abstract class Folks.AbstractFieldDetails<T> : Object
+{
+  private T _value;
+  /**
+   * The value of the field.
+   *
+   * The value of the field, the exact type and content of which depends on what
+   * the structure is used for.
+   *
+   * @since UNRELEASED
+   */
+  public virtual T @value
+    {
+      get { return this._value; }
+      set { this._value = value; }
+    }
+
+  /**
+   * The parameters associated with the value.
+   *
+   * A hash table of the parameters associated with
+   * { link Folks.AbstractFieldDetails.value}. The keys are the names of
+   * the parameters, while the values are a list of strings.
+   *
+   * @since UNRELEASED
+   */
+  public virtual MultiMap<string, string> parameters
+    {
+      get { return this._parameters; }
+      set
+        {
+          if (value == null)
+            this._parameters.clear ();
+          else
+            this._parameters = value;
+        }
+    }
+
+  /**
+   * Get the values for a parameter
+   *
+   * @param parameter_name the parameter name
+   * @return a collection of values for `parameter_name` or `null` (i.e. no
+   * collection) if there are no such parameters.
+   *
+   * @since UNRELEASED
+   */
+  public Collection<string>? get_parameter_values (string parameter_name)
+    {
+      if (this.parameters.contains (parameter_name) == false)
+        {
+          return null;
+        }
+
+      return this.parameters.get (parameter_name).read_only_view;
+    }
+
+  /**
+   * Add a new value for a parameter.
+   *
+   * If there is already a parameter called `parameter_name` then
+   * `parameter_value` is added to the existing ones.
+   *
+   * @param parameter_name the name of the parameter
+   * @param parameter_value the value to add
+   *
+   * @since UNRELEASED
+   */
+  public void add_parameter (string parameter_name, string parameter_value)
+    {
+      this.parameters.set (parameter_name, parameter_value);
+    }
+
+  /**
+   * Set the value of a parameter.
+   *
+   * Sets the parameter called `parameter_name` to be `parameter_value`.
+   * If there were already parameters with the same name they are replaced.
+   *
+   * @param parameter_name the name of the parameter
+   * @param parameter_value the value to add
+   *
+   * @since UNRELEASED
+   */
+  public void set_parameter (string parameter_name, string parameter_value)
+    {
+      this.parameters.remove_all (parameter_name);
+      this.parameters.set (parameter_name, parameter_value);
+    }
+
+  /**
+   * Extend the existing parameters.
+   *
+   * Merge the parameters from `additional` into the existing ones.
+   *
+   * @param additional the parameters to add
+   *
+   * @since UNRELEASED
+   */
+  public void extend_parameters (MultiMap<string, string> additional)
+    {
+      foreach (var name in additional.get_keys ())
+        {
+          var values = additional.get (name);
+          foreach (var val in values)
+            {
+              this.add_parameter (name, val);
+            }
+        }
+    }
+
+  /**
+   * Remove all instances of a parameter.
+   *
+   * @param parameter_name the name of the parameter
+   *
+   * @since UNRELEASED
+   */
+  public void remove_parameter_all (string parameter_name)
+    {
+      this.parameters.remove_all (parameter_name);
+    }
+}
diff --git a/folks/field-details.vala b/folks/field-details.vala
index 0568fec..71cb3c8 100644
--- a/folks/field-details.vala
+++ b/folks/field-details.vala
@@ -16,46 +16,39 @@
  *
  * Authors:
  *       Marco Barisione <marco barisione collabora co uk>
+ *       Travis Reitter <travis reitter collabora co uk>
  */
 
 using GLib;
 using Gee;
 
 /**
- * Object representing a string value that can have some parameters
- * associated with it.
+ * Object representing any type of string value that can have some vCard-like
+ * parameters associated with it.
  *
  * Some contact details, like phone numbers or URLs, can have some
  * extra details associated with them.
  * For instance, a phone number expressed in vcard notation as
  * `tel;type=work,voice:(111) 555-1234` would be represented as
- * a FieldDetails with value "(111) 555-1234" and with parameters
+ * a AbstractFieldDetails with value "(111) 555-1234" and with parameters
  * `['type': ('work', 'voice')]`.
  *
- * @since 0.3.5
+ * @since UNRELEASED
  */
-public class Folks.FieldDetails : Object
+public class Folks.FieldDetails : AbstractFieldDetails<string>
 {
+  private MultiMap<string, string> _parameters;
   /**
-   * The value of the field.
-   *
-   * The value of the field, the exact content depends on what the structure is
-   * used for.
-   *
-   * @since 0.3.5
-   */
-  public string value { get; set; }
-
-  /**
-   * The parameters associated with the value.
-   *
-   * A hash table of the parameters associated with
-   * { link Folks.FieldDetails.value}. The keys are the names of the
-   * parameters, while the values are a list of strings.
+   * The parameters of this FieldDetails.
    *
+   * See { link Folks.AbstractFieldDetails.parameters}.
    * @since 0.5.1
    */
-  public MultiMap<string, string> parameters { get; set; }
+  public override MultiMap<string, string> parameters
+    {
+      get { return this._parameters; }
+      set { this._parameters = value; }
+    }
 
   /**
    * Create a new FieldDetails.
@@ -68,91 +61,6 @@ public class Folks.FieldDetails : Object
   public FieldDetails (string value)
     {
       this.value = value;
-      this.parameters = new HashMultiMap<string, string> ();
-    }
-
-  /**
-   * Get the values for a parameter
-   *
-   * @param parameter_name the parameter name
-   * @return a collection of values for `parameter_name` or `null` (i.e. no
-   * collection) if there are no such parameters.
-   *
-   * @since 0.5.1
-   */
-  public Collection<string>? get_parameter_values (string parameter_name)
-    {
-      if (this.parameters.contains (parameter_name) == false)
-        {
-          return null;
-        }
-
-      return this.parameters.get (parameter_name).read_only_view;
-    }
-
-  /**
-   * Add a new value for a parameter.
-   *
-   * If there is already a parameter called `parameter_name` then
-   * `parameter_value` is added to the existing ones.
-   *
-   * @param parameter_name the name of the parameter
-   * @param parameter_value the value to add
-   *
-   * @since 0.3.5
-   */
-  public void add_parameter (string parameter_name, string parameter_value)
-    {
-      this.parameters.set (parameter_name, parameter_value);
-    }
-
-  /**
-   * Set the value of a parameter.
-   *
-   * Sets the parameter called `parameter_name` to be `parameter_value`.
-   * If there were already parameters with the same name they are replaced.
-   *
-   * @param parameter_name the name of the parameter
-   * @param parameter_value the value to add
-   *
-   * @since 0.3.5
-   */
-  public void set_parameter (string parameter_name, string parameter_value)
-    {
-      this.parameters.remove_all (parameter_name);
-      this.parameters.set (parameter_name, parameter_value);
-    }
-
-  /**
-   * Extend the existing parameters.
-   *
-   * Merge the parameters from `additional` into the existing ones.
-   *
-   * @param additional the parameters to add
-   *
-   * @since 0.5.1
-   */
-  public void extend_parameters (MultiMap<string, string> additional)
-    {
-      foreach (var name in additional.get_keys ())
-        {
-          var values = additional.get (name);
-          foreach (var val in values)
-            {
-              this.add_parameter (name, val);
-            }
-        }
-    }
-
-  /**
-   * Remove all instances of a parameter.
-   *
-   * @param parameter_name the name of the parameter
-   *
-   * @since 0.3.5
-   */
-  public void remove_parameter_all (string parameter_name)
-    {
-      this.parameters.remove_all (parameter_name);
+      this._parameters = new HashMultiMap<string, string> ();
     }
 }