Overhaul SLV2 API to return/take SLV2Value (instead of strings or primitives) wherever possible.

Make 'index' a fundemental property of ingen ports.


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

12 files changed, 86 insertions, 158 deletions

diff --git a/slv2/lv2_ui.h b/slv2/lv2_ui.h
index 744a71c..4e99232 100644
--- a/slv2/lv2_ui.h
+++ b/slv2/lv2_ui.h
@@ -189,8 +189,8 @@ typedef struct _LV2UI_Descriptor {
                         as the first parameter of @c write_function.

       @param host_data  Data required from the host for instantiation.

                         The type of this depends on the RDF class of the UI.

-			If the UI type does not specify anything to be passed

-			here, the host should pass NULL.

+                        If the UI type does not specify anything to be passed

+                        here, the host should pass NULL.

       @param widget     A pointer to an LV2UI_Widget. The UI will write a

                         widget pointer to this location (what type of widget 

                         depends on the RDF class of the UI) that will be the

diff --git a/slv2/plugin.h b/slv2/plugin.h
index 3dc63a8..a3ae1f0 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -76,7 +76,7 @@ slv2_plugin_verify(SLV2Plugin plugin);
  *
  * Time = O(1)
  */
-const char*
+SLV2Value
 slv2_plugin_get_uri(SLV2Plugin plugin);
 
 
@@ -95,7 +95,7 @@ slv2_plugin_get_uri(SLV2Plugin plugin);
  *
  * Time = O(1)
  */
-const char*
+SLV2Value
 slv2_plugin_get_bundle_uri(SLV2Plugin plugin);
 
 
@@ -124,7 +124,7 @@ slv2_plugin_get_data_uris(SLV2Plugin plugin);
  *
  * Time = O(1)
  */
-const char*
+SLV2Value
 slv2_plugin_get_library_uri(SLV2Plugin plugin);
 
 
@@ -136,7 +136,7 @@ slv2_plugin_get_library_uri(SLV2Plugin plugin);
  *
  * Time = Query
  */
-char*
+SLV2Value
 slv2_plugin_get_name(SLV2Plugin plugin);
 
 
@@ -163,9 +163,19 @@ slv2_plugin_get_class(SLV2Plugin plugin);
  * Time = Query
  */
 SLV2Values
-slv2_plugin_get_value(SLV2Plugin  p,
-                      SLV2URIType predicate_type,
-                      const char* predicate);
+slv2_plugin_get_value(SLV2Plugin p,
+                      SLV2Value  predicate);
+
+
+/** Get a value associated with the plugin in a plugin's data files.
+ *
+ * This function is identical to slv2_plugin_get_value, but takes a QName
+ * string parameter for a predicate instead of an SLV2Value, which may be
+ * more convenient.
+ */
+SLV2Values
+slv2_plugin_get_value_by_qname(SLV2Plugin  p,
+                               const char* predicate);
 
 
 /** Get a value associated with some subject in a plugin's data files.
@@ -189,9 +199,8 @@ slv2_plugin_get_value(SLV2Plugin  p,
  */
 SLV2Values
 slv2_plugin_get_value_for_subject(SLV2Plugin  p,
-                                  SLV2Value   subject,
-                                  SLV2URIType predicate_type,
-                                  const char* predicate);
+                                  SLV2Value   subject_uri,
+								  SLV2Value   predicate_uri);
 
 
 /** Return whether a feature is supported by a plugin.
@@ -202,8 +211,8 @@ slv2_plugin_get_value_for_subject(SLV2Plugin  p,
  * Time = Query
  */
 bool
