Remove state:Path and use new atom:Path instead.

Remove suggestion to use file URIs in plugins, which is much too tedious.  If plugins use standard atom types, hosts should be able to map paths in any way (which they may need to regardless).  Unfortunately it's slightly less pretty in Turtle to have a special path type rather than a (possibly relative) URI.

Factor out common write_set_filename_msg in sampler example.

Establish common URI define convention LV2_EXTNAME__URILOCALNAME and define all URIs in state, message, and atom.

7 files changed, 124 insertions, 67 deletions

diff --git a/lv2/lv2plug.in/ns/ext/atom/atom-test.c b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
index 2cc0da9..2011f68 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom-test.c
+++ b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
@@ -72,16 +72,17 @@ main()
 	LV2_URID eg_four    = urid_map(NULL, "http://example.org/four");
 	LV2_URID eg_true    = urid_map(NULL, "http://example.org/true");
 	LV2_URID eg_false   = urid_map(NULL, "http://example.org/false");
+	LV2_URID eg_path    = urid_map(NULL, "http://example.org/path");
 	LV2_URID eg_uri     = urid_map(NULL, "http://example.org/uri");
 	LV2_URID eg_urid    = urid_map(NULL, "http://example.org/urid");
 	LV2_URID eg_string  = urid_map(NULL, "http://example.org/string");
 	LV2_URID eg_literal = urid_map(NULL, "http://example.org/literal");
 	LV2_URID eg_tuple   = urid_map(NULL, "http://example.org/tuple");
 	LV2_URID eg_vector  = urid_map(NULL, "http://example.org/vector");
-	LV2_URID eg_seq     = urid_map(NULL, "http://example.org/seq");
+	LV2_URID eg_seq     = urid_map(NULL, "http: //example.org/seq");
 
 #define BUF_SIZE  1024
-#define NUM_PROPS 13
+#define NUM_PROPS 14
 
 	uint8_t buf[BUF_SIZE];
 	lv2_atom_forge_set_buffer(&forge, buf, BUF_SIZE);
@@ -132,15 +133,26 @@ main()
 		return test_fail("%ld != 0 (false)\n", f->value);
 	}
 
+	// eg_path = (Path)"/foo/bar"
+	const uint8_t* pstr     = (const uint8_t*)"/foo/bar";
+	const size_t   pstr_len = strlen((const char*)pstr);
+	lv2_atom_forge_property_head(&forge, eg_path, 0);
+	LV2_Atom_String* path  = lv2_atom_forge_uri(&forge, pstr, pstr_len);
+	uint8_t*         pbody = (uint8_t*)LV2_ATOM_BODY(path);
+	if (strcmp((const char*)pbody, (const char*)pstr)) {
+		return test_fail("%s != \"%s\"\n",
+		                 (const char*)pbody, (const char*)pstr);
+	}
+
 	// eg_uri = (URI)"http://example.org/value"
 	const uint8_t* ustr     = (const uint8_t*)"http://example.org/value";
 	const size_t   ustr_len = strlen((const char*)ustr);
 	lv2_atom_forge_property_head(&forge, eg_uri, 0);
-	LV2_Atom_String* uri  = lv2_atom_forge_uri(&forge, ustr, ustr_len);
-	uint8_t*         body = (uint8_t*)LV2_ATOM_BODY(uri);
-	if (strcmp((const char*)body, (const char*)ustr)) {
+	LV2_Atom_String* uri   = lv2_atom_forge_uri(&forge, ustr, ustr_len);
+	uint8_t*         ubody = (uint8_t*)LV2_ATOM_BODY(uri);
+	if (strcmp((const char*)ubody, (const char*)ustr)) {
 		return test_fail("%s != \"%s\"\n",
-		                 (const char*)body, (const char*)ustr);
+		                 (const char*)ubody, (const char*)ustr);
 	}
 
 	// eg_urid = (URID)"http://example.org/value"
@@ -157,7 +169,7 @@ main()
 		&forge, (const uint8_t*)"hello", strlen("hello"));
 	uint8_t* sbody = (uint8_t*)LV2_ATOM_BODY(string);
 	if (strcmp((const char*)sbody, "hello")) {
-		return test_fail("%s != \"hello\"\n", (const char*)body);
+		return test_fail("%s != \"hello\"\n", (const char*)sbody);
 	}
 
 	// eg_literal = (Literal)"hello"@fr
