API: add gst_tag_parse_extended_comment() (#351426).

Original commit message from CVS:
* docs/libs/gst-plugins-base-libs-sections.txt:
* gst-libs/gst/tag/tag.h:
* gst-libs/gst/tag/tags.c: (gst_tag_parse_extended_comment):
API: add gst_tag_parse_extended_comment() (#351426).
* tests/check/Makefile.am:
* tests/check/libs/.cvsignore:
* tests/check/libs/tag.c: (GST_START_TEST), (tag_suite), (main):
Add unit test for gst_tag_parse_extended_comment().

ChangeLog

@@ -1,3 +1,15 @@
+2006-08-16  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/libs/gst-plugins-base-libs-sections.txt:
+	* gst-libs/gst/tag/tag.h:
+	* gst-libs/gst/tag/tags.c: (gst_tag_parse_extended_comment):
+	  API: add gst_tag_parse_extended_comment() (#351426).
+
+	* tests/check/Makefile.am:
+	* tests/check/libs/.cvsignore:
+	* tests/check/libs/tag.c: (GST_START_TEST), (tag_suite), (main):
+	  Add unit test for gst_tag_parse_extended_comment().
+
 2006-08-15  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* sys/ximage/ximagesink.c: (gst_ximagesink_get_property):

docs/libs/gst-plugins-base-libs-sections.txt

@@ -853,6 +853,7 @@ GST_TAG_CMML_CLIP
 GST_TAG_CMML_HEAD
 GST_TAG_CMML_STREAM
 gst_tag_register_musicbrainz_tags
+gst_tag_parse_extended_comment
 GstTagImageType
 <SUBSECTION Standard>
 GST_TYPE_TAG_IMAGE_TYPE

gst-libs/gst/tag/tag.h

@@ -171,6 +171,15 @@ G_CONST_RETURN gchar *  gst_tag_from_id3_user_tag               (const gchar *
                                                                  const gchar *          id3_user_tag);
 G_CONST_RETURN gchar *  gst_tag_to_id3_tag                      (const gchar *          gst_tag);
 
+/* other tag-related functions */
+
+gboolean                gst_tag_parse_extended_comment (const gchar  * ext_comment,
+                                                        gchar       ** key,
+                                                        gchar       ** lang,
+                                                        gchar       ** value,
+                                                        gboolean       fail_if_no_key);
+
+/* FIXME 0.11: replace with a more general gst_tag_library_init() */
 void gst_tag_register_musicbrainz_tags (void);
 
 G_END_DECLS

gst-libs/gst/tag/tags.c

@@ -1,7 +1,6 @@
-/* GStreamer
+/* GStreamer non-core tag registration and tag utility functions
  * Copyright (C) 2005 Ross Burton <ross@burtonini.com>
- *
- * tags.c: Non-core tag registration
+ * Copyright (C) 2006 Tim-Philipp Müller <tim centricular net>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -27,6 +26,8 @@
 #include <gst/gst.h>
 #include "tag.h"
 
+#include <string.h>
+
 /**
  * SECTION:gsttag
  * @short_description: additional tag definitions for plugins and applications
@@ -137,3 +138,67 @@ gst_tag_image_type_get_type (void)
   g_once (&once, (GThreadFunc) register_tag_image_type_enum, &id);
   return id;
 }
+
+/**
+ * gst_tag_parse_extended_comment:
+ * @ext_comment: an extended comment string, see #GST_TAG_EXTENDED_COMMENT
+ * @key: return location for the comment description key, or NULL
+ * @lang: return location for the comment ISO-639 language code, or NULL
+ * @value: return location for the actual comment string, or NULL
+ * @fail_if_no_key: whether to fail if strings are not in key=value form
+ *
+ * Convenience function to parse a GST_TAG_EXTENDED_COMMENT string and
+ * separate it into its components.
+ *
+ * If successful, @key, @lang and/or @value will be set to newly allocated
+ * strings that you need to free with g_free() when done. @key and @lang
+ * may also be set to NULL by this function if there is no key or no language
+ * code in the extended comment string.
+ *
+ * Returns: TRUE if the string could be parsed, otherwise FALSE
+ *
+ * Since: 0.10.10
+ */
+gboolean
+gst_tag_parse_extended_comment (const gchar * ext_comment, gchar ** key,
+    gchar ** lang, gchar ** value, gboolean fail_if_no_key)
+{
+  const gchar *div, *bop, *bcl;
+
+  g_return_val_if_fail (ext_comment != NULL, FALSE);
+  g_return_val_if_fail (g_utf8_validate (ext_comment, -1, NULL), FALSE);
+
+  if (key)
+    *key = NULL;
+  if (lang)
+    *lang = NULL;
+
+  div = strchr (ext_comment, '=');
+  bop = strchr (ext_comment, '[');
+  bcl = strchr (ext_comment, ']');
+
+  if (div == NULL) {
+    if (fail_if_no_key)
+      return FALSE;
+    if (value)
+      *value = g_strdup (ext_comment);
+    return TRUE;
+  }
+
+  if (bop != NULL && bop < div) {
+    if (bcl < bop || bcl > div)
+      return FALSE;
+    if (key)
+      *key = g_strndup (ext_comment, bop - ext_comment);
+    if (lang)
+      *lang = g_strndup (bop + 1, bcl - bop - 1);
+  } else {
+    if (key)
+      *key = g_strndup (ext_comment, div - ext_comment);
+  }
+
+  if (value)
+    *value = g_strdup (div + 1);
+
+  return TRUE;
+}

tests/check/Makefile.am

@@ -55,6 +55,7 @@ check_PROGRAMS = \
 	generic/states \
 	libs/audio \
 	libs/cddabasesrc \
+	libs/tag \
 	libs/video \
         pipelines/simple-launch-lines
 
@@ -92,6 +93,10 @@ libs_cddabasesrc_CFLAGS = \
 	-I$(top_srcdir)/gst-libs \
 	$(CFLAGS) $(AM_CFLAGS)
 
+libs_tag_LDADD = \
+	$(top_builddir)/gst-libs/gst/tag/libgsttag-@GST_MAJORMINOR@.la $(LDADD)
+libs_tag_CFLAGS = -I$(top_srcdir)/gst-libs $(CFLAGS) $(AM_CFLAGS)
+
 elements_alsa_LDADD = \
 	$(top_builddir)/gst-libs/gst/interfaces/libgstinterfaces-@GST_MAJORMINOR@.la \
 	$(LDADD)

tests/check/libs/.gitignore

@@ -2,3 +2,4 @@
 cddabasesrc
 video
 audio
+tag

tests/check/libs/tag.c

@@ -0,0 +1,163 @@
+/* GStreamer
+ *
+ * unit tests for the tag support library
+ *
+ * Copyright (C) 2006 Tim-Philipp Müller <tim centricular net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <gst/check/gstcheck.h>
+
+#include <gst/tag/tag.h>
+#include <string.h>
+
+GST_START_TEST (test_parse_extended_comment)
+{
+  gchar *key, *val, *lang;
+
+  /* first check the g_return_val_if_fail conditions */
+  ASSERT_CRITICAL (gst_tag_parse_extended_comment (NULL, NULL, NULL, NULL,
+          FALSE));
+  ASSERT_CRITICAL (gst_tag_parse_extended_comment ("\777\000", NULL, NULL, NULL,
+          FALSE));
+
+  key = val = lang = NULL;
+  fail_unless (gst_tag_parse_extended_comment ("a=b", &key, &lang, &val,
+          FALSE) == TRUE);
+  fail_unless (key != NULL);
+  fail_unless (lang == NULL);
+  fail_unless (val != NULL);
+  fail_unless_equals_string (key, "a");
+  fail_unless_equals_string (val, "b");
+  g_free (key);
+  g_free (lang);
+  g_free (val);
+
+  key = val = lang = NULL;
+  fail_unless (gst_tag_parse_extended_comment ("a[l]=b", &key, &lang, &val,
+          FALSE) == TRUE);
+  fail_unless (key != NULL);
+  fail_unless (lang != NULL);
+  fail_unless (val != NULL);
+  fail_unless_equals_string (key, "a");
+  fail_unless_equals_string (lang, "l");
+  fail_unless_equals_string (val, "b");
+  g_free (key);
+  g_free (lang);
+  g_free (val);
+
+  key = val = lang = NULL;
+  fail_unless (gst_tag_parse_extended_comment ("foo=bar", &key, &lang, &val,
+          FALSE) == TRUE);
+  fail_unless (key != NULL);
+  fail_unless (lang == NULL);
+  fail_unless (val != NULL);
+  fail_unless_equals_string (key, "foo");
+  fail_unless_equals_string (val, "bar");
+  g_free (key);
+  g_free (lang);
+  g_free (val);
+
+  key = val = lang = NULL;
+  fail_unless (gst_tag_parse_extended_comment ("foo[fr]=bar", &key, &lang, &val,
+          FALSE) == TRUE);
+  fail_unless (key != NULL);
+  fail_unless (lang != NULL);
+  fail_unless (val != NULL);
+  fail_unless_equals_string (key, "foo");
+  fail_unless_equals_string (lang, "fr");
+  fail_unless_equals_string (val, "bar");
+  g_free (key);
+  g_free (lang);
+  g_free (val);
+
+  key = val = lang = NULL;
+  fail_unless (gst_tag_parse_extended_comment ("foo=[fr]bar", &key, &lang, &val,
+          FALSE) == TRUE);
+  fail_unless (key != NULL);
+  fail_unless (lang == NULL);
+  fail_unless (val != NULL);
+  fail_unless_equals_string (key, "foo");
+  fail_unless_equals_string (val, "[fr]bar");
+  g_free (key);
+  g_free (lang);
+  g_free (val);
+
+  /* test NULL for output locations */
+  fail_unless (gst_tag_parse_extended_comment ("foo[fr]=bar", NULL, NULL, NULL,
+          FALSE) == TRUE);
+
+  /* test strict mode (key must be specified) */
+  fail_unless (gst_tag_parse_extended_comment ("foo[fr]=bar", NULL, NULL, NULL,
+          TRUE) == TRUE);
+  fail_unless (gst_tag_parse_extended_comment ("foo=bar", NULL, NULL, NULL,
+          TRUE) == TRUE);
+  fail_unless (gst_tag_parse_extended_comment ("foobar", NULL, NULL, NULL,
+          TRUE) == FALSE);
+
+  /* test non-strict mode (if there's no key, that's fine too) */
+  fail_unless (gst_tag_parse_extended_comment ("foobar", NULL, NULL, NULL,
+          FALSE) == TRUE);
+  fail_unless (gst_tag_parse_extended_comment ("[fr]bar", NULL, NULL, NULL,
+          FALSE) == TRUE);
+
+  key = val = lang = NULL;
+  fail_unless (gst_tag_parse_extended_comment ("[fr]bar", &key, &lang, &val,
+          FALSE) == TRUE);
+  fail_unless (key == NULL);
+  fail_unless (lang == NULL);
+  fail_unless (val != NULL);
+  fail_unless_equals_string (val, "[fr]bar");
+  g_free (key);
+  g_free (lang);
+  g_free (val);
+}
+
+GST_END_TEST;
+
+static Suite *
+tag_suite (void)
+{
+  Suite *s = suite_create ("tag support library");
+  TCase *tc_chain = tcase_create ("general");
+
+  suite_add_tcase (s, tc_chain);
+  tcase_add_test (tc_chain, test_parse_extended_comment);
+
+  return s;
+}
+
+int
+main (int argc, char **argv)
+{
+  int nf;
+
+  Suite *s = tag_suite ();
+  SRunner *sr = srunner_create (s);
+
+  gst_check_init (&argc, &argv);
+
+  srunner_run_all (sr, CK_NORMAL);
+  nf = srunner_ntests_failed (sr);
+  srunner_free (sr);
+
+  return nf;
+}