Sputnik: Saci API

## 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.

Don't put anything here

Page Name (for URL)

Page Title

Breadcrumb Text

Page Content

Advanced Fields

About This Edit