@@ -165,9 +177,9 @@ main()
 	LV2_Atom_Literal* literal = lv2_atom_forge_literal(
 		&forge, (const uint8_t*)"bonjour", strlen("bonjour"),
 		0, urid_map(NULL, "http://lexvo.org/id/term/fr"));
-	body = (uint8_t*)LV2_ATOM_CONTENTS(LV2_Atom_Literal, literal);
-	if (strcmp((const char*)body, "bonjour")) {
-		return test_fail("%s != \"bonjour\"\n", (const char*)body);
+	uint8_t* lbody = (uint8_t*)LV2_ATOM_CONTENTS(LV2_Atom_Literal, literal);
+	if (strcmp((const char*)lbody, "bonjour")) {
+		return test_fail("%s != \"bonjour\"\n", (const char*)lbody);
 	}
 
 	// eg_tuple = "foo",true
@@ -267,6 +279,7 @@ main()
 		const LV2_Atom* four;
 		const LV2_Atom* affirmative;
 		const LV2_Atom* negative;
+		const LV2_Atom* path;
 		const LV2_Atom* uri;
 		const LV2_Atom* urid;
 		const LV2_Atom* string;
@@ -285,6 +298,7 @@ main()
 		{ eg_four,    &matches.four },
 		{ eg_true,    &matches.affirmative },
 		{ eg_false,   &matches.negative },
+		{ eg_path,    &matches.path },
 		{ eg_uri,     &matches.uri },
 		{ eg_urid,    &matches.urid },
 		{ eg_string,  &matches.string },
@@ -312,6 +326,8 @@ main()
 			return test_fail("Bad match true\n");
 		} else if (!lv2_atom_equals((LV2_Atom*)f, matches.negative)) {
 			return test_fail("Bad match false\n");
+		} else if (!lv2_atom_equals((LV2_Atom*)path, matches.path)) {
+			return test_fail("Bad match path\n");
 		} else if (!lv2_atom_equals((LV2_Atom*)uri, matches.uri)) {
 			return test_fail("Bad match URI\n");
 		} else if (!lv2_atom_equals((LV2_Atom*)string, matches.string)) {
@@ -333,6 +349,7 @@ main()
 		                            eg_four,    &matches.four,
 		                            eg_true,    &matches.affirmative,
 		                            eg_false,   &matches.negative,
+		                            eg_path,    &matches.path,
 		                            eg_uri,     &matches.uri,
 		                            eg_urid,    &matches.urid,
 		                            eg_string,  &matches.string,
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h
index 66f0490..f45ba74 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.h
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.h
@@ -27,6 +27,37 @@
 
 #define LV2_ATOM_URI "http://lv2plug.in/ns/ext/atom"
 
+#define LV2_ATOM__Atom          LV2_ATOM_URI "#Atom"
+#define LV2_ATOM__Bang          LV2_ATOM_URI "#Bang"
+#define LV2_ATOM__Number        LV2_ATOM_URI "#Number"
+#define LV2_ATOM__Int32         LV2_ATOM_URI "#Int32"
+#define LV2_ATOM__Int64         LV2_ATOM_URI "#Int64"
+#define LV2_ATOM__Float         LV2_ATOM_URI "#Float"
+#define LV2_ATOM__Double        LV2_ATOM_URI "#Double"
+#define LV2_ATOM__Bool          LV2_ATOM_URI "#Bool"
+#define LV2_ATOM__String        LV2_ATOM_URI "#String"
+#define LV2_ATOM__Literal       LV2_ATOM_URI "#Literal"
+#define LV2_ATOM__Path          LV2_ATOM_URI "#Path"
+#define LV2_ATOM__URI           LV2_ATOM_URI "#URI"
+#define LV2_ATOM__URID          LV2_ATOM_URI "#URID"
+#define LV2_ATOM__Vector        LV2_ATOM_URI "#Vector"
+#define LV2_ATOM__Tuple         LV2_ATOM_URI "#Tuple"
+#define LV2_ATOM__Property      LV2_ATOM_URI "#Property"
+#define LV2_ATOM__Object        LV2_ATOM_URI "#Object"
+#define LV2_ATOM__Resource      LV2_ATOM_URI "#Resource"
+#define LV2_ATOM__Blank         LV2_ATOM_URI "#Blank"
+#define LV2_ATOM__TimeUnit      LV2_ATOM_URI "#TimeUnit"
+#define LV2_ATOM__AudioFrames   LV2_ATOM_URI "#AudioFrames"
+#define LV2_ATOM__Beats         LV2_ATOM_URI "#Beats"
+#define LV2_ATOM__Event         LV2_ATOM_URI "#Event"
+#define LV2_ATOM__Sequence      LV2_ATOM_URI "#Sequence"
+#define LV2_ATOM__AtomPort      LV2_ATOM_URI "#AtomPort"
+#define LV2_ATOM__ValuePort     LV2_ATOM_URI "#ValuePort"
+#define LV2_ATOM__MessagePort   LV2_ATOM_URI "#MessagePort"
+#define LV2_ATOM__bufferType    LV2_ATOM_URI "#bufferType"
+#define LV2_ATOM__supports      LV2_ATOM_URI "#supports"
+#define LV2_ATOM__eventTransfer LV2_ATOM_URI "#eventTransfer"
+
 #define LV2_ATOM_REFERENCE_TYPE 0
 
 #include <stdint.h>
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index 70a1252..677a159 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -218,22 +218,28 @@ void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) {
 </pre>
 """ .
 
+atom:Path
+	a rdfs:Class ;
+	rdfs:subClassOf atom:String ;
+	rdfs:label "File path string" ;
+	lv2:documentation """
+<p>A local file path string.  This is identical in format to atom:String,
+except the string is a path.  Since the ability to distinguish paths from plain
+strings is often necessary, paths MUST NOT be transmitted as atom:String.</p>
+""" .
+
 atom:URI
 	a rdfs:Class ;
 	rdfs:subClassOf atom:String ;
 	rdfs:label "URI string" ;
 	lv2:documentation """
 <p>A URI string.  This is identical in format to atom:String, except the string
-is a URI.  This is occasionally useful when a URI is needed but mapping it is
-inappropriate.  URIs should never be expressed as atom:String, because this
-makes it impossible to distinguish URIs from arbitrary strings, which makes
-functionality like mapping or rewriting URIs impossible.  Similarly, there is
-deliberately no atom type for filesystem paths.  To refer to a filename, use a
-complete file URI, with hostname if at all possible.  This allows hosts to
-properly handle paths in situations like serialisation or network
-transmission.</p>
-
-<p>Pedantically, this is an <q>IRI</q>, since UTF-8 characters are allowed.</p>
+is a URI.  This is useful when a URI is needed but mapping is inappropriate.
+Since the ability to distinguish URIs from plain strings is often necessary,
+URIs MUST NOT be transmitted as atom:String.</p>
+
+<p>This is not strictly a URI, since UTF-8 is allowed.  Escaping and related
+issues issues are the host's responsibility.</p>
 """ .
 
 atom:URID
diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h
index 4db9638..06f24f5 100644
--- a/lv2/lv2plug.in/ns/ext/atom/forge.h
+++ b/lv2/lv2plug.in/ns/ext/atom/forge.h
@@ -85,6 +85,7 @@ typedef struct {
 	LV2_URID Int32;
 	LV2_URID Int64;
 	LV2_URID Literal;
+	LV2_URID Path;
 	LV2_URID Property;
 	LV2_URID Resource;
 	LV2_URID Sequence;
@@ -172,6 +173,7 @@ lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map)
 	forge->Int32    = map->map(map->handle, LV2_ATOM_URI "#Int32");
 	forge->Int64    = map->map(map->handle, LV2_ATOM_URI "#Int64");
 	forge->Literal  = map->map(map->handle, LV2_ATOM_URI "#Literal");
+	forge->Path     = map->map(map->handle, LV2_ATOM_URI "#Path");
 	forge->Property = map->map(map->handle, LV2_ATOM_URI "#Property");
 	forge->Resource = map->map(map->handle, LV2_ATOM_URI "#Resource");
 	forge->Sequence = map->map(map->handle, LV2_ATOM_URI "#Sequence");
@@ -322,13 +324,31 @@ lv2_atom_forge_uri(LV2_Atom_Forge* forge,
 	const LV2_Atom_String a = { { forge->URI, len + 1 } };
 	LV2_Atom_String* out = (LV2_Atom_String*)
 		lv2_atom_forge_write_nopad(forge, &a, sizeof(a));
-	if (!out) {
-		return NULL;
+	if (out) {
+		if (!lv2_atom_forge_string_body(forge, uri, len)) {
+			out->atom.type = 0;
+			out->atom.size = 0;
+			out = NULL;
+		}
 	}
-	if (!lv2_atom_forge_string_body(forge, uri, len)) {
-		out->atom.type = 0;
-		out->atom.size = 0;
-		return NULL;
+	return out;
+}
+
+/** Write an atom:Path.  Note that @p path need not be NULL terminated. */
+static inline LV2_Atom_String*
+lv2_atom_forge_path(LV2_Atom_Forge* forge,
+                    const uint8_t*  path,
+                    size_t          len)
+{
+	const LV2_Atom_String a = { { forge->Path, len + 1 } };
+	LV2_Atom_String* out = (LV2_Atom_String*)
+		lv2_atom_forge_write_nopad(forge, &a, sizeof(a));
+	if (out) {
+		if (!lv2_atom_forge_string_body(forge, path, len)) {
+			out->atom.type = 0;
+			out->atom.size = 0;
+			out = NULL;
+		}
 	}
 	return out;
 }
diff --git a/lv2/lv2plug.in/ns/ext/message/message.h b/lv2/lv2plug.in/ns/ext/message/message.h
index 9c03713..728b836 100644
--- a/lv2/lv2plug.in/ns/ext/message/message.h
+++ b/lv2/lv2plug.in/ns/ext/message/message.h
@@ -27,21 +27,20 @@
 
 #define LV2_MESSAGE_URI "http://lv2plug.in/ns/ext/message"
 
-#define LV2_MESSAGE_Ack      LV2_MESSAGE_URI "#Ack"
-#define LV2_MESSAGE_Delete   LV2_MESSAGE_URI "#Delete"
-#define LV2_MESSAGE_Error    LV2_MESSAGE_URI "#Error"
-#define LV2_MESSAGE_Get      LV2_MESSAGE_URI "#Get"
-#define LV2_MESSAGE_Message  LV2_MESSAGE_URI "#Message"
-#define LV2_MESSAGE_Move     LV2_MESSAGE_URI "#Move"
-#define LV2_MESSAGE_Patch    LV2_MESSAGE_URI "#Patch"
-#define LV2_MESSAGE_Post     LV2_MESSAGE_URI "#Post"
-#define LV2_MESSAGE_Put      LV2_MESSAGE_URI "#Put"
-#define LV2_MESSAGE_Request  LV2_MESSAGE_URI "#Request"
-#define LV2_MESSAGE_Response LV2_MESSAGE_URI "#Response"
-#define LV2_MESSAGE_Set      LV2_MESSAGE_URI "#Set"
-
-#define LV2_MESSAGE_add   LV2_MESSAGE_URI "#add"
-#define LV2_MESSAGE_body  LV2_MESSAGE_URI "#body"
-#define LV2_MESSAGE_cause LV2_MESSAGE_URI "#cause"
+#define LV2_MESSAGE__Ack      LV2_MESSAGE_URI "#Ack"
+#define LV2_MESSAGE__Delete   LV2_MESSAGE_URI "#Delete"
+#define LV2_MESSAGE__Error    LV2_MESSAGE_URI "#Error"
+#define LV2_MESSAGE__Get      LV2_MESSAGE_URI "#Get"
+#define LV2_MESSAGE__Message  LV2_MESSAGE_URI "#Message"
+#define LV2_MESSAGE__Move     LV2_MESSAGE_URI "#Move"
+#define LV2_MESSAGE__Patch    LV2_MESSAGE_URI "#Patch"
+#define LV2_MESSAGE__Post     LV2_MESSAGE_URI "#Post"
+#define LV2_MESSAGE__Put      LV2_MESSAGE_URI "#Put"
+#define LV2_MESSAGE__Request  LV2_MESSAGE_URI "#Request"
+#define LV2_MESSAGE__Response LV2_MESSAGE_URI "#Response"
+#define LV2_MESSAGE__Set      LV2_MESSAGE_URI "#Set"
+#define LV2_MESSAGE__add      LV2_MESSAGE_URI "#add"
+#define LV2_MESSAGE__body     LV2_MESSAGE_URI "#body"
+#define LV2_MESSAGE__cause    LV2_MESSAGE_URI "#cause"
 
 #endif  /* LV2_MESSAGE_H */
diff --git a/lv2/lv2plug.in/ns/ext/state/state.h b/lv2/lv2plug.in/ns/ext/state/state.h
index b450b93..aa272b7 100644
--- a/lv2/lv2plug.in/ns/ext/state/state.h
+++ b/lv2/lv2plug.in/ns/ext/state/state.h
@@ -36,10 +36,11 @@ extern "C" {
 
 #define LV2_STATE_URI "http://lv2plug.in/ns/ext/state"
 
-#define LV2_STATE_INTERFACE_URI LV2_STATE_URI "#Interface"
-#define LV2_STATE_PATH_URI      LV2_STATE_URI "#Path"
-#define LV2_STATE_MAP_PATH_URI  LV2_STATE_URI "#mapPath"
-#define LV2_STATE_MAKE_PATH_URI LV2_STATE_URI "#makePath"
+#define LV2_STATE__Interface LV2_STATE_URI "#Interface"
+#define LV2_STATE__State     LV2_STATE_URI "#State"
+#define LV2_STATE__state     LV2_STATE_URI "#state"
+#define LV2_STATE__mapPath   LV2_STATE_URI "#mapPath"
+#define LV2_STATE__makePath  LV2_STATE_URI "#makePath"
 
 typedef void* LV2_State_Handle;
 typedef void* LV2_State_Map_Path_Handle;
@@ -315,7 +316,7 @@ typedef struct {
 } LV2_State_Map_Path;
 
 /**
-   Feature data for state:makePath (@ref LV2_STATE_MAKE_PATH_URI).
+   Feature data for state:makePath (@ref LV2_STATE__makePath).
 */
 typedef struct {
 
diff --git a/lv2/lv2plug.in/ns/ext/state/state.ttl b/lv2/lv2plug.in/ns/ext/state/state.ttl
index 6c0656a..4b86eb6 100644
--- a/lv2/lv2plug.in/ns/ext/state/state.ttl
+++ b/lv2/lv2plug.in/ns/ext/state/state.ttl
@@ -193,7 +193,9 @@ Map get_plugin_state(LV2_Handle instance)
 <p>Plugins may need to refer to files (e.g. loaded samples) in their state.
 This is done by storing the file's path as a property just like any other
 value.  However, there are some rules which MUST be followed when storing
-paths, see <a href="#mapPath">state:mapPath</a> for details.</p>
+paths, see <a href="#mapPath">state:mapPath</a> for details.  Plugins MUST
+use the type <a href="http://lv2plug.in/ns/ext/atom#Path">atom:Path</a>
+for all paths in their state.</p>
 
 <h3>Creating New Files or Directories</h3>
 
@@ -267,7 +269,6 @@ state:mapPath
 	a lv2:Feature ;
 	rdfs:label "Support for storing paths in files" ;
 	lv2:documentation """
-
 <p>This feature maps absolute paths to/from <q>abstract paths</q> which are
 stored in state.  To support this feature a host must pass an LV2_Feature with
 URI LV2_STATE_MAP_PATH_URI and data pointed to an LV2_State_Map_Path to the
@@ -305,7 +306,6 @@ state:makePath
 	a lv2:Feature ;
 	rdfs:label "Support for creating new files and directories" ;
 	lv2:documentation """
-
 <p>This feature allows plugins to create new files and/or directories.  To
 support this feature the host passes an LV2_Feature with URI
 LV2_STATE_MAKE_PATH_URI and data pointed to an LV2_State_Make_Path to the
@@ -340,20 +340,3 @@ char* save_myfile(LV2_State_Make_Path* make_path)
 }
 </pre>
 """ .
-
-state:Path
-	a rdfs:Class ;
-	rdfs:label "Path" ;
-	lv2:documentation """
-<p>A path to a file or directory.</p>
-
-<p>The format of a state:Path is a C string, possibly escaped or otherwise
-restricted in a system-specific manner.  This URI (LV2_STATE_PATH_URI), mapped
-to an integer, MUST be used as the <code>type</code> parameter for any files
-passed to the LV2_State_Store_Function; and will likewise be returned by the
-corresponding call to the LV2_State_Retrieve_Function.</p>
-
-<p>When storing and retrieving a path, the plugin MUST NOT assume the same path
-will be restored.  However, the restored path will refer to a file with
-equivalent contents to the original.</p>
-""" .