aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext/atom
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2014-01-24 00:55:35 +0000
committerDavid Robillard <d@drobilla.net>2014-01-24 00:55:35 +0000
commit1cb9f77d07c998108d0ba54811ac4604a2b49725 (patch)
tree9816ff3058bcc18af86cb785bdac4857c1000181 /lv2/lv2plug.in/ns/ext/atom
parentc12e45895f93e7bf3b42c43cf45208b28208a252 (diff)
downloadlv2-1cb9f77d07c998108d0ba54811ac4604a2b49725.tar.xz
atom: Deprecate Blank and Resource in favour of just Object.
atom: Add lv2_atom_forge_is_object_type() and lv2_atom_forge_is_blank() to ease backwards compatibility. atom: Add lv2_atom_forge_key() for terser object writing. patch: Add patch:sequenceNumber for associating replies with requests. lv2specgen: Display deprecated warning on classes marked owl:deprecated.
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/atom')
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom-test.c2
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom.h2
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/atom.ttl25
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/forge.h121
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl13
-rw-r--r--lv2/lv2plug.in/ns/ext/atom/manifest.ttl2
6 files changed, 144 insertions, 21 deletions
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom-test.c b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
index 3159156..9792c84 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom-test.c
+++ b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
@@ -90,7 +90,7 @@ main(void)
LV2_Atom_Forge_Frame obj_frame;
LV2_Atom* obj = lv2_atom_forge_deref(
- &forge, lv2_atom_forge_resource(&forge, &obj_frame, 0, eg_Object));
+ &forge, lv2_atom_forge_object(&forge, &obj_frame, 0, eg_Object));
// eg_one = (Int)1
lv2_atom_forge_property_head(&forge, eg_one, 0);
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h
index 8169167..9707a94 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.h
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.h
@@ -189,7 +189,7 @@ typedef struct {
/** The body of an atom:Object. May be cast to LV2_Atom. */
typedef struct {
- uint32_t id; /**< URID (atom:Resource) or blank ID (atom:Blank). */
+ uint32_t id; /**< URID, or 0 for blank. */
uint32_t otype; /**< Type URID (same as rdf:type, for fast dispatch). */
/* Contents (a series of property bodies) follow here. */
} LV2_Atom_Object_Body;
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index c222ebf..301f416 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -388,17 +388,18 @@ atom:Object
<p>An <q>Object</q> is an atom with a set of properties. This corresponds to
an RDF Resource, and can be thought of as a dictionary with URID keys.</p>
-<p>An LV2_Atom_Object has a uint32_t <code>id</code> and uint32_t
-<code>type</code>, followed by a series of atom:Property bodies (without
-headers, i.e. LV2_Atom_Property_Body). The LV2_Atom_Object::type field is
-semantically equivalent to a property with key rdf:type, but is included in the
-structure to allow for fast dispatch.</p>
+<p>An LV2_Atom_Object body has a uint32_t <code>id</code> and
+<code>type</code>, followed by a series of atom:Property bodies
+(LV2_Atom_Property_Body). The LV2_Atom_Object_Body::otype field is equivalent
+to a property with key rdf:type, but is included in the structure to allow for
+fast dispatching.</p>
-<p>This is an abstract Atom type, an Object is always either a atom:Resource
-or a atom:Blank.</p>
+<p>Code SHOULD check for objects using lv2_atom_forge_is_object() or
+lv2_atom_forge_is_blank() if a forge is available, rather than checking the
+atom type directly. This will correctly handle the deprecated atom:Resource
+and atom:Blank types.</p>
-<p>If serialised to RDF, an Object SHOULD be represented directly as a
-resource, e.g.:</p>
+<p>When serialised to RDF, an Object is represented as a resource, e.g.:</p>
<pre class="turtle-code">
eg:someObject
@@ -412,8 +413,11 @@ atom:Resource
a rdfs:Class ;
rdfs:subClassOf atom:Object ;
rdfs:label "Resource" ;
+ owl:deprecated "true"^^xsd:boolean ;
atom:cType "LV2_Atom_Object" ;
lv2:documentation """
+<p>This class is deprecated. Use atom:Object instead.</p>
+
<p>An atom:Object where the <code>id</code> field is a URID, i.e. an Object
with a URI.</p>
""" .
@@ -422,8 +426,11 @@ atom:Blank
a rdfs:Class ;
rdfs:subClassOf atom:Object ;
rdfs:label "Blank" ;
+ owl:deprecated "true"^^xsd:boolean ;
atom:cType "LV2_Atom_Object" ;
lv2:documentation """
+<p>This class is deprecated. Use atom:Object with ID 0 instead.</p>
+
<p>An atom:Object where the LV2_Atom_Object::id is a blank node ID (NOT a URI).
The ID of a Blank is valid only within the context the Blank appears in. For
ports this is the context of the associated run() call, i.e. all ports share
diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h
index 3529592..5fcfa38 100644
--- a/lv2/lv2plug.in/ns/ext/atom/forge.h
+++ b/lv2/lv2plug.in/ns/ext/atom/forge.h
@@ -48,6 +48,12 @@
#include "lv2/lv2plug.in/ns/ext/atom/util.h"
#include "lv2/lv2plug.in/ns/ext/urid/urid.h"
+#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
+# define LV2_ATOM_FORGE_DEPRECATED __attribute__((__deprecated__))
+#else
+# define LV2_ATOM_FORGE_DEPRECATED
+#endif
+
#ifdef __cplusplus
extern "C" {
#else
@@ -89,7 +95,7 @@ typedef struct {
LV2_Atom_Forge_Frame* stack;
- LV2_URID Blank;
+ LV2_URID Blank LV2_ATOM_FORGE_DEPRECATED;
LV2_URID Bool;
LV2_URID Chunk;
LV2_URID Double;
@@ -97,9 +103,10 @@ typedef struct {
LV2_URID Int;
LV2_URID Long;
LV2_URID Literal;
+ LV2_URID Object;
LV2_URID Path;
LV2_URID Property;
- LV2_URID Resource;
+ LV2_URID Resource LV2_ATOM_FORGE_DEPRECATED;
LV2_URID Sequence;
LV2_URID String;
LV2_URID Tuple;
@@ -120,6 +127,10 @@ lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size);
static inline void
lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map)
{
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#endif
lv2_atom_forge_set_buffer(forge, NULL, 0);
forge->Blank = map->map(map->handle, LV2_ATOM__Blank);
forge->Bool = map->map(map->handle, LV2_ATOM__Bool);
@@ -129,6 +140,7 @@ lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map)
forge->Int = map->map(map->handle, LV2_ATOM__Int);
forge->Long = map->map(map->handle, LV2_ATOM__Long);
forge->Literal = map->map(map->handle, LV2_ATOM__Literal);
+ forge->Object = map->map(map->handle, LV2_ATOM__Object);
forge->Path = map->map(map->handle, LV2_ATOM__Path);
forge->Property = map->map(map->handle, LV2_ATOM__Property);
forge->Resource = map->map(map->handle, LV2_ATOM__Resource);
@@ -138,6 +150,9 @@ lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map)
forge->URI = map->map(map->handle, LV2_ATOM__URI);
forge->URID = map->map(map->handle, LV2_ATOM__URID);
forge->Vector = map->map(map->handle, LV2_ATOM__Vector);
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic pop
+#endif
}
static inline LV2_Atom*
@@ -188,6 +203,40 @@ lv2_atom_forge_top_is(LV2_Atom_Forge* forge, uint32_t type)
(lv2_atom_forge_deref(forge, forge->stack->ref)->type == type);
}
+/** Return true iff @p type is an atom:Object. */
+static inline bool
+lv2_atom_forge_is_object_type(const LV2_Atom_Forge* forge, uint32_t type)
+{
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#endif
+ return (type == forge->Object ||
+ type == forge->Blank ||
+ type == forge->Resource);
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic pop
+#endif
+}
+
+/** Return true iff @p type is an atom:Object with a blank ID. */
+static inline bool
+lv2_atom_forge_is_blank(const LV2_Atom_Forge* forge,
+ uint32_t type,
+ const LV2_Atom_Object_Body* body)
+{
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#endif
+ return (type == forge->Blank ||
+ (type == forge->Object &&
+ ((LV2_Atom_Object_Body*)body)->id == 0));
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic pop
+#endif
+}
+
/**
@}
@name Output Configuration
@@ -503,7 +552,7 @@ lv2_atom_forge_tuple(LV2_Atom_Forge* forge, LV2_Atom_Forge_Frame* frame)
}
/**
- Write the header of an atom:Resource.
+ Write the header of an atom:Object.
The passed frame will be initialised to represent this object. To complete
the object, write a sequence of properties, then pop the frame with
@@ -514,12 +563,12 @@ lv2_atom_forge_tuple(LV2_Atom_Forge* forge, LV2_Atom_Forge_Frame* frame)
LV2_URID eg_Cat = map("http://example.org/Cat");
LV2_URID eg_name = map("http://example.org/name");
- // Write object header
+ // Start object with type eg_Cat and blank ID
LV2_Atom_Forge_Frame frame;
- lv2_atom_forge_resource(forge, &frame, 1, eg_Cat);
+ lv2_atom_forge_object(forge, &frame, 0, eg_Cat);
- // Write property: eg:name = "Hobbes"
- lv2_atom_forge_property_head(forge, eg_name, 0);
+ // Append property eg:name = "Hobbes"
+ lv2_atom_forge_key(forge, eg_name);
lv2_atom_forge_string(forge, "Hobbes", strlen("Hobbes"));
// Finish object
@@ -527,39 +576,93 @@ lv2_atom_forge_tuple(LV2_Atom_Forge* forge, LV2_Atom_Forge_Frame* frame)
@endcode
*/
static inline LV2_Atom_Forge_Ref
+lv2_atom_forge_object(LV2_Atom_Forge* forge,
+ LV2_Atom_Forge_Frame* frame,
+ LV2_URID id,
+ LV2_URID otype)
+{
+ const LV2_Atom_Object a = {
+ { sizeof(LV2_Atom_Object) - sizeof(LV2_Atom), forge->Object },
+ { id, otype }
+ };
+ return lv2_atom_forge_push(
+ forge, frame, lv2_atom_forge_write(forge, &a, sizeof(a)));
+}
+
+/**
+ The same as lv2_atom_forge_resource(), but for object:Resource.
+
+ This function is deprecated and should not be used in new code.
+ Use lv2_atom_forge_resource() directly instead.
+*/
+LV2_ATOM_FORGE_DEPRECATED
+static inline LV2_Atom_Forge_Ref
lv2_atom_forge_resource(LV2_Atom_Forge* forge,
LV2_Atom_Forge_Frame* frame,
LV2_URID id,
LV2_URID otype)
{
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#endif
const LV2_Atom_Object a = {
{ sizeof(LV2_Atom_Object) - sizeof(LV2_Atom), forge->Resource },
{ id, otype }
};
return lv2_atom_forge_push(
forge, frame, lv2_atom_forge_write(forge, &a, sizeof(a)));
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic pop
+#endif
}
/**
The same as lv2_atom_forge_resource(), but for object:Blank.
+
+ This function is deprecated and should not be used in new code.
+ Use lv2_atom_forge_resource() directly instead.
*/
+LV2_ATOM_FORGE_DEPRECATED
static inline LV2_Atom_Forge_Ref
lv2_atom_forge_blank(LV2_Atom_Forge* forge,
LV2_Atom_Forge_Frame* frame,
uint32_t id,
LV2_URID otype)
{
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic push
+# pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#endif
const LV2_Atom_Object a = {
{ sizeof(LV2_Atom_Object) - sizeof(LV2_Atom), forge->Blank },
{ id, otype }
};
return lv2_atom_forge_push(
forge, frame, lv2_atom_forge_write(forge, &a, sizeof(a)));
+#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
+# pragma GCC diagnostic pop
+#endif
+}
+
+/**
+ Write a property key in an Object, to be followed by the value.
+
+ See lv2_atom_forge_object() documentation for an example.
+*/
+static inline LV2_Atom_Forge_Ref
+lv2_atom_forge_key(LV2_Atom_Forge* forge,
+ LV2_URID key)
+{
+ const LV2_Atom_Property_Body a = { key, 0, { 0, 0 } };
+ return lv2_atom_forge_write(forge, &a, 2 * sizeof(uint32_t));
}
/**
- Write the header for a property body (likely in an Object).
- See lv2_atom_forge_resource() documentation for an example.
+ Write the header for a property body in an object, with context.
+
+ If you do not need the context, which is almost certainly the case,
+ use the simpler lv2_atom_forge_key() instead.
*/
static inline LV2_Atom_Forge_Ref
lv2_atom_forge_property_head(LV2_Atom_Forge* forge,
diff --git a/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl b/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl
index 2f9d24c..251d998 100644
--- a/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl
@@ -12,6 +12,19 @@
doap:created "2007-00-00" ;
doap:developer <http://drobilla.net/drobilla#me> ;
doap:release [
+ doap:revision "1.9" ;
+ doap:created "2014-01-23" ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Deprecate Blank and Resource in favour of just Object."
+ ] , [
+ rdfs:label "Add lv2_atom_forge_is_object_type() and lv2_atom_forge_is_blank() to ease backwards compatibility."
+ ] , [
+ rdfs:label "Add lv2_atom_forge_key() for terser object writing."
+ ]
+ ]
+ ] , [
doap:revision "1.8" ;
doap:created "2014-01-04" ;
doap:file-release <http://lv2plug.in/spec/lv2-1.8.0.tar.bz2> ;
diff --git a/lv2/lv2plug.in/ns/ext/atom/manifest.ttl b/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
index 552d33e..d92e1c4 100644
--- a/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
@@ -4,5 +4,5 @@
<http://lv2plug.in/ns/ext/atom>
a lv2:Specification ;
lv2:minorVersion 1 ;
- lv2:microVersion 8 ;
+ lv2:microVersion 9 ;
rdfs:seeAlso <atom.ttl> .