diff options
Diffstat (limited to 'lv2/patch.lv2')
-rw-r--r-- | lv2/patch.lv2/manifest.ttl | 8 | ||||
-rw-r--r-- | lv2/patch.lv2/patch.meta.ttl | 305 | ||||
-rw-r--r-- | lv2/patch.lv2/patch.ttl | 247 |
3 files changed, 560 insertions, 0 deletions
diff --git a/lv2/patch.lv2/manifest.ttl b/lv2/patch.lv2/manifest.ttl new file mode 100644 index 0000000..fee2375 --- /dev/null +++ b/lv2/patch.lv2/manifest.ttl @@ -0,0 +1,8 @@ +@prefix lv2: <http://lv2plug.in/ns/lv2core#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . + +<http://lv2plug.in/ns/ext/patch> + a lv2:Specification ; + lv2:minorVersion 2 ; + lv2:microVersion 10 ; + rdfs:seeAlso <patch.ttl> . diff --git a/lv2/patch.lv2/patch.meta.ttl b/lv2/patch.lv2/patch.meta.ttl new file mode 100644 index 0000000..edbb5dc --- /dev/null +++ b/lv2/patch.lv2/patch.meta.ttl @@ -0,0 +1,305 @@ +@prefix doap: <http://usefulinc.com/ns/doap#> . +@prefix foaf: <http://xmlns.com/foaf/0.1/> . +@prefix lv2: <http://lv2plug.in/ns/lv2core#> . +@prefix patch: <http://lv2plug.in/ns/ext/patch#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . + +<http://lv2plug.in/ns/ext/patch> + a doap:Project ; + doap:created "2012-02-09" ; + doap:license <http://opensource.org/licenses/isc> ; + doap:developer <http://drobilla.net/drobilla#me> ; + doap:name "LV2 Patch" ; + doap:shortdesc "A protocol for accessing and manipulating properties." ; + lv2:documentation """ + +This is a vocabulary for messages that access and manipulate properties. +It can be used as a dynamic control interface for plugins, +or anything else with a property-based model. + +The key underlying concept here is to control things by manipulating arbitrary properties, +rather than by calling application-specific methods. +This allows implementations to understand what messages do +(at least in a mechanical sense), +which makes things like caching, proxying, or undo relatively straightforward to implement. +Note, however, that this is only conceptual: +there is no requirement to implement a general property store. +Typically, a plugin will understand a fixed set of properties that represent its parameters or other internal state, and ignore everything else. + +This protocol is syntax-agnostic, +and [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity) +in the sense that the messages use the same format as the data they manipulate. +In particular, messages can be serialised as a binary [Object](atom.html#Object) for realtime plugin control, +or as Turtle for saving to a file, +sending over a network, +printing for debugging purposes, +and so on. + +This specification only defines a semantic protocol, +there is no corresponding API. +It can be used with the [Atom](atom.html) extension to control plugins which support message-based parameters as defined by the [Parameters](parameters.html) extension. + +For example, if a plugin defines a `eg:volume` parameter, it can be controlled by the host by sending a patch:Set message to the plugin instance: + + :::turtle + [ + a patch:Set ; + patch:property eg:volume ; + patch:value 11.0 ; + ] + +Similarly, the host could get the current value for this parameter by sending a patch:Get message: + + :::turtle + [ + a patch:Get ; + patch:property eg:volume ; + ] + +The plugin would then respond with the same patch:Set message as above. +In this case, the plugin instance is implicitly the patch:subject, +but a specific subject can also be given for deeper control. + +"""^^lv2:Markdown . + +patch:Copy + lv2:documentation """ + +After this, the destination has the same description as the subject, +and the subject is unchanged. + +It is an error if the subject does not exist, +or if the destination already exists. + +Multiple subjects may be given if the destination is a container, +but the semantics of this case are application-defined. + +"""^^lv2:Markdown . + +patch:Get + lv2:documentation """ + +If a patch:property is given, +then the receiver should respond with a patch:Set message that gives only that property. + +Otherwise, it should respond with a [concise bounded description](http://www.w3.org/Submission/CBD/) in a patch:Put message, +that is, a description that recursively includes any blank node values. + +If a patch:subject is given, then the response should have the same subject. +If no subject is given, then the receiver is implicitly the subject. + +If a patch:request node or a patch:sequenceNumber is given, +then the response should be a patch:Response and have the same property. +If neither is given, then the receiver can respond with a simple patch:Put message. +For example: + + :::turtle + [] + a patch:Get ; + patch:subject eg:something . + +Could result in: + + :::turtle + [] + a patch:Put ; + patch:subject eg:something ; + patch:body [ + eg:name "Something" ; + eg:ratio 1.6180339887 ; + ] . + +"""^^lv2:Markdown . + +patch:Insert + lv2:documentation """ + +If the subject does not exist, it is created. If the subject does already +exist, it is added to. + +This request only adds properties, it never removes them. The user must take +care that multiple values are not set for properties which should only have +one. + +"""^^lv2:Markdown . + +patch:Message + lv2:documentation """ + +This is an abstract base class for all patch messages. Concrete messages are +either a patch:Request or a patch:Response. + +"""^^lv2:Markdown . + +patch:Move + lv2:documentation """ + +After this, the destination has the description that the subject had, and the +subject no longer exists. + +It is an error if the subject does not exist, or if the destination already +exists. + +"""^^lv2:Markdown . + +patch:Patch + lv2:documentation """ + +This method always has at least one subject, and exactly one patch:add and +patch:remove property. The value of patch:add and patch:remove are nodes which +have the properties to add or remove from the subject(s), respectively. The +special value patch:wildcard may be used as the value of a remove property to +remove all properties with the given predicate. For example: + + :::turtle + [] + a patch:Patch ; + patch:subject <something> ; + patch:add [ + eg:name "New name" ; + eg:age 42 ; + ] ; + patch:remove [ + eg:name "Old name" ; + eg:age patch:wildcard ; # Remove all old eg:age properties + ] . + +"""^^lv2:Markdown . + +patch:Put + lv2:documentation """ + +If the subject does not already exist, it is created. If the subject does +already exist, the patch:body is considered an updated version of it, and the +previous version is replaced. + + :::turtle + [] + a patch:Put ; + patch:subject <something> ; + patch:body [ + eg:name "New name" ; + eg:age 42 ; + ] . + +"""^^lv2:Markdown . + +patch:Request + a rdfs:Class ; + rdfs:label "Request" ; + rdfs:subClassOf patch:Message ; + lv2:documentation """ + +A request may have a patch:subject property, which specifies the resource that +the request applies to. The subject may be omitted in contexts where it is +implicit, for example if the recipient is the subject. + +"""^^lv2:Markdown . + +patch:Set + lv2:documentation """ + +This is equivalent to a patch:Patch which removes _all_ pre-existing values for +the property before setting the new value. For example: + + :::turtle + [] + a patch:Set ; + patch:subject <something> ; + patch:property eg:name ; + patch:value "New name" . + +Which is equivalent to: + + :::turtle + [] + a patch:Patch ; + patch:subject <something> ; + patch:add [ + eg:name "New name" ; + ] ; + patch:remove [ + eg:name patch:wildcard ; + ] . + +"""^^lv2:Markdown . + +patch:body + lv2:documentation """ + +The details of this property's value depend on the type of message it is a part +of. + +"""^^lv2:Markdown . + +patch:context + lv2:documentation """ + +For example, a plugin may have a special context for ephemeral properties which +are only relevant during the lifetime of the instance and should not be saved +in state. + +The specific uses for contexts are application specific. However, the context +MUST be a URI, and can be interpreted as the ID of a data model where +properties should be stored. Implementations MAY have special support for +contexts, for example by storing in a quad store or serializing to a format +that supports multiple RDF graphs such as TriG. + +"""^^lv2:Markdown . + +patch:readable + lv2:documentation """ + +See the similar patch:writable property for details. + +"""^^lv2:Markdown . + +patch:request + lv2:documentation """ + +This can be used if referring directly to the URI or blank node ID of the +request is possible. Otherwise, use patch:sequenceNumber. + +"""^^lv2:Markdown . + +patch:sequenceNumber + lv2:documentation """ + +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 that no reply is desired. + +"""^^lv2:Markdown . + +patch:wildcard + lv2:documentation """ + +This makes it possible to describe the removal of all values for a given +property. + +"""^^lv2:Markdown . + +patch:writable + lv2:documentation """ + +This is used to list properties that can be changed, for example to allow user +interfaces to present appropriate controls. For example: + + :::turtle + @prefix eg: <http://example.org/> . + @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . + @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . + @prefix xsd: <http://www.w3.org/2001/XMLSchema#> . + + eg:title + a rdf:Property ; + rdfs:label "title" ; + rdfs:range xsd:string . + + eg:plugin + patch:writable eg:title . + +"""^^lv2:Markdown . diff --git a/lv2/patch.lv2/patch.ttl b/lv2/patch.lv2/patch.ttl new file mode 100644 index 0000000..59ca118 --- /dev/null +++ b/lv2/patch.lv2/patch.ttl @@ -0,0 +1,247 @@ +@prefix foaf: <http://xmlns.com/foaf/0.1/> . +@prefix owl: <http://www.w3.org/2002/07/owl#> . +@prefix patch: <http://lv2plug.in/ns/ext/patch#> . +@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . +@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . + +<http://lv2plug.in/ns/ext/patch> + a owl:Ontology ; + rdfs:seeAlso <patch.meta.ttl> ; + rdfs:label "LV2 Patch" ; + rdfs:comment "A protocol for accessing and manipulating properties." . + +patch:Ack + a rdfs:Class ; + rdfs:subClassOf patch:Response ; + rdfs:label "Ack" ; + rdfs:comment "An acknowledgement that a request was successful." . + +patch:Copy + a rdfs:Class ; + rdfs:subClassOf patch:Request ; + rdfs:label "Copy" ; + rdfs:subClassOf [ + a owl:Restriction ; + owl:minCardinality 1 ; + owl:onProperty patch:subject + ] , [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:destination + ] ; + rdfs:comment "A request to copy the patch:subject to the patch:destination." . + +patch:Delete + a rdfs:Class ; + rdfs:subClassOf patch:Request ; + rdfs:label "Delete" ; + rdfs:comment "Request that the patch:subject or subjects be deleted." . + +patch:Error + a rdfs:Class ; + rdfs:subClassOf patch:Response ; + rdfs:label "Error" ; + rdfs:comment "A response indicating an error processing a request." . + +patch:Get + a rdfs:Class ; + rdfs:subClassOf patch:Request ; + rdfs:label "Get" ; + rdfs:comment "A request for a description of the patch:subject." . + +patch:Insert + a rdfs:Class ; + rdfs:subClassOf patch:Request ; + rdfs:label "Insert" ; + rdfs:subClassOf [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:subject + ] ; + rdfs:comment "A request to insert a patch:body into the patch:subject." . + +patch:Message + a rdfs:Class ; + rdfs:label "Patch Message" ; + rdfs:comment "A patch message." . + +patch:Move + a rdfs:Class ; + rdfs:subClassOf patch:Request ; + rdfs:label "Move" ; + rdfs:subClassOf [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:subject + ] , [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:destination + ] ; + rdfs:comment "A request to move the patch:subject to the patch:destination." . + +patch:Patch + a rdfs:Class ; + rdfs:subClassOf patch:Request , + [ + a owl:Restriction ; + owl:minCardinality 1 ; + owl:onProperty patch:subject + ] , [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:add + ] , [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:remove + ] ; + rdfs:label "Patch" ; + rdfs:comment "A request to add and/or remove properties of the patch:subject." . + +patch:Put + a rdfs:Class ; + rdfs:subClassOf patch:Request ; + rdfs:label "Put" ; + rdfs:subClassOf [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:subject + ] ; + rdfs:comment "A request to put the patch:body as the patch:subject." . + +patch:Request + a rdfs:Class ; + rdfs:label "Request" ; + rdfs:subClassOf patch:Message ; + rdfs:comment "A patch request message." . + +patch:Response + a rdfs:Class ; + rdfs:subClassOf patch:Message ; + rdfs:label "Response" ; + rdfs:comment "A response to a patch:Request." . + +patch:Set + a rdfs:Class ; + rdfs:label "Set" ; + rdfs:subClassOf patch:Request , + [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:property + ] , [ + a owl:Restriction ; + owl:cardinality 1 ; + owl:onProperty patch:value + ] ; + rdfs:comment "A compact request to set a property to a value." . + +patch:accept + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "accept" ; + rdfs:domain patch:Request ; + rdfs:range rdfs:Class ; + rdfs:comment "An accepted type for a response." . + +patch:add + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:domain patch:Patch ; + rdfs:range rdfs:Resource ; + rdfs:label "add" ; + rdfs:comment "The properties to add to the subject." . + +patch:body + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:domain patch:Message ; + rdfs:label "body" ; + rdfs:comment "The body of a message." . + +patch:context + a rdf:Property , + owl:ObjectProperty ; + rdfs:domain patch:Message ; + rdfs:label "context" ; + rdfs:comment "The context of properties in this message." . + +patch:destination + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:domain patch:Message ; + rdfs:label "destination" ; + rdfs:comment "The destination to move the patch:subject to." . + +patch:property + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "property" ; + rdfs:domain patch:Message ; + rdfs:range rdf:Property ; + rdfs:comment "The property for a patch:Set or patch:Get message." . + +patch:readable + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "readable" ; + rdfs:range rdf:Property ; + rdfs:comment "A property that can be read with a patch:Get message." . + +patch:remove + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:label "remove" ; + rdfs:domain patch:Patch ; + rdfs:range rdfs:Resource ; + rdfs:comment "The properties to remove from the subject." . + +patch:request + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:label "request" ; + rdfs:domain patch:Response ; + rdfs:range patch:Request ; + rdfs:comment "The request this is a response to." . + +patch:sequenceNumber + a rdf:Property , + owl:DatatypeProperty , + owl:FunctionalProperty ; + rdfs:label "sequence number" ; + rdfs:domain patch:Message ; + rdfs:range xsd:int ; + rdfs:comment "The sequence number of a request or response." . + +patch:subject + a rdf:Property , + owl:ObjectProperty , + owl:FunctionalProperty ; + rdfs:domain patch:Message ; + rdfs:label "subject" ; + rdfs:comment "The subject this message applies to." . + +patch:value + a rdf:Property ; + rdfs:label "value" ; + rdfs:domain patch:Set ; + rdfs:comment "The value of a property in a patch:Set message." . + +patch:wildcard + a owl:Thing ; + rdfs:label "wildcard" ; + rdfs:comment "A wildcard that matches any resource." . + +patch:writable + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "writable" ; + rdfs:range rdf:Property ; + rdfs:comment "A property that can be set with a patch:Set or patch:Patch message." . |