Rename pango_ot_ruleset_get_for() to

2007-06-03  Behdad Esfahbod  <behdad@gnome.org>

        * docs/pango-sections.txt:
        * docs/tmpl/opentype.sgml:
        * modules/arabic/arabic-fc.c (arabic_engine_shape):
        * modules/basic/basic-fc.c (basic_engine_shape):
        * modules/hebrew/hebrew-fc.c (hebrew_engine_shape):
        * modules/indic/indic-fc.c (indic_engine_shape):
        * modules/khmer/khmer-fc.c (khmer_engine_shape):
        * modules/syriac/syriac-fc.c (syriac_engine_shape):
        * modules/thai/thai-fc.c (thai_engine_shape):
        * modules/tibetan/tibetan-fc.c (tibetan_engine_shape):
        * pango/pango-ot-ruleset.c (pango_ot_ruleset_get_for_description),
        (pango_ot_ruleset_new_from_description):
        * pango/pango-ot.h:
        * pango/pangoft2.def:
        Rename pango_ot_ruleset_get_for() to
        pango_ot_ruleset_get_for_description().

        New engine API: pango_ot_ruleset_new_from_description().


svn path=/trunk/; revision=2328

14 files changed, 114 insertions, 42 deletions

diff --git a/ChangeLog b/ChangeLog
index 4050dbc1..93ae1624 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2007-06-03  Behdad Esfahbod  <behdad@gnome.org>
+
+	* docs/pango-sections.txt:
+	* docs/tmpl/opentype.sgml:
+	* modules/arabic/arabic-fc.c (arabic_engine_shape):
+	* modules/basic/basic-fc.c (basic_engine_shape):
+	* modules/hebrew/hebrew-fc.c (hebrew_engine_shape):
+	* modules/indic/indic-fc.c (indic_engine_shape):
+	* modules/khmer/khmer-fc.c (khmer_engine_shape):
+	* modules/syriac/syriac-fc.c (syriac_engine_shape):
+	* modules/thai/thai-fc.c (thai_engine_shape):
+	* modules/tibetan/tibetan-fc.c (tibetan_engine_shape):
+	* pango/pango-ot-ruleset.c (pango_ot_ruleset_get_for_description),
+	(pango_ot_ruleset_new_from_description):
+	* pango/pango-ot.h:
+	* pango/pangoft2.def:
+	Rename pango_ot_ruleset_get_for() to
+	pango_ot_ruleset_get_for_description().
+
+	New engine API: pango_ot_ruleset_new_from_description().
+
 2007-06-02  Behdad Esfahbod  <behdad@gnome.org>
 
 	Bug 443206 – PANGO_SCRIPT_UNKNOWN should not cause a run break
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index fa57140a..d50b1a6e 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -964,9 +964,10 @@ pango_ot_buffer_set_rtl
 pango_ot_buffer_set_zero_width_marks
 pango_ot_buffer_get_glyphs
 pango_ot_buffer_output
-pango_ot_ruleset_get_for
+pango_ot_ruleset_get_for_description
 pango_ot_ruleset_new
 pango_ot_ruleset_new_for
+pango_ot_ruleset_new_from_description
 pango_ot_ruleset_add_feature
 pango_ot_ruleset_maybe_add_feature
 pango_ot_ruleset_maybe_add_features
diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml
index 45865df6..20910f82 100644
--- a/docs/tmpl/opentype.sgml
+++ b/docs/tmpl/opentype.sgml
@@ -82,7 +82,8 @@ The #PangoOTRuleset structure holds all the information needed
 to build a complete #PangoOTRuleset from an OpenType font.
 The main use of this struct is to act as the key for a per-font
 hash of rulesets.  The user populates a ruleset description and
-gets the ruleset using pango_ot_ruleset_get_for().
+gets the ruleset using pango_ot_ruleset_get_for_description()
+or create a new one using pango_ot_ruleset_new_from_description().
 </para>
 
 @script: a #PangoScript.
@@ -348,7 +349,7 @@ is not found.
 @glyphs: 
 
 
-<!-- ##### FUNCTION pango_ot_ruleset_get_for ##### -->
+<!-- ##### FUNCTION pango_ot_ruleset_get_for_description ##### -->
 <para>
 
 </para>
@@ -378,6 +379,16 @@ is not found.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_ot_ruleset_new_from_description ##### -->
+<para>
+
+</para>
+
+@info: 
+@desc: 
+@Returns: 
+
+
 <!-- ##### FUNCTION pango_ot_ruleset_add_feature ##### -->
 <para>
 
diff --git a/modules/arabic/arabic-fc.c b/modules/arabic/arabic-fc.c
index 9635278b..e7f53bd8 100644
--- a/modules/arabic/arabic-fc.c
+++ b/modules/arabic/arabic-fc.c
@@ -172,7 +172,7 @@ arabic_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   pango_ot_ruleset_substitute (ruleset, buffer);
   pango_ot_ruleset_position (ruleset, buffer);
