From 1cb9f77d07c998108d0ba54811ac4604a2b49725 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 24 Jan 2014 00:55:35 +0000 Subject: 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. --- lv2/lv2plug.in/ns/ext/atom/atom-test.c | 2 +- lv2/lv2plug.in/ns/ext/atom/atom.h | 2 +- lv2/lv2plug.in/ns/ext/atom/atom.ttl | 25 +++-- lv2/lv2plug.in/ns/ext/atom/forge.h | 121 +++++++++++++++++++++++-- lv2/lv2plug.in/ns/ext/atom/lv2-atom.doap.ttl | 13 +++ lv2/lv2plug.in/ns/ext/atom/manifest.ttl | 2 +- lv2/lv2plug.in/ns/ext/patch/lv2-patch.doap.ttl | 8 ++ lv2/lv2plug.in/ns/ext/patch/manifest.ttl | 2 +- lv2/lv2plug.in/ns/ext/patch/patch.h | 47 +++++----- lv2/lv2plug.in/ns/ext/patch/patch.ttl | 22 ++++- lv2/lv2plug.in/ns/meta/meta.ttl | 8 ++ 11 files changed, 206 insertions(+), 46 deletions(-) (limited to 'lv2') 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

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

-

An LV2_Atom_Object has a uint32_t id and uint32_t -type, 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.

+

An LV2_Atom_Object body has a uint32_t id and +type, 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.

-

This is an abstract Atom type, an Object is always either a atom:Resource -or a atom:Blank.

+

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.

-

If serialised to RDF, an Object SHOULD be represented directly as a -resource, e.g.:

+

