Getting Started with dmc-autostore

dmc-autostore Basics

Here is a short overview of how to setup and use dmc-autostore.

Usage Overview

When the AutoStore manager is imported it will make a data structure available to you. All you need to do is read and write to the structure as you wish and AutoStore will take care of the rest, saving changes to the structure.

When your app is re-started, the AutoStore manager will have your data structure ready so you can do more reading and writing.

Yeah, it really is that simple.

First Run Usage

If there is no AutoStore data file (ie, like on the first run of the app) the structure you get will be an empty Lua table ( eg, { } ). Your app can check for this "First Run" situation and respond appropriately. This is a good opportunity to initialize the data structure.

AutoStore won't create a data file until you make changes to the initial empty structure.

Setup

First import the AutoStore library like any other by using the require() statement.

local AutoStore = require 'dmc_autostore'

This will return the AutoStore manager which coordinates any and all save operations on the data structure.

Code Examples

First Run Initialization

Remember that the AutoStore data file won't exist until your application writes to the data structure at least once. You can check for this situation with the is_new_file flag.

If your application needs to initialization the data structure, that should be done first before the rest of your application starts writing data.

The following example is taken from one of the examples found in the repo, though it has been slightly simplified for this documentation.

AutoStore Initialization

local AutoStore = require 'dmc_autostore'


local function initializeAutoStore()

    -- check to see if the data structure has been initialized
    --
    if not AutoStore.is_new_file then return end

    --== new data file, initialize the data structure ==--

    -- get a reference to the root of the data structure
    -- right now 'data' is an empty, "magic" table, eg {}
    local data = AutoStore.data

    --== add "containers" for each section in the app

    -- container to store our UFO objects
    data[ 'ufos' ] = {}

    -- container to our user information
    data[ 'user' ] = {}

    -- save some app specific info, perhaps current version
    -- in case the data structure format changes in the future
    -- or a secret key, etc
    data[ 'app_info' ] = { data_version='1.0', secret={ id="124", key="F5@E$sj1" } }

    ...

    -- Yes, all of those changes will be automatically saved
    -- and there's no ".save()" in sight !

end


--- bootstrap the application
--
local main = function()

    ...

    -- called very early in the app launch
    --
    initializeAutoStore()

    ...

end


main()

Normal Usage

There's nothing complex about reading or writing information to the data structure since it's made up of regular Lua data. It is a flexible structure which can grow and shrink as things are added and removed. And, just like a nested data structure, references to tables inside of the structure can be used as well. This is part of the coolness of this storage mechanism.

This can be seen in the following code examples.

Simple, non-OO Example

This example we will import AutoStore in order to get the root of the structure.

This example is considered a continuation from the example in "First Run Initialization". Look to that example for the data and structure references.
local AutoStore = require 'dmc_autostore'

local function my_function()

    -- reference the structure starting with the root
    AutoStore.data.app_info.data_version = '1.5'


    -- or start with a reference
    local app_info = AutoStore.data.app_info -- reference to the table
    app_info.secret.id = '7654'

end

Object-Oriented Example

Here is an example of taking small "magic branches" from the data structure and passing them to objects.

In this situation you don't have to import AutoStore because the "magic branch" has everything it needs to communicate with the AutoStore manager.

Note: This is not a complete example, just enough to understand the concept.

Note: This example is considered a continuation from the example in "First Run Initialization". Look to that example for the data and structure references.

Main.lua

local AutoStore = require 'dmc_autostore'

local function loadFirstObject()

    local ufos = AutoStore.data.ufos -- reference to the table
    local data = ufos['1']

    -- 'data' now stores a "magic branch"
    -- to { x=160, y=240, temperature='cold' }
    -- now pass 'data' into our object constructor
    -- so the reference can be cached inside of our object
    --
    local object = UFO:new( data )

end

UFO.lua

-- the 'data' we're passing in is a "magic branch" from AutoStore, however
-- to the object it looks and acts just like a regular Lua table
--
local function UFO:new( data )

    -- obviously glossing over the OO aspects so we can
    -- just show the things relavant to AutoStore
    local o = {}


    -- save the reference to our small "branch" of the data structure
    -- we can use '_data' throughout our Class code for our storage needs
    --
    o._data = data


    return o  -- our new object
end


local function UFO:update()

    -- make changes to our data structure
    self._data.x = 50
    self._data.temperature = 'warm'

    -- Yes, all of those changes will be automatically saved
    -- and there's no ".save()" in sight !

end

Full-Examples-Available
The simple example shown in this document is just to give a very brief introduction into the use of dmc-autostore.

There are other examples which can be run on the Corona simulator or a mobile device. They come bundled with DMC Corona Library and are located in the folder examples/ found at the github repo: https://github.com/dmccuskey/dmc-autostore.

Visit page dmc-autostore API to learn how to fully interact with the Lua data structure.

Caveats

There are some things to note about using AutoStore. Just for getting started, the most important one is listed here. Others are listed in the page dmc-autostore Documentation.

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