Description

Vault is a small persistent data storage library for LÖVE. It takes native Lua types, and stores them in a file, ready for retrieval.

Vault is licensed under the zlib/libpng license. See LICENSE.txt for the license itself.

Usage

This little guide will show you how to use Vault. Before using Vault, you must set your game's identity using love.filesystem.setIndenity.

Specifying Files

There are two ways to specify a filename for Vault to use. You can set the default file by setting Vault.file, which is set to 'data' by default, or you can pass in the filename as the last argument to all the functions in the Vault module. Here's an example:

Vault.file = 'foobar' -- the default file
Vault.save() -- uses 'foobar'
Vault.save('another-one') -- uses 'another-one'

Saving Data

You can save data in a number of ways. One is to start setting things for your file using Vault.set. Vault.set takes two arguments (not included the optional filename), a key and a value. Your keys and your values can be any type, except for 'function', 'thread', and 'userdata'. Let's have a look at using Vault.set:

Vault.set('somekey', 3)
Vault.set('another', { foo = 3, bar = 4 })
Vault.set('something', nil)
Vault.set(3, false)

And to save the data:

Vault.save()

An alternative way of calling Vault.set is by using this syntax:

Vault['somekey'] = 3
...
Vault[3] = false

There are two things to note about this. One is that you can't specify a specific file while doing this (you must use Vault.file), and two is that you can't use a key of anything belong to the Vault module. Here's a list of the string keys:

fileData
file
load
data
get
set
save
__index
__newindex
_getTableString
_getString

Another way to save data is to specify the data all in one go, by using a table, which is passed to Vault.save:

Vault.save({ somekey = 3, another = { foo = 3, bar = 4 }, something = nil, [3] = false })

Loading Data

The easiest way to get all the data is by using Vault.data:

Vault.data() -- { somekey = 3, ... }

Be warned however, this does cache data. If you want to force a reload, you can use Vault.load.

If you just want to get a specific key, you can use Vault.get, like this:

Vault.get('somekey') -- 3
Vault.get('another') -- { foo = 3, bar = 4 }

If the data hasn't been already loaded, Vault.get will do it automatically.

Similar to Vault.set, an alternate way to call Vault.get is by using this syntax:

Vault['somekey'] -- 3

Take note that the same limitations apply as with the Vault[key] = v syntax.

Conclusion

Well that's it. Remember that you can pass a file name at the end of any function to override Vault.file.

Enjoy!

mebens / vault