diff --git a/modules/basic/basic-fc.c b/modules/basic/basic-fc.c
index 85687f1b..d8587256 100644
--- a/modules/basic/basic-fc.c
+++ b/modules/basic/basic-fc.c
@@ -201,7 +201,7 @@ basic_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   pango_ot_ruleset_substitute (ruleset, buffer);
   pango_ot_ruleset_position (ruleset, buffer);
diff --git a/modules/hebrew/hebrew-fc.c b/modules/hebrew/hebrew-fc.c
index baff892d..7f59b281 100644
--- a/modules/hebrew/hebrew-fc.c
+++ b/modules/hebrew/hebrew-fc.c
@@ -263,7 +263,7 @@ hebrew_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   pango_ot_ruleset_get_feature_count (ruleset, NULL, &n_gpos_features);
   if (n_gpos_features == 0)
diff --git a/modules/indic/indic-fc.c b/modules/indic/indic-fc.c
index 09f70545..d73b94dc 100644
--- a/modules/indic/indic-fc.c
+++ b/modules/indic/indic-fc.c
@@ -268,7 +268,7 @@ indic_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   /* do gsub processing */
   pango_ot_ruleset_substitute (ruleset, buffer);
diff --git a/modules/khmer/khmer-fc.c b/modules/khmer/khmer-fc.c
index 05011c5f..7c2486cd 100644
--- a/modules/khmer/khmer-fc.c
+++ b/modules/khmer/khmer-fc.c
@@ -665,7 +665,7 @@ khmer_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   pango_ot_ruleset_substitute (ruleset, buffer);
   pango_ot_ruleset_position (ruleset, buffer);
diff --git a/modules/syriac/syriac-fc.c b/modules/syriac/syriac-fc.c
index be4aff9c..cbdce5be 100644
--- a/modules/syriac/syriac-fc.c
+++ b/modules/syriac/syriac-fc.c
@@ -162,7 +162,7 @@ syriac_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   pango_ot_ruleset_substitute (ruleset, buffer);
   pango_ot_ruleset_position (ruleset, buffer);
diff --git a/modules/thai/thai-fc.c b/modules/thai/thai-fc.c
index 68459926..d97b9306 100644
--- a/modules/thai/thai-fc.c
+++ b/modules/thai/thai-fc.c
@@ -290,7 +290,7 @@ thai_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   font_info = thai_get_font_info (font, ruleset);
 
diff --git a/modules/tibetan/tibetan-fc.c b/modules/tibetan/tibetan-fc.c
index 57dd6133..ff65071c 100644
--- a/modules/tibetan/tibetan-fc.c
+++ b/modules/tibetan/tibetan-fc.c
@@ -518,7 +518,7 @@ tibetan_engine_shape (PangoEngineShape *engine,
   desc.n_other_features = 0;
   desc.other_features = NULL;
 
-  ruleset = pango_ot_ruleset_get_for (pango_ot_info_get (face), &desc);
+  ruleset = pango_ot_ruleset_get_for_description (pango_ot_info_get (face), &desc);
 
   pango_ot_ruleset_substitute (ruleset, buffer);
   pango_ot_ruleset_position (ruleset, buffer);
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 6dd60377..f0949387 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -95,12 +95,14 @@ pango_ot_ruleset_finalize (GObject *object)
 }
 
 /**
- * pango_ot_ruleset_get_for:
+ * pango_ot_ruleset_get_for_description:
  * @info: a #PangoOTInfo.
  * @desc: a #PangoOTRulesetDescription.
  *
  * Returns a ruleset for the given OpenType info and ruleset
- * description.  The returned ruleset should not be modified.
+ * description.  Rulesets are created on demand using
+ * pango_ot_ruleset_new_from_description().
+ * The returned ruleset should not be modified or destroyed.
  *
  * The static feature map members of @desc should be alive as
  * long as @info is.
@@ -111,8 +113,8 @@ pango_ot_ruleset_finalize (GObject *object)
  * Since: 1.18
  **/
 const PangoOTRuleset *
