Creating a new Saci instance

To create a new Saci instance, use saci.new(), passing at least two arguments: the name of Versium implementation module that Saci should use for storage and a table of parameters for initializing that module. (Note that the content of that table would depend on the implementation.)

E.g., to create an instance of saci that connects to a "filedir" versium (which stores data in a directory):

require("saci")
my_saci = saci.new("versium.filedir", {"/home/joe/sputnik/wiki-data"})

Additionally, a third parameter can be passed: the name of the module to be used as the default/root prototype:

my_saci = saci.new("versium.filedir", {"/home/joe/sputnik/wiki-data"}, "@My_Prototype")

(If that parameter is not specified, Saci defaults to "@Root").

Note that saci.new() does not necessarily create any new storage - it only creates an Lua object that represents a storage system. Some Versium implementations may initialize storage upon first request. Others may require that some prior steps are taken to set it up.

Using an instance of Saci.

node_exists(id)

Returns true if the node exists and false otherwise. For instance:

if my_saci:node_exists("Foo") then
   print("Node Foo exists!")
end

get_node_history(id, prefix, limit) and get\node_info(id, version)

Function get_node_history(id, prefix, limit) returns the history of edits to the node as a list of tables, each representing the information about the revision:

For example:

for _, edit in my_saci:get_node_history("Foo") do
   print (edit.version, edit.timestamp, edit.author, edit.comment)
end

The optional second parameter can be used to filter revisions by timestamp:

this_months_edits = my_saci:get_node_history("Foo", "2008-05")

The optional third parameter allos us to cap the number of items to be returned:

last_ten_edits = my_saci:get_node_history("Foo", "", 10)

Alternatively, the same edit information can be obtained using get\node_info().

edit_info = my_saci:get_node_info("Foo", "0000005")
print(edit_info.author)

If the second parameter is omitted, we get the latest revision:

last_author = my_saci:get_node_info("Foo").author

get_node(id, version)

To get the actual payload of the node, use get_node(). This function returns a table, but note that the fields of that table depend on how Saci is configured. (See Saci Configuration.) The only field that we are certain to have is "fields," which contains field metadata.

node = my_saci:get_node("Foo")
print(node.foo)

Alternatively, we can request a specific version:

node = my_saci:get_node("Foo", "000004")

Note that the node table does not contain any metadata about the revision. In most cases we do not care which version of the node we got - just that it's the latest one. If we want to be sure that we know what version we have, we should first use get_node_info():

edit_info = my_saci:my_saci:get_node("Foo") -- get metadata for the last revision
node = my_saci:get_node("Foo", edit_info.version) -- ask for this version
return node, edit_info.version

If the storage implementation that Saci is using does not have the desired node, then Saci will check if it has a method get_fallback_node(), which can be set by the client, and will use it to retrieve a fallback node if it is defined:

my_saci.get_fallback_node() = function(id, version)
   return my_other_saci:get_node(id, version)
end
node = my_saci.get_node("Foo")

If Saci returns a value that was obtained by using get_fallback_node(), it will then also return a second value "true" to indicate this.

If all fails, get_node() just returns nil.

Using the Node

The value returned by get_node() is an instance of saci.Node.

TO DO

Saving a node

TO DO

Retrieving multiple nodes

function Saci:get_nodes_prefix(prefix)

TO DO

Auxiliary Methods

make_node(data, id)

Creates a node from a data string.

deflate(node)

Turns a node represented as a Lua table into a string representation which could later be inflated again.