-slv2_plugin_has_feature(SLV2Plugin  p,
-                        const char* feature);
+slv2_plugin_has_feature(SLV2Plugin p,
+                        SLV2Value  feature_uri);
 
 
 /** Get the LV2 Features supported (required or optionally) by a plugin.
@@ -261,20 +270,6 @@ uint32_t
 slv2_plugin_get_num_ports(SLV2Plugin p);
 
 
-/** Get the "template" (port signature) of this plugin.
- *
- * The template is intended to be all the basic information a host might
- * want to know about a plugin's inputs and outputs (e.g. to determine if the
- * plugin is appropriate for a given situation).  Using this function is much,
- * much faster than using the individual functions repeatedly to get the same
- * information (since each call results in a single query).
- *
- * Time = Query
- */
-SLV2Template
-slv2_plugin_get_template(SLV2Plugin p);
-
-
 /** Return whether or not the plugin introduces (and reports) latency.
  *
  * The index of the latency port can be found with slv2_plugin_get_latency_port
@@ -298,29 +293,32 @@ slv2_plugin_has_latency(SLV2Plugin p);
  * Time = Query
  */
 uint32_t
-slv2_plugin_get_latency_port(SLV2Plugin p);
+slv2_plugin_get_latency_port_index(SLV2Plugin p);
 
 
-/** Query a plugin for a single variable.
+/** Query a plugin for a single variable (i.e. SELECT a single ?value).
  *
  * \param plugin The plugin to query.
  * \param sparql_str A SPARQL SELECT query.
  * \param variable The index of the variable to return results for
- *     (i.e. with "<code>SELECT ?foo ?bar</code>" foo is 0, and bar is 1).
+ *        (e.g. with "<code>SELECT ?foo ?bar</code>" foo=0, bar=1).
  * \return All matches for \a variable.
  *
  * Time = Query
  */
 SLV2Values
-slv2_plugin_simple_query(SLV2Plugin  plugin,
-                         const char* sparql_str,
-                         unsigned    variable);
+slv2_plugin_query_variable(SLV2Plugin  plugin,
+                           const char* sparql_str,
+                           unsigned    variable);
 
 
 /** Query a plugin and return the number of results found.
  *
+ * Note that this function will work, but is mostly meaningless for queries
+ * that are not SELECT DISTINCT.
+ *
  * \param plugin The plugin to query.
- * \param sparql_str A SPARQL SELECT query.
+ * \param sparql_str A SPARQL SELECT DISTINCT query.
  *
  * Time = Query
  */
