Saci handles turning nodes of data into Lua objects, but does not concern itself with the actual physical storage. This is done by modules that implement an interface called "Versium". Versium implementations can store and retrieve data represented as byte strings with ids. They also keep track of history for that data.
The Versium API
Each Versium implementation is a Lua module that can be loaded with "require". They can be distributed as LuaRocks.
Capabilities
Since many parts of the API are optional, each implementation must define a table that specifies what it does and does not support. For instance:
capabilities = {
can_save = true, -- an implementation can be read-only
has_history = true, -- some implementations don't keep track of history
is_persistent = true, -- we'll still have the data if the server goes down
supports_extra_fields = true, -- revisions can have fields other than time stamp and author ID
}
Creating a new instance
A new instance of the implementation is created by a function called "new()". This function can take parameters, which are implementation-specific. Note that new() does not create any storage system (such as a database). It creates an Lua object that represents a connection to a storage system.
For instance:
local versium_implementation = require(module_name)
local my_versium_instance = versium_implementation.new(params)
Methods
Once the client creates an instance, they interact with the storage system using this instance.
node_exists(id)
Returns true or false depending on whether there is a node with this ID.
get_node_history(id, prefix)
Returns the history of the node as a list of tables, sorted in reverse chronological order. Each table represents a revision of the node and has the following fields:
- "version" - the id of the revision
- "author" - the author who made the revision
- "timestamp" - the time whe the edit was made (it should look like "2008-04-20T22:12:49")
- "comment" - the comment attached to the revision (or nil),
- "extra" - a table of additional fields (or nil).
Note that all of those values must be stored as strings and the time format is fixed. However, each implementation can use its own way of assigning version IDs.
The history can be filtered by a time prefix. For instace
history = my_versium:get_node_history("Foo", "2008-02")
would return all revisions for February 2008.
get_node_info(id, version)
Returns the information for a specific revision of the node, identified by "version". If "version" is not specified, then the latest revision should be returned.
get_node_info("Foo") should give us the same table as
get_node_history("Foo")[1] (but potentially a lot faster). Also, if
we obtain pick some revision from the history like this:
version = my_versium:get_node_history("Foo")[i].version
then get_node_info("Foo", version) should give us the same table as get_node_history("Foo")[i].
The version parameter is not actually implemented at the moment, but coming soon.
get_node(id, version)
Returns the data stored in the node as a string. Returns nil if the node doesn't exist. Throws an error if anything else goes wrong.
For instance:
data = get_node("Foo")
After that "data" will be set to the content of the node (some byte string).
save_version(id, data, author, comment, extra, timestamp)
Saves a new revision of the node. The first three parameters are required and specify respectively the node that is being updated, the data that it is being updated with, and the user name that will be associated with the change. The comment parameter is optional. The extra parameter is optional and may be set to a table of additional fields. The implementation or may not support optional fields and is free to just ignore this parameter. The timestamp parameter is similarly optional for the client and for the implementation.
get_node_ids(prefix, limit)
Returns a list of existing node ids, up to a certain limit. (If no limit is specified, all ids are returned, up to a limit set by the implementation.) If the optional argument prefix is supplied, then only nodes starting with this prefix should be returned. (The prefix should be treated as a string, not a Lua pattern.) If the prefix is set, then the limit applies to the number of ids that are being returned. The ids can be returned in any order. If "limit" is exhausted but there are more ids left, then a second value of "true" should be returned.
Implementations
FileDir
"FileDir" is the default implementation of Versium, which just stores nodes and their history on disk in directories. See File Storage. FileDir is installed by default together with versium, available as "versium.filedir".
Virtual
"Virtual" implementation is non-persistent and just stores nodes in memory. It is installed by default together with versium and is available as "versium.virtual". The currentl version available in the source repository is out of date but will be updated soon.
Versium-SQL
Versium-SQL stores nodes in a relational database. It requires luasql to work. See SQL Storage.
Versium-SVN
Versium-SVN stores nodes in a subversion repository. It is distributed as a separate rock, "versium-svn". The current version in the source repository is out of date.
Versium-Git
Versium-Git stores nodes in a Git repository. See Git Storage.