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.

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> .