When serialised to RDF, an Object is represented as a resource, e.g.:

 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 """
+

This class is deprecated. Use atom:Object instead.

+

An atom:Object where the id field is a URID, i.e. an Object with a URI.

""" . @@ -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 """ +

This class is deprecated. Use atom:Object with ID 0 instead.

+

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 ; doap:release [ + doap:revision "1.9" ; + doap:created "2014-01-23" ; + dcs:blame ; + 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 ; 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 @@ a lv2:Specification ; lv2:minorVersion 1 ; - lv2:microVersion 8 ; + lv2:microVersion 9 ; rdfs:seeAlso . diff --git a/lv2/lv2plug.in/ns/ext/patch/lv2-patch.doap.ttl b/lv2/lv2plug.in/ns/ext/patch/lv2-patch.doap.ttl index a2f3e79..75cde84 100644 --- a/lv2/lv2plug.in/ns/ext/patch/lv2-patch.doap.ttl +++ b/lv2/lv2plug.in/ns/ext/patch/lv2-patch.doap.ttl @@ -12,6 +12,14 @@ doap:name "LV2 Patch" ; doap:shortdesc "Messages for accessing and manipulating properties." ; doap:release [ + doap:revision "2.1" ; + doap:created "2013-01-23" ; + dcs:changeset [ + dcs:item [ + rdfs:label "Add patch:sequenceNumber for associating replies with requests." + ] + ] + ] , [ doap:revision "2.0" ; doap:created "2013-01-10" ; doap:file-release ; diff --git a/lv2/lv2plug.in/ns/ext/patch/manifest.ttl b/lv2/lv2plug.in/ns/ext/patch/manifest.ttl index fcc06be..a2d2176 100644 --- a/lv2/lv2plug.in/ns/ext/patch/manifest.ttl +++ b/lv2/lv2plug.in/ns/ext/patch/manifest.ttl @@ -4,5 +4,5 @@ a lv2:Specification ; lv2:minorVersion 2 ; - lv2:microVersion 0 ; + lv2:microVersion 1 ; rdfs:seeAlso . diff --git a/lv2/lv2plug.in/ns/ext/patch/patch.h b/lv2/lv2plug.in/ns/ext/patch/patch.h index 1a7a893..3224264 100644 --- a/lv2/lv2plug.in/ns/ext/patch/patch.h +++ b/lv2/lv2plug.in/ns/ext/patch/patch.h @@ -28,28 +28,29 @@ #define LV2_PATCH_URI "http://lv2plug.in/ns/ext/patch" #define LV2_PATCH_PREFIX LV2_PATCH_URI "#" -#define LV2_PATCH__Ack LV2_PATCH_PREFIX "Ack" -#define LV2_PATCH__Delete LV2_PATCH_PREFIX "Delete" -#define LV2_PATCH__Error LV2_PATCH_PREFIX "Error" -#define LV2_PATCH__Get LV2_PATCH_PREFIX "Get" -#define LV2_PATCH__Message LV2_PATCH_PREFIX "Message" -#define LV2_PATCH__Move LV2_PATCH_PREFIX "Move" -#define LV2_PATCH__Patch LV2_PATCH_PREFIX "Patch" -#define LV2_PATCH__Post LV2_PATCH_PREFIX "Post" -#define LV2_PATCH__Put LV2_PATCH_PREFIX "Put" -#define LV2_PATCH__Request LV2_PATCH_PREFIX "Request" -#define LV2_PATCH__Response LV2_PATCH_PREFIX "Response" -#define LV2_PATCH__Set LV2_PATCH_PREFIX "Set" -#define LV2_PATCH__add LV2_PATCH_PREFIX "add" -#define LV2_PATCH__body LV2_PATCH_PREFIX "body" -#define LV2_PATCH__destination LV2_PATCH_PREFIX "destination" -#define LV2_PATCH__property LV2_PATCH_PREFIX "property" -#define LV2_PATCH__readable LV2_PATCH_PREFIX "readable" -#define LV2_PATCH__remove LV2_PATCH_PREFIX "remove" -#define LV2_PATCH__request LV2_PATCH_PREFIX "request" -#define LV2_PATCH__subject LV2_PATCH_PREFIX "subject" -#define LV2_PATCH__value LV2_PATCH_PREFIX "value" -#define LV2_PATCH__wildcard LV2_PATCH_PREFIX "wildcard" -#define LV2_PATCH__writable LV2_PATCH_PREFIX "writable" +#define LV2_PATCH__Ack LV2_PATCH_PREFIX "Ack" +#define LV2_PATCH__Delete LV2_PATCH_PREFIX "Delete" +#define LV2_PATCH__Error LV2_PATCH_PREFIX "Error" +#define LV2_PATCH__Get LV2_PATCH_PREFIX "Get" +#define LV2_PATCH__Message LV2_PATCH_PREFIX "Message" +#define LV2_PATCH__Move LV2_PATCH_PREFIX "Move" +#define LV2_PATCH__Patch LV2_PATCH_PREFIX "Patch" +#define LV2_PATCH__Post LV2_PATCH_PREFIX "Post" +#define LV2_PATCH__Put LV2_PATCH_PREFIX "Put" +#define LV2_PATCH__Request LV2_PATCH_PREFIX "Request" +#define LV2_PATCH__Response LV2_PATCH_PREFIX "Response" +#define LV2_PATCH__Set LV2_PATCH_PREFIX "Set" +#define LV2_PATCH__add LV2_PATCH_PREFIX "add" +#define LV2_PATCH__body LV2_PATCH_PREFIX "body" +#define LV2_PATCH__destination LV2_PATCH_PREFIX "destination" +#define LV2_PATCH__property LV2_PATCH_PREFIX "property" +#define LV2_PATCH__readable LV2_PATCH_PREFIX "readable" +#define LV2_PATCH__remove LV2_PATCH_PREFIX "remove" +#define LV2_PATCH__request LV2_PATCH_PREFIX "request" +#define LV2_PATCH__subject LV2_PATCH_PREFIX "subject" +#define LV2_PATCH__sequenceNumber LV2_PATCH_PREFIX "sequenceNumber" +#define LV2_PATCH__value LV2_PATCH_PREFIX "value" +#define LV2_PATCH__wildcard LV2_PATCH_PREFIX "wildcard" +#define LV2_PATCH__writable LV2_PATCH_PREFIX "writable" #endif /* LV2_PATCH_H */ diff --git a/lv2/lv2plug.in/ns/ext/patch/patch.ttl b/lv2/lv2plug.in/ns/ext/patch/patch.ttl index ae1a0e3..c38ca31 100644 --- a/lv2/lv2plug.in/ns/ext/patch/patch.ttl +++ b/lv2/lv2plug.in/ns/ext/patch/patch.ttl @@ -310,16 +310,36 @@ patch:remove a rdf:Property , owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:label "remove" ; rdfs:domain patch:Message . patch:request a rdf:Property , owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:label "request" ; rdfs:domain patch:Response ; rdfs:range patch:Request ; lv2:documentation """ -

The request this is a response to.

+

The request this is a response to. This can be used if referring directly +to the URI or blank node ID of the request is possible. Otherwise, use +patch:sequenceNumber.

+""" . + +patch:sequenceNumber + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:label "sequence number" ; + rdfs:domain patch:Message ; + rdfs:range xsd:int ; + lv2:documentation """ +

The sequence number of a request or response. This property is used to +associate replies with requests when it is not feasible to refer to request +URIs with patch:request. A patch:Response with a given sequence number is the +reply to the previously send patch:Request with the same sequence number.

+ +

The special sequence number 0 means no reply is desired.

""" . patch:subject diff --git a/lv2/lv2plug.in/ns/meta/meta.ttl b/lv2/lv2plug.in/ns/meta/meta.ttl index 5bd316c..6e679cd 100644 --- a/lv2/lv2plug.in/ns/meta/meta.ttl +++ b/lv2/lv2plug.in/ns/meta/meta.ttl @@ -48,6 +48,14 @@ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH R meta:kfoltman , meta:paniq ; doap:release [ + doap:revision "1.8.1" ; + doap:created "2014-01-23" ; + dcs:changeset [ + dcs:item [ + rdfs:label "lv2specgen: Display deprecated warning on classes marked owl:deprecated." + ] + ] + ] , [ doap:revision "1.8.0" ; doap:created "2014-01-04" ; doap:file-release ; -- cgit v1.2.1