API updates (removed SLV2Value (binary compatibility nightmare waiting to happen) and added consistent SLV2Plugins and SLV2Strings).

Documentation cleanups.


git-svn-id: http://svn.drobilla.net/lad/slv2@314 a436a847-0d15-0410-975c-d299462d15a1

11 files changed, 128 insertions, 80 deletions

diff --git a/slv2/Makefile.am b/slv2/Makefile.am
index d2153ef..8ce74f2 100644
--- a/slv2/Makefile.am
+++ b/slv2/Makefile.am
@@ -11,4 +11,5 @@ slv2include_HEADERS = \
 	port.h \
 	pluginlist.h \
 	plugininstance.h \
-	util.h
+	util.h \
+	stringlist.h
diff --git a/slv2/plugin.h b/slv2/plugin.h
index 5555437..05bba75 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -32,7 +32,7 @@ extern "C" {
 typedef const struct _Plugin SLV2Plugin;
 
 
-/** \defgroup data Plugin data file access
+/** \defgroup data Plugin - RDF data access
  *
  * These functions work exclusively with the plugin's RDF data file.  They do
  * not load the plugin dynamic library (or access
@@ -95,7 +95,7 @@ slv2_plugin_get_uri(const SLV2Plugin* plugin);
  * \return a complete URL eg. "file:///usr/foo/SomeBundle.lv2/someplug.ttl",
  * which is shared and must not be modified or free()'d.
  */
-SLV2URIList
+SLV2Strings
 slv2_plugin_get_data_uris(const SLV2Plugin* plugin);
 
 
@@ -124,7 +124,7 @@ slv2_plugin_get_name(const SLV2Plugin* plugin);
 /** Request some arbitrary RDF object of the plugin.
  *
  * May return NULL if the property was not found (ie is not defined in the
- * data file), or if object is not sensibly represented as an SLV2Value
+ * data file), or if object is not sensibly represented as an SLV2Strings
  * (e.g. blank nodes).
  *
  * Return value must be freed by caller with slv2_value_free.
@@ -134,7 +134,7 @@ slv2_plugin_get_name(const SLV2Plugin* plugin);
  * $LANG will be returned if it is set.  Otherwise all values will be
  * returned.
  */
-SLV2Value
+SLV2Strings
 slv2_plugin_get_value(const SLV2Plugin* p,
                       const char*       predicate);
 
@@ -147,7 +147,7 @@ slv2_plugin_get_value(const SLV2Plugin* p,
  *
  * Return value must be freed by caller with slv2_value_free.
  */
-SLV2Value
+SLV2Strings
 slv2_plugin_get_properties(const SLV2Plugin* p);
 
 
@@ -158,7 +158,7 @@ slv2_plugin_get_properties(const SLV2Plugin* p);
  *
  * Return value must be freed by caller with slv2_value_free.
  */
-SLV2Value
+SLV2Strings
 slv2_plugin_get_hints(const SLV2Plugin* p);
 
 
@@ -193,7 +193,7 @@ slv2_plugin_get_latency_port(const SLV2Plugin* p);
  *
  * This returns a list of all supported features (both required and optional).
  */
-SLV2Value
+SLV2Strings
 slv2_plugin_get_supported_features(const SLV2Plugin* p);
 
 
@@ -202,7 +202,7 @@ slv2_plugin_get_supported_features(const SLV2Plugin* p);
  * All feature URI's returned by this call MUST be passed to the plugin's
  * instantiate method for the plugin to instantiate successfully.
  */
-SLV2Value
+SLV2Strings
 slv2_plugin_get_required_features(const SLV2Plugin* p);
 
 
@@ -212,7 +212,7 @@ slv2_plugin_get_required_features(const SLV2Plugin* p);
  * instantiate method, those features will be used by the function, otherwise
  * the plugin will act as it would if it did not support that feature at all.
  */
-SLV2Value
+SLV2Strings
 slv2_plugin_get_optional_features(const SLV2Plugin* p);
 
 
diff --git a/slv2/plugininstance.h b/slv2/plugininstance.h
index bf86010..1b475c2 100644
--- a/slv2/plugininstance.h
+++ b/slv2/plugininstance.h
@@ -34,7 +34,7 @@ extern "C" {
 typedef const struct _Instance SLV2Instance;
 
 
-/** \defgroup lib Plugin library access
+/** \defgroup lib Plugin Instance - Shared library access
  *
  * An SLV2Instance is an instantiated SLV2Plugin (eg a loaded dynamic
  * library).  These functions interact with the binary library code only,
diff --git a/slv2/pluginlist.h b/slv2/pluginlist.h
index aca3bb7..5410bc3 100644
--- a/slv2/pluginlist.h
+++ b/slv2/pluginlist.h
@@ -24,16 +24,16 @@ extern "C" {
 #endif
 
 
-typedef struct _PluginList* SLV2List;
+typedef struct _PluginList* SLV2Plugins;
 
 
-/** \defgroup lists Plugin discovery
- *
+/** \defgroup plugins Plugins - Collection of plugins, plugin discovery
+ * 
  * These functions are for locating plugins installed on the system.
  *
  * Normal hosts which just want to easily load plugins by URI are strongly
  * recommended to simply find all installed plugins with
- * \ref slv2_list_load_all rather than find and load bundles manually.
+ * \ref slv2_plugins_load_all rather than find and load bundles manually.
  * 
  * Functions are provided for hosts that wish to access bundles explicitly and
  * individually for some reason, as well as make custom lists of plugins from
@@ -46,10 +46,10 @@ typedef struct _PluginList* SLV2List;
 
 /** Create a new, empty plugin list.
  *
- * Returned object must be freed with slv2_list_free.
+ * Returned object must be freed with slv2_plugins_free.
  */
-SLV2List
-slv2_list_new();
+SLV2Plugins
+slv2_plugins_new();
 
 
 /** Free a plugin list.
@@ -61,10 +61,10 @@ slv2_list_new();
  * will have to copy it with slv2_plugin_duplicate().
  *
  * \a list is invalid after this call (though it may be used again after a
- * "list = slv2_list_new()")
+ * "list = slv2_plugins_new()")
  */
 void
-slv2_list_free(SLV2List list);
+slv2_plugins_free(SLV2Plugins list);
 
 
 /** Add all plugins installed on the system to \a list.
@@ -81,18 +81,18 @@ slv2_list_free(SLV2List list);
  * discouraged without a special reason to do so - use this one.
  */
 void
-slv2_list_load_all(SLV2List list);
+slv2_plugins_load_all(SLV2Plugins list);
 
 
 /** Add all plugins found in \a search_path to \a list.
  *
  * If \a search_path is NULL, \a list will be unmodified.
  *
- * Use of this function is \b not recommended.  Use \ref slv2_list_load_all.
+ * Use of this function is \b not recommended.  Use \ref slv2_plugins_load_all.
  */
 void
-slv2_list_load_path(SLV2List    list,
-                    const char* search_path);
+slv2_plugins_load_path(SLV2Plugins    list,
+                       const char* search_path);
 
 
 /** Add all plugins found in the bundle at \a bundle_base_url to \a list.
@@ -105,35 +105,37 @@ slv2_list_load_path(SLV2List    list,
  * remain consistent whatsoever.  This function should only be used by apps
  * which ship with a special bundle (which it knows exists at some path).
  * It is \b not to be used by normal hosts that want to load system
- * installed plugins.  Use \ref slv2_list_load_all for that.
+ * installed plugins.  Use \ref slv2_plugins_load_all for that.
  */
 void
-slv2_list_load_bundle(SLV2List    list,
-                      const char* bundle_base_url);
+slv2_plugins_load_bundle(SLV2Plugins    list,
+                         const char* bundle_base_url);
 
 
 /** Get the number of plugins in the list.
  */
 size_t
-slv2_list_get_length(const SLV2List list);
+slv2_plugins_size(const SLV2Plugins list);
 
 
 /** Get a plugin from the list by URI.
  *
  * Return value is shared (stored in \a list) and must not be freed or
  * modified by the caller in any way.
+ * This functions is a search, slv2_plugins_get_at is
+ * significantly faster.
  * 
  * \return NULL if plugin with \a url not found in \a list.
  */
 const SLV2Plugin*
-slv2_list_get_plugin_by_uri(const SLV2List list,
-                            const char*    uri);
+slv2_plugins_get_by_uri(const SLV2Plugins list,
+                               const char*    uri);
 
 
 /** Get a plugin from the list by index.
  *
  * \a index has no significance.  Any \a index not less than
- * slv2list_get_length(list) will return NULL.  * All plugins in a list can
+ * slv2list_get_length(list) will return NULL.  All plugins in a list can
  * thus be easily enumerated by repeated calls to this function starting
  * with \a index 0.
  *
@@ -143,8 +145,8 @@ slv2_list_get_plugin_by_uri(const SLV2List list,
  * \return NULL if \a index out of range.
  */
 const SLV2Plugin*
-slv2_list_get_plugin_by_index(const SLV2List list,
-                              size_t         index);
+slv2_plugins_get_at(const SLV2Plugins list,
+                                 size_t         index);
 
 
 /** @} */
diff --git a/slv2/port.h b/slv2/port.h
index 5c29774..9106a9c 100644
--- a/slv2/port.h
+++ b/slv2/port.h
@@ -23,8 +23,9 @@
 extern "C" {
 #endif
 
-#include "types.h"
-#include "plugin.h"
+#include <slv2/types.h>
+#include <slv2/plugin.h>
+#include <slv2/stringlist.h>
 
 /** \addtogroup data
  * @{
@@ -45,7 +46,7 @@ slv2_port_by_symbol(const char* symbol);
 
 /** Port equivalent to slv2_plugin_get_value.
  */
-SLV2Value
+SLV2Strings
 slv2_port_get_value(SLV2Plugin* plugin,
                     SLV2PortID  id,
                     const char* property);
@@ -53,14 +54,14 @@ slv2_port_get_value(SLV2Plugin* plugin,
 
 /** Port equivalent to slv2_plugin_get_properties.
  */
-SLV2Value
+SLV2Strings
 slv2_port_get_properties(const SLV2Plugin* p,
                          SLV2PortID        id);
 
 
 /** Port equivalent to slv2_plugin_get_hints.
  */
-SLV2Value
+SLV2Strings
 slv2_port_get_hints(const SLV2Plugin* p,
                     SLV2PortID        id);
 
diff --git a/slv2/private_types.h b/slv2/private_types.h
index cfdcb9c..abda0a1 100644
--- a/slv2/private_types.h
+++ b/slv2/private_types.h
@@ -69,9 +69,10 @@ struct _PluginList {
 };
 
 
-typedef raptor_sequence* SLV2URIList;
+/** An ordered, indexable collection of strings. */
+typedef raptor_sequence* SLV2Strings;
 
-SLV2URIList slv2_uri_list_new();
+SLV2Strings slv2_strings_new();
 
 
 #ifdef __cplusplus
diff --git a/slv2/query.h b/slv2/query.h
index 3faba15..ea78735 100644
--- a/slv2/query.h
+++ b/slv2/query.h
@@ -82,11 +82,15 @@ rasqal_query_results*
 slv2_plugin_query(SLV2Plugin* plugin,
                   const char* sparql_str);
 
-SLV2Value
+SLV2Strings
 slv2_plugin_simple_query(SLV2Plugin* plugin,
                          const char* sparql_str,
                          const char* variable);
 
+unsigned
+slv2_plugin_query_count(SLV2Plugin* plugin,
+                        const char* sparql_str);
+
 #if 0
 /** Run a SPARQL query on a plugin's data file and return variable matches.
  *
@@ -96,7 +100,7 @@ slv2_plugin_simple_query(SLV2Plugin* plugin,
  *
  * Returned is a list of all matches for the query variable \a var_name.
  */
-SLV2Value
+SLV2Strings
 slv2_query_get_results(const SLV2Plugin* p,
                        const char*       query_string,
                        const char*       var_name);
diff --git a/slv2/slv2.h b/slv2/slv2.h
index 44744c9..07e9201 100644
--- a/slv2/slv2.h
+++ b/slv2/slv2.h
@@ -30,6 +30,7 @@ extern "C" {
 #include <slv2/plugin.h>
 #include <slv2/plugininstance.h>
 #include <slv2/pluginlist.h>
+#include <slv2/stringlist.h>
 #include <slv2/port.h>
 
 
diff --git a/slv2/stringlist.h b/slv2/stringlist.h
new file mode 100644
index 0000000..5ed711b
--- /dev/null
+++ b/slv2/stringlist.h
@@ -0,0 +1,69 @@
+/* SLV2
+ * Copyright (C) 2007 Dave Robillard <http://drobilla.net>
+ *  
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU 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 General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __SLV2_STRINGLIST_H__
+#define __SLV2_STRINGLIST_H__
+
+#include <slv2/private_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/** \defgroup strings Strings - Collection of strings
+ *
+ * SLV2Strings is an ordered collection of strings which is fast for random
+ * access by index (i.e. a fancy array).
+ *
+ * @{
+ */
+
+/** Get the number of elements in a string list.
+ */
+int
+slv2_strings_size(const SLV2Strings list);
+
+
+/** Get a string from a string list at the given index.
+ *
+ * @return the element at @a index, or NULL if index is out of range.
+ */
+char*
+slv2_strings_get_at(const SLV2Strings list, int index);
+
+
+/** Return whether @a list contains @a uri.
+ */
+bool
+slv2_strings_contains(const SLV2Strings list, const char* uri);
+
+
+/** Free a string list. */
+void
+slv2_strings_free(SLV2Strings);
+
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __SLV2_STRINGLIST_H__ */
+
diff --git a/slv2/types.h b/slv2/types.h
index 4fb8cf4..018c8e2 100644
--- a/slv2/types.h
+++ b/slv2/types.h
@@ -29,22 +29,6 @@ extern "C" {
 #endif
 
 
-/* A property, resulting from a query.
- *
- * Note that properties may have many values.
- */
-struct _Value {
-	size_t num_values;
-	char** values;
-};
-
-typedef struct _Value* SLV2Value;
-
-
-/** Free an SLV2Value. */
-void
-slv2_value_free(SLV2Value);
-
 
 /** Port ID type, to allow passing either symbol or index
  * to port related functions.
@@ -73,25 +57,6 @@ typedef enum _PortClass {
 } SLV2PortClass;
 
 
-/** Get the number of elements in a URI list.
- */
-int
-slv2_uri_list_size(const SLV2URIList list);
-
-
-/** Get a URI from a URI list at the given index.
- *
- * @return the element at @index, or NULL if index is out of range.
- */
-char*
-slv2_uri_list_get_at(const SLV2URIList list, int index);
-
-
-/** Return whether @list contains @uri.
- */
-bool
-slv2_uri_list_contains(const SLV2URIList list, const char* uri);
-
 #ifdef __cplusplus
 }
 #endif
diff --git a/slv2/util.h b/slv2/util.h
index f6c90d4..eb8dea7 100644
--- a/slv2/util.h
+++ b/slv2/util.h
@@ -32,6 +32,12 @@ extern "C" {
 #endif
 
 
+/** \defgroup util Utility functions
+ *
+ * @{
+ */
+
+
 /** Convert a full URI (eg file://foo/bar/baz.ttl) to a local path (e.g. /foo/bar/baz.ttl).
  *
  * Return value is shared and must not be deleted by caller.
@@ -61,9 +67,7 @@ char*
 slv2_vstrjoin(const char** first, va_list args_list);
 
 
-const char*
-slv2_url2path(const char* const url);
-
+/** @} */
 
 #ifdef __cplusplus
 }