From 725d4a404b838da6b67d9da66228a1125bddef57 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 20 Nov 2011 23:08:57 +0000 Subject: Lay out repository structure to match include and URI structure. Treat lv2core like all the other specifications in gendoc.py. --- ns/ext/files/files.ttl | 115 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 ns/ext/files/files.ttl (limited to 'ns/ext/files/files.ttl') diff --git a/ns/ext/files/files.ttl b/ns/ext/files/files.ttl new file mode 100644 index 0000000..d3ff8a5 --- /dev/null +++ b/ns/ext/files/files.ttl @@ -0,0 +1,115 @@ +# LV2 Files Extension +# Copyright 2010-2011 David Robillard +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +@prefix atom: . +@prefix doap: . +@prefix files: . +@prefix foaf: . +@prefix lv2: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . + + + a lv2:Specification ; + doap:name "LV2 Files" ; + doap:shortdesc "A standard for referring to files in plugin state." ; + doap:license ; + doap:release [ + doap:revision "0.2" ; + doap:created "2011-04-05" + ] ; + doap:maintainer [ + a foaf:Person ; + foaf:name "David Robillard" ; + foaf:homepage ; + rdfs:seeAlso + ] ; + lv2:documentation """ +

This extension provides a mechanism for plugins to portably refer to files +in persistent plugin state (using the LV2 Persist extension), and create +instance-local files in host-defined locations (e.g. for recording).

+ +

The motivating idea behind this extension is that all details of file +management MUST be handled by the host since different hosts may have very +different requirements. Plugins MUST NOT make any assumption about file system +locations beyond what is explicitly guaranteed by this extension.

+ +

This extension defines two features: files:newFileSupport allows plugins to +create new files within an instance-specific namespace at any time (except in +realtime contexts); while files:pathSupport allows plugins to refer to file +paths in plugin state in a way transparent to the host.

+ +

To create a new file, the plugin MUST request a path from the host using +LV2_Files_New_File_Support::new_file_path(). Thus, the host may choose an +appropriate location for the file (e.g. a writable path on the appropriate disk +volume or a path within a session directory) using information not available to +the plugin.

+ +

To store a path in persistent state, the plugin MUST map it to an +abstract path using LV2_Files_Path_Support::abstract_path(). To use a +path loaded from persistent state, the plugin MUST map the (abstract) path to +an absolute path using LV2_Files_Path_Support::absolute_path(). Thus, the host +can manage all paths used in a session and support exporting sessions to a +portable self-contained format for archival or distribution.

""" . + +files:pathSupport a lv2:Feature ; + rdfs:label "Support for storing file paths in plugin state" ; + lv2:documentation """ +

This feature allows plugins to refer to pre-existing or newly created files +in persistent plugin state in a portable way. To support this feature a host +MUST pass a LV2_Files_Path_Support structure to the plugin's +LV2_Descriptor::instantiate() method as an LV2_Feature with LV2_Feature::URI = +LV2_FILES_PATH_SUPPORT_URI and LV2_Feature::data pointed to an instance of +LV2_Files_Path_Support.

+ +

Plugins MUST use the functions provided by this feature to handle +all paths saved to, or restored from, persistent plugin state; +otherwise broken and/or non-portable state will silently be created resulting +in a broken user experience.

+""" . + +files:newFileSupport a lv2:Feature ; + rdfs:label "Support for creating new files" ; + lv2:documentation """ +

This feature allows plugins to create new files local to that plugin +instance. To support this feature a host MUST pass a +LV2_Files_New_File_Support structure to the plugin's +LV2_Descriptor::instantiate() method as an LV2_Feature with LV2_Feature::URI = +LV2_FILES_NEW_FILE_SUPPORT_URI and LV2_Feature::data pointed to an instance of +LV2_Files_New_File_Support.

+""" . + +files:AbstractPath a rdfs:Class ; + rdfs:label "File Path" ; + lv2:documentation """ +

An abstract path to a file in persistent plugin state.

+ +

The format of a files:AbstractPath is a C string escaped or otherwise +restricted in a system-specific manner. This URI, +http://lv2plug.in/ns/ext/files#AbstractPath, mapped to an integer, +should be used as the type parameter to a +LV2_Persist_Store_Function; and will likewise be returned by the corresponding +call to a LV2_Persist_Retrieve_Function.

+ +

Abstract paths reside in a namespace specific to a plugin instance. +Typical hosts are expected to implement this by giving each plugin instance its +own state directory.

+ +

When storing and retrieving an abstract 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.

+""" . -- cgit v1.2.1