dmc-autostore Documentation

Why AutoStore?

dmc-autostore was created to simplify the process of reading and writing data in an application. Some of the design considerations are:

  • Use a single data file

    Though some libraries allow you to create and save multiple data files, for many reasons this really didn't seem like an important feature. Allowing only a single data file meant that the API could be simplified.

  • Use JSON

    JSON is a flexible data structure and can represent any type of structure an app would need. Key/Value storage seems unweildy in comparison.

  • Make the structure Smart

    Find a way to make the structure smart enough to know when modifications are made, then automatically save those changes.

Caveats

Here are some things to note about using AutoStore.

Be sure to retrieve the "magic" data structure first

AutoStore works by putting your data in a "smart" wrapper which watches for changes to the data structure. So technically any data structure that you put in AutoStore is NOT the one that you get OUT, you will instead get the wrapped version.

Normally you won't have to worry about this, but here's an example of a case when you will need to understand.

Incorrect use of AutoStore

local function loadFirstObject()

    local ufos = AutoStore.data.ufos -- reference to the 'ufo' table
    local data1, data2

    -- create the data for my first UFO
    -- here 'data1' refers to a regular, normal Lua data structure
    data1  = { x=160, y=240, temperature='cold' }

    -- let's store our data in our "magic" structure
    ufos['1'] = data1

    -- at this point, any changes to 'data1' still refer to the normal structure
    -- so AutoStore won't know about it
    data1.x = 100

    -- so you need to retrieve the wrapped data structure from AutoStore
    data2 = ufos['1']

    -- now changes to 'data2' will trigger the save mechanism
    data2.x = 100


    -- So the table referenced in 'data1' is not the same as 'data2'

end

Correct Use of AutoStore: get the wrapped data structure before making modifications

local function loadFirstObject()

    local ufos = AutoStore.data.ufos -- reference to the 'ufo' table

    -- create the data for my first UFO and save it
    data = { x=160, y=240, temperature='cold' }
    ufos['1'] = data


    -- get the wrapped version to make changes
    data = ufos['1']

    -- the wrapped version is ALSO the what to give
    -- to an object when doing OO programming
    local o = UFO:new( data )
    data.x = 100

end

Interaction with the Lua data structure is slightly different

Corona currently uses Lua 5.1. Unfortunately this version doesn't have a way to override the functionalty for ipairs() and pairs(). This means that the interaction with table data structures is slightly different than what you might expect.

To help the issue, AutoStore has its own versions of these functions, but they are methods on the AutoStore data structure.

Here is an example using ipairs():

Regular Table Interaction

local list = { "bread", "butter", "jam" }

for i,v in ipairs( list )  -- <<< normal Lua ipairs() iteration
    do print(i,v)
end

AutoStore Table Interaction

local AutoStore = require 'dmc_autostore'
AutoStore.data.list = { "bread", "butter", "jam" }

local list = AutoStore.data.list

for i,v in list:ipairs()  -- <<< here is with AutoStore
    do print(i,v)
end

The same concept applies for pairs():

local AutoStore = require 'dmc_autostore'
AutoStore.data.user = { first="Joe", last="Smith" }

local user = AutoStore.data.user

for k,v in user:pairs()  -- <<< here is with AutoStore
    do print(k,v)
end

From the examples it's apparent that that table interaction with AutoStore takes an object-oriented approach.