-pango_ot_ruleset_get_for (PangoOTInfo                     *info,
-			  const PangoOTRulesetDescription *desc)
+pango_ot_ruleset_get_for_description (PangoOTInfo                     *info,
+				      const PangoOTRulesetDescription *desc)
 {
   PangoOTRuleset *ruleset;
   static GQuark rulesets_quark = 0;
@@ -140,28 +142,7 @@ pango_ot_ruleset_get_for (PangoOTInfo                     *info,
 
   if (!ruleset)
     {
-      ruleset = pango_ot_ruleset_new_for (info,
-					  desc->script,
-					  desc->language);
-
-      if (desc->n_static_gsub_features)
-	pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GSUB,
-					     desc->static_gsub_features,
-					     desc->n_static_gsub_features);
-      if (desc->n_static_gpos_features)
-	pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GPOS,
-					     desc->static_gpos_features,
-					     desc->n_static_gpos_features);
-
-      if (desc->n_other_features)
-        {
-	  pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GSUB,
-					       desc->other_features,
-					       desc->n_other_features);
-	  pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GPOS,
-					       desc->other_features,
-					       desc->n_other_features);
-	}
+      ruleset = pango_ot_ruleset_new_from_description (info, desc);
 
       g_hash_table_insert (rulesets,
 			   pango_ot_ruleset_description_copy (desc),
@@ -288,6 +269,61 @@ pango_ot_ruleset_new_for (PangoOTInfo       *info,
 }
 
 /**
+ * pango_ot_ruleset_new_from_description:
+ * @info: a #PangoOTInfo.
+ * @desc: a #PangoOTRulesetDescription.
+ *
+ * Creates a new #PangoOTRuleset for the given OpenType infor and
+ * matching the given ruleset description.
+ *
+ * This is a convenience function that calls pango_ot_ruleset_new_for() and
+ * adds the static GSUB/GPOS features to the resulting ruleset, followed by
+ * adding other features to both GSUB and GPOS.
+ *
+ * The static feature map members of @desc should be alive as
+ * long as @info is.
+ *
+ * Return value: the newly allocated #PangoOTRuleset, which
+ *               should be freed with g_object_unref().
+ *
+ * Since: 1.18
+ **/
+PangoOTRuleset *
+pango_ot_ruleset_new_from_description (PangoOTInfo                     *info,
+				       const PangoOTRulesetDescription *desc)
+{
+  PangoOTRuleset *ruleset;
+
+  g_return_val_if_fail (info != NULL, NULL);
+  g_return_val_if_fail (desc != NULL, NULL);
+
+  ruleset = pango_ot_ruleset_new_for (info,
+				      desc->script,
+				      desc->language);
+
+  if (desc->n_static_gsub_features)
+    pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GSUB,
+					 desc->static_gsub_features,
+					 desc->n_static_gsub_features);
+  if (desc->n_static_gpos_features)
+    pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GPOS,
+					 desc->static_gpos_features,
+					 desc->n_static_gpos_features);
+
+  if (desc->n_other_features)
+    {
+      pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GSUB,
+					   desc->other_features,
+					   desc->n_other_features);
+      pango_ot_ruleset_maybe_add_features (ruleset, PANGO_OT_TABLE_GPOS,
+					   desc->other_features,
+					   desc->n_other_features);
+    }
+
+  return ruleset;
+}
+
+/**
  * pango_ot_ruleset_add_feature:
  * @ruleset: a #PangoOTRuleset.
  * @table_type: the table type to add a feature to.
@@ -627,8 +663,8 @@ pango_ot_ruleset_description_equal (const PangoOTRulesetDescription *desc1,
  *
  * Creates a copy of @desc, which should be freed with
  * pango_ot_ruleset_description_free(). Primarily used internally
- * by pango_ot_ruleset_get_for() to cache rulesets for ruleset
- * descriptions.
+ * by pango_ot_ruleset_get_for_description() to cache rulesets for
+ * ruleset descriptions.
  *
  * Return value: the newly allocated #PangoOTRulesetDescription, which
  *               should be freed with pango_ot_ruleset_description_free().
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index e1ea45e1..60d2a55c 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -134,12 +134,14 @@ void           pango_ot_buffer_output     (const PangoOTBuffer  *buffer,
 void           pango_ot_buffer_set_zero_width_marks (PangoOTBuffer     *buffer,
 						     gboolean           zero_width_marks);
 
-const PangoOTRuleset *pango_ot_ruleset_get_for (PangoOTInfo                     *info,
-						const PangoOTRulesetDescription *desc);
+const PangoOTRuleset *pango_ot_ruleset_get_for_description (PangoOTInfo                     *info,
+							    const PangoOTRulesetDescription *desc);
 PangoOTRuleset *pango_ot_ruleset_new (PangoOTInfo       *info);
 PangoOTRuleset *pango_ot_ruleset_new_for (PangoOTInfo       *info,
 					  PangoScript        script,
 					  PangoLanguage     *language);
+PangoOTRuleset *pango_ot_ruleset_new_from_description (PangoOTInfo                     *info,
+						       const PangoOTRulesetDescription *desc);
 void            pango_ot_ruleset_add_feature (PangoOTRuleset   *ruleset,
 					      PangoOTTableType  table_type,
 					      guint             feature_index,
diff --git a/pango/pangoft2.def b/pango/pangoft2.def
index 50e625d8..79165939 100644
--- a/pango/pangoft2.def
+++ b/pango/pangoft2.def
@@ -63,12 +63,13 @@ EXPORTS
 	pango_ot_ruleset_description_free
 	pango_ot_ruleset_description_hash
 	pango_ot_ruleset_get_feature_count
-	pango_ot_ruleset_get_for
+	pango_ot_ruleset_get_for_description
 	pango_ot_ruleset_get_type
 	pango_ot_ruleset_maybe_add_feature
 	pango_ot_ruleset_maybe_add_features
 	pango_ot_ruleset_new
 	pango_ot_ruleset_new_for
+	pango_ot_ruleset_new_from_description
 	pango_ot_ruleset_position
 	pango_ot_ruleset_substitute
 	pango_ot_tag_from_language