@@ -344,13 +342,15 @@ slv2_plugin_get_port_by_index(SLV2Plugin plugin,
 /** Get a port on this plugin by \a symbol.
  *
  * To perform multiple calls on a port, the returned value should
- * be cached and used repeatedly.
+ * be cached and used repeatedly.  Note this function is slower
+ * than slv2_plugin_get_port_by_index, especially on plugins
+ * with a very large number of ports.
  *
  * Time = O(n)
  */
 SLV2Port
-slv2_plugin_get_port_by_symbol(SLV2Plugin  plugin,
-                               const char* symbol);
+slv2_plugin_get_port_by_symbol(SLV2Plugin plugin,
+                               SLV2Value  symbol);
 
 
 /** Get a list of all UIs available for this plugin.
@@ -376,7 +376,7 @@ slv2_plugin_get_uis(SLV2Plugin plugin);
  *
  * Time = Query
  */
-char*
+SLV2Value
 slv2_plugin_get_author_name(SLV2Plugin plugin);
 
 
@@ -387,7 +387,7 @@ slv2_plugin_get_author_name(SLV2Plugin plugin);
  *
  * Time = Query
  */
-char*
+SLV2Value
 slv2_plugin_get_author_email(SLV2Plugin plugin);
 
 
@@ -398,7 +398,7 @@ slv2_plugin_get_author_email(SLV2Plugin plugin);
  *
  * Time = Query
  */
-char*
+SLV2Value
 slv2_plugin_get_author_homepage(SLV2Plugin plugin);
 
 
diff --git a/slv2/pluginclass.h b/slv2/pluginclass.h
index 14449ab..790cc15 100644
--- a/slv2/pluginclass.h
+++ b/slv2/pluginclass.h
@@ -37,7 +37,7 @@ extern "C" {
  *
  * Time = O(1)
  */
-const char* slv2_plugin_class_get_parent_uri(SLV2PluginClass plugin_class);
+SLV2Value slv2_plugin_class_get_parent_uri(SLV2PluginClass plugin_class);
 
 
 /** Get the URI of this plugin class.
@@ -46,7 +46,7 @@ const char* slv2_plugin_class_get_parent_uri(SLV2PluginClass plugin_class);
  *
  * Time = O(1)
  */
-const char* slv2_plugin_class_get_uri(SLV2PluginClass plugin_class);
+SLV2Value slv2_plugin_class_get_uri(SLV2PluginClass plugin_class);
 
 
 /** Get the label of this plugin class, ie "Oscillators".
@@ -55,7 +55,7 @@ const char* slv2_plugin_class_get_uri(SLV2PluginClass plugin_class);
  *
  * Time = O(1)
  */
-const char* slv2_plugin_class_get_label(SLV2PluginClass plugin_class);
+SLV2Value slv2_plugin_class_get_label(SLV2PluginClass plugin_class);
 
 
 /** Get the subclasses of this plugin class.
diff --git a/slv2/pluginclasses.h b/slv2/pluginclasses.h
index f283356..470e782 100644
--- a/slv2/pluginclasses.h
+++ b/slv2/pluginclasses.h
@@ -47,7 +47,7 @@ slv2_plugin_classes_size(SLV2PluginClasses list);
  */
 SLV2PluginClass
 slv2_plugin_classes_get_by_uri(SLV2PluginClasses list,
-                               const char*       uri);
+                               SLV2Value         uri);
 
 
 /** Get a plugin from the list by index.
diff --git a/slv2/plugininstance.h b/slv2/plugininstance.h
index 8f2b7fd..383e404 100644
--- a/slv2/plugininstance.h
+++ b/slv2/plugininstance.h
@@ -30,6 +30,8 @@ extern "C" {
 
 typedef struct _InstanceImpl* SLV2InstanceImpl;
 
+/** \cond IGNORE */
+
 /* Instance of a plugin.
  *
  * The LV2 descriptor and handle of this are exposed to allow inlining of
@@ -44,6 +46,8 @@ typedef struct _Instance {
 	SLV2InstanceImpl      pimpl; ///< Private implementation
 }* SLV2Instance;
 
+/** \endcond */
+
 
 /** \defgroup slv2_library Plugin library access
  *
@@ -147,7 +151,7 @@ slv2_instance_run(SLV2Instance instance,
 	assert(instance->lv2_descriptor);
 	assert(instance->lv2_handle);
 
-	if (instance->lv2_descriptor->run)
+	/*if (instance->lv2_descriptor->run)*/
 		instance->lv2_descriptor->run(instance->lv2_handle, sample_count);
 }
 
diff --git a/slv2/plugins.h b/slv2/plugins.h
index 274696e..3290c4f 100644
--- a/slv2/plugins.h
+++ b/slv2/plugins.h
@@ -58,7 +58,7 @@ slv2_plugins_size(SLV2Plugins list);
  */
 SLV2Plugin
 slv2_plugins_get_by_uri(SLV2Plugins list,
-                        const char* uri);
+                        SLV2Value   uri);
 
 
 /** Get a plugin from the list by index.
diff --git a/slv2/pluginui.h b/slv2/pluginui.h
index b01bf34..8fc1f06 100644
--- a/slv2/pluginui.h
+++ b/slv2/pluginui.h
@@ -34,7 +34,7 @@ extern "C" {
  *
  * Time = O(1)
  */
-const char*
+SLV2Value
 slv2_ui_get_uri(SLV2UI ui);
 
 
@@ -50,14 +50,14 @@ slv2_ui_get_classes(SLV2UI ui);
 
 /** Check whether a plugin UI is a given type.
  *
- * \param ui       The Plugin UI
- * \param type_uri The URI of the LV2 UI type to check this UI against
+ * \param ui        The Plugin UI
+ * \param class_uri The URI of the LV2 UI type to check this UI against
  *
  * Time = O(1)
  */
 bool
-slv2_ui_is_a(SLV2UI ui, const char* type_uri);
-	
+slv2_ui_is_a(SLV2UI ui, SLV2Value class_uri);
+
 
 /** Get the URI for a Plugin UI's bundle.
  *
@@ -65,7 +65,7 @@ slv2_ui_is_a(SLV2UI ui, const char* type_uri);
  *
  * Time = O(1)
  */
-const char*
+SLV2Value
 slv2_ui_get_bundle_uri(SLV2UI ui);
 
 
@@ -75,7 +75,7 @@ slv2_ui_get_bundle_uri(SLV2UI ui);
  *
  * Time = O(1)
  */
-const char*
+SLV2Value
 slv2_ui_get_binary_uri(SLV2UI ui);
 
 
diff --git a/slv2/pluginuis.h b/slv2/pluginuis.h
index 6c91d45..7eacc4a 100644
--- a/slv2/pluginuis.h
+++ b/slv2/pluginuis.h
@@ -57,8 +57,8 @@ slv2_uis_size(SLV2UIs list);
  * \return NULL if plugin with \a url not found in \a list.
  */
 SLV2UI
-slv2_uis_get_by_uri(SLV2UIs     list,
-                    const char* uri);
+slv2_uis_get_by_uri(SLV2UIs   list,
+                    SLV2Value uri);
 
 
 /** Get a plugin from the list by index.
diff --git a/slv2/port.h b/slv2/port.h
index 072417b..5c0549c 100644
--- a/slv2/port.h
+++ b/slv2/port.h
@@ -38,9 +38,9 @@ extern "C" {
  * Time = Query
  */
 SLV2Values
-slv2_port_get_value(SLV2Plugin  plugin,
-                    SLV2Port    port,
-                    const char* property_uri);
+slv2_port_get_value_by_qname(SLV2Plugin  plugin,
+                             SLV2Port    port,
+                             const char* property_uri);
 
 
 /** Return the LV2 port properties of a port.
@@ -57,9 +57,9 @@ slv2_port_get_properties(SLV2Plugin plugin,
  * Time = Query
  */
 bool
-slv2_port_has_property(SLV2Plugin  p,
-                       SLV2Port    port,
-                       const char* property_uri);
+slv2_port_has_property(SLV2Plugin p,
+                       SLV2Port   port,
+                       SLV2Value  property_uri);
 
 
 /** Return whether a port is an event port and supports a certain event type.
@@ -67,21 +67,19 @@ slv2_port_has_property(SLV2Plugin  p,
  * Time = Query
  */
 bool
-slv2_port_supports_event(SLV2Plugin  p,
-                         SLV2Port    port,
-                         const char* event_uri);
+slv2_port_supports_event(SLV2Plugin p,
+                         SLV2Port   port,
+                         SLV2Value  event_uri);
 
 
-/** Get the symbol of a port given the index.
+/** Get the symbol of a port.
  *
  * The 'symbol' is a short string, a valid C identifier.
- * Returned string must be free()'d by caller.
- *
- * \return NULL when index is out of range
+ * Returned value is owned by \a port and must not be freed.
  *
  * Time = Query
  */
-char*
+SLV2Value
 slv2_port_get_symbol(SLV2Plugin plugin,
                      SLV2Port   port);
 
@@ -93,7 +91,7 @@ slv2_port_get_symbol(SLV2Plugin plugin,
  *
  * Time = Query
  */
-char*
+SLV2Value
 slv2_port_get_name(SLV2Plugin plugin,
                    SLV2Port   port);
 
@@ -129,56 +127,22 @@ slv2_port_is_a(SLV2Plugin plugin,
                SLV2Port   port,
                SLV2Value  port_class);
 
-#if 0
-/** Get the direction (input, output) of a port.
- *
- * Time = Query
- */
-SLV2PortDirection
-slv2_port_get_direction(SLV2Plugin plugin,
-                        SLV2Port   port);
-
-/** Get the data type of a port.
- *
- * Time = Query
- */
-SLV2PortDataType
-slv2_port_get_data_type(SLV2Plugin plugin,
-                        SLV2Port   port);
-#endif
-
-
-/** Get the default value of a port.
- *
- * Only valid for ports with a data type of lv2:float.
- *
- * Time = Query
- */
-float
-slv2_port_get_default_value(SLV2Plugin plugin, 
-                            SLV2Port   port);
-
-
-/** Get the minimum value of a port.
- *
- * Only valid for ports with a data type of lv2:float.
- *
- * Time = Query
- */
-float
-slv2_port_get_minimum_value(SLV2Plugin plugin, 
-                            SLV2Port   port);
-
 
-/** Get the maximum value of a port.
+/** Get the default, minimum, and maximum values of a port.
  *
- * Only valid for ports with a data type of lv2:float.
+ * @a def, @a min, and @a max are outputs, pass pointers to uninitialized
+ * (i.e. NOT created with slv2_value_new) SLV2Value variables.  These will
+ * be set to point at new values (which must be freed by the caller using
+ * slv2_value_free), or NULL if the value does not exist.
  *
  * Time = Query
  */
-float
-slv2_port_get_maximum_value(SLV2Plugin plugin, 
-                            SLV2Port   port);
+void
+slv2_port_get_range(SLV2Plugin p, 
+                    SLV2Port   port,
+                    SLV2Value* def,
+                    SLV2Value* min,
+                    SLV2Value* max);
 
 
 /** @} */
diff --git a/slv2/types.h b/slv2/types.h
index 0318a98..ce73fc3 100644
--- a/slv2/types.h
+++ b/slv2/types.h
@@ -36,25 +36,10 @@ extern "C" {
 #define SLV2_PORT_CLASS_EVENT   "http://lv2plug.in/ns/ext/event#EventPort"
 
 
-/** The format of a URI string.
- *
- * Full URI: http://example.org/foo
- * QName: lv2:Plugin
- */
-typedef enum _SLV2URIType {
-	SLV2_URI,
-	SLV2_QNAME
-} SLV2URIType;
-
-
 /** A port on a plugin.  Opaque, but valid to compare to NULL. */
 typedef struct _SLV2Port* SLV2Port;
 
 
-/** The port (I/O) signature of a plugin.  Opaque, but valid to compare to NULL. */
-typedef struct _SLV2PortSignature* SLV2PortSignature;
-
-
 /** A plugin.  Opaque, but valid to compare to NULL. */
 typedef struct _SLV2Plugin* SLV2Plugin;
 
@@ -79,10 +64,6 @@ typedef void* SLV2PluginClasses;
 typedef struct _SLV2Value* SLV2Value;
 
 
-/** A plugin template (collection of port signatures). */
-typedef void* SLV2Template;
-
-
 /** A collection of typed values. */
 typedef void* SLV2Values;
 
diff --git a/slv2/util.h b/slv2/util.h
index 60c5d4d..cba7af3 100644
--- a/slv2/util.h
+++ b/slv2/util.h
@@ -40,27 +40,6 @@ extern "C" {
 const char* slv2_uri_to_path(const char* uri);
 
 
-/** Append \a suffix to \a *dst, reallocating \a dst as necessary.
- *
- * \a dst will (possibly) be freed, it must be dynamically allocated with malloc
- * or NULL.
- */
-void
-slv2_strappend(char** dst, const char* suffix);
-
-
-/** Join all arguments into one string.
- *
- * Arguments are not modified, return value must be free()'d.
- */
-char*
-slv2_strjoin(const char* first, ...);
-
-
-char*
-slv2_vstrjoin(const char** first, va_list args_list);
-
-
 /** @} */
 
 #ifdef __cplusplus
diff --git a/slv2/world.h b/slv2/world.h
index 9d82dd7..e9c328d 100644
--- a/slv2/world.h
+++ b/slv2/world.h
@@ -107,8 +107,8 @@ slv2_world_load_all(SLV2World world);
  * Time = Query
  */
 void
-slv2_world_load_bundle(SLV2World   world,
-                       const char* bundle_uri);
+slv2_world_load_bundle(SLV2World world,
+                       SLV2Value bundle_uri);
 
 
 /** Get the parent of all other plugin classes, lv2:Plugin.