GBC Data Cabinet

About

The GBCDataCabinet plugin allows the Solar2D developer to create and use session (located in memory) and persistent (located on disk) data throughout your application. You no longer have to create global variables to share data between Composer modules, for example.

Features

  • Create multiple session and/or persistent data cabinets easily.
  • Create multiple special table types (stacks and queues).
  • Eliminates the need to global variables to share data between Corona scenes.
  • It’s FREE!

Set Up

GBC Data Cabinet is now part of the Solar2D Free Plugins Directory, so there is nothing you need to do except to add the following reference in your build.settings file.

plugins = {  
    ["plugin.GBCDataCabinet"] = {
        publisherId = "com.gamesbycandlelight",
    },
}

Be sure to require the plugin in each module you need to manage your data:

local GBCDataCabinet = require("plugin.GBCDataCabinet")

Cabinet Reference

GBCDataCabinet.createCabinet(cabinetName)

cabinetName – name of cabinet to create.

Creates a new data cabinet with the name cabinetName that can then be used to store your data.

Returns true if successful, or false if the cabinet could not be created.


GBCDataCabinet.deleteCabinet(cabinetName, deletePersistent)

cabinetName – name of cabinet to delete
deletePersistent – (Optional) Should the persistent cabinet also be deleted?

Deletes the cabinet named cabinetName. Note that all data stored in this cabinet is also deleted.

If deletePersistent is true, the persistent version of the cabinet named cabinetName is also deleted. The end result of this call is that all data stored in the cabinet named cabinetName (both in memory and on disk) will be deleted and there will be no way to recover.

Returns true is successful, or false is there was an error.


GBCDataCabinet.load(cabinetName)

cabinetName – name of persistent cabinet to load into memory.

Loads an existing cabinet into memory so it can be used.

Returns true if successful, or false if there was an error.


GBCDataCabinet.save(cabinetName)

cabinetName – name of cabinet to save to disk.

Saves an existing cabinet that is currently in memory to disk. The memory version will remain. If there is an existing persistent cabinet named cabinetName on the disk, it will be overwritten.

Returns true if successful, or false if there was an error.


GBCDataCabinet.get(cabinetName, name)

cabinetName – name of cabinet.
name – name of the data value to get.

Returns the value, or nil if name does not exist in the cabinet, or if the cabinet is not loaded.


GBCDataCabinet.set(cabinetName, name, value)

cabinetName – name of cabinet to modify.
name – the name of the data value.
value – the actual value

Adds data to the cabinet. Note that any type of data, including tables, can be addded.

Returns true if successful, or false if there was an error.


Stack Reference

A stack is a last-in, first-out table. You use push and pop to add and remove items from the stack.

GBCDataCabinet.createStack(stackName)

stackName – Name of stack to create.

This function will create a new stack.

Returns true if a stack can be create, otherwise returns false.


GBCDataCabinet.push(stackName, stackItem)

stackName – name of stack to use.
stackItem – the data you wish to add to the stack.

Adds stackItem to the top of the stack.

Returns true if item can be added, otherwise false.


GBCDataCabinet.pop(stackName)

stackName – name of the stack to get data from.

Grabs the topmost data item from the stack. After this call, the data item returned is removed from the stack and is no longer available.

Returns the data item or nil if stack is empty or if there is an error.


GBCDataCabinet.stackPeek(stackName)

stackName – name of stack to peek into.

As the name implies, grabs the topmost data item from the stack, but does not remove it.

Returns the data item or nil if stack is empty or if there is an error.


GBCDataCabinet.stackDelete(stackName)

stackName – name of stack to delete.

Deletes the stack and all its data.


GBCDataCabinet.stackCount(stackName)

stackName – name of stack.

Returns the number of items in the stack, or nil if there is an error.


Queue Reference

A queue is a first-in, first-out table. You use enqueue and dequeue to add and remove items from the queue.

GBCDataCabinet.createQueue(queueName)

queueName – Name of queue to create.

This function will create a new queue.

Returns true if a queue can be create, otherwise returns false.


GBCDataCabinet.enqueue(queueName, queueItem)

queueName – name of queue to use.
queueItem – the data you wish to add to the queue.

Adds queueItem to the top of the queue

Returns true if item could be added, otherwise false.


GBCDataCabinet.dequeue(queueName)

queueName – name of the queue to get data from.

Grabs the oldest data item from the queue. After this call, the data item returned is removed from the queue and is no longer available.

Returns the data item or nil if queue is empty or if there is an error.


GBCDataCabinet.queuePeek(queueName)

queueName – name of queue to peek into.

As the name implies, grabs the oldest data item from the queue, but does not remove it.

Returns the data item or nil if queue is empty or if there is an error.


GBCDataCabinet.queueDelete(queueName)

queueName – name of queue to delete.

Deletes the queue and all its data.


GBCDataCabinet.queueCount(queueName)

queueName – name of queue.

Returns the number of items in the queue, or nil if there is an error.


Common Functions

GBCDataCabinet.clean()

Removes all cabinets, stacks, and queues from memory. You should be sure to call this when your application ends.


GBCDataCabinet.setDebugMode(enableDebug)

enableDebug – true or false.  True will enable debug mode, which will print any errors to the console.


Sample Code

A sample Corona SDK project is available for download here: GBCDataCabinet.

Below are some examples on how to use GBC Data Cabinet

Cabinet

local statusText = {}
local success

-------------------------------------------
-- 1. create a cabinet in memory
-------------------------------------------
local success = GBCDataCabinet.createCabinet("My First Cabinet")
    
statusText[1] = display.newText(currentSceneGroup, "First cabinet created: "..
    tostring(success), Screen.CenterX, Screen.Top + 75, native.systemFont, 14)

-- add some data to cabinet
success = GBCDataCabinet.set("My First Cabinet", "Date", os.date())
    
statusText[2] = display.newText(currentSceneGroup, "Data added to first cabinet: "..
    tostring(success), Screen.CenterX, Screen.Top + 100, native.systemFont, 14)

-------------------------------------------
-- 2. create another cabinet and save data to disk
-------------------------------------------

success = GBCDataCabinet.createCabinet("My Second Cabinet")
  
statusText[3] = display.newText(currentSceneGroup, "Second Cabinet Created: "..
    tostring(success), Screen.CenterX, Screen.Top + 125, native.systemFont, 14)

-- add some data to the cabinet
success = GBCDataCabinet.set("My Second Cabinet", "Score", 100)
    
statusText[4] = display.newText(currentSceneGroup, "Data added to second cabinet: "..
    tostring(success), Screen.CenterX, Screen.Top + 150, native.systemFont, 14)

-- add a table to the cabinet
success = GBCDataCabinet.set("My Second Cabinet", "Other Info", {
    ["My First Name"] = "First Name",
    ["My Last Name"] = "Last Name",
})

statusText[5] = display.newText(currentSceneGroup, "Table added to second cabinet: "..
    tostring(success), Screen.CenterX, Screen.Top + 175, native.systemFont, 14)  
    
-- change the value of some data that was previously added
-- Note "My First Name" has a different value
success = GBCDataCabinet.set("My Second Cabinet", "Other Info", {
    ["My First Name"] = "Another First Name",
    ["My Last Name"] = "Last Name",
})

-- save this cabinet to disk for later use
success = GBCDataCabinet.save("My Second Cabinet")
    
statusText[6] = display.newText(currentSceneGroup, "Second cabinet saved to disk: "..
    tostring(success), Screen.CenterX, Screen.Top + 200, native.systemFont, 14)    
    
-- delete the cabinet in memory, but not from the disk
success = GBCDataCabinet.deleteCabinet("My Second Cabinet")
        
-------------------------------------------
-- 3. recall some persistent data
-------------------------------------------

-- Load some saved data
success = GBCDataCabinet.load("My Second Cabinet")
    
statusText[7] = display.newText(currentSceneGroup, "Second cabinet loaded into memory: "..
    tostring(success), Screen.CenterX, Screen.Top + 225, native.systemFont, 14)

-- get a value previously saved
local value = GBCDataCabinet.get("My Second Cabinet", "Score")
  
if value ~= nil then
    statusText[8] = display.newText(currentSceneGroup, "Score: "..value, 
        Screen.CenterX, Screen.Top + 250, native.systemFont, 14)
end

-------------------------------------------
-- 4. Try to recall some data that was NOT 
--    saved to disk.
-------------------------------------------

success = GBCDataCabinet.load("My First Cabinet")
  
statusText[9] = display.newText(currentSceneGroup, "First cabinet loaded into memory: "..
    tostring(success), Screen.CenterX, Screen.Top + 275, native.systemFont, 14)
   
if not success then
    statusText[10] = display.newText(currentSceneGroup, 
        "Error message: This cabinet does not exist", 
        Screen.CenterX, Screen.Top + 300, native.systemFont, 14)
end

Stack

-- create a stack
demoStack = GBCDataCabinet.createStack("DemoStack")
    
-- push 5 values to the stack
for i = 1, 5 do
    local val = math.random(1, 100)
    GBCDataCabinet.push("DemoStack", val)
    pushText.text = pushText.text.." "..tostring(val)
end
    
countText.text = "There are "..GBCDataCabinet.stackCount("DemoStack")..
    " items in this stack"  
        
-- get the 5 values
for i = 1, 5 do
    local val = GBCDataCabinet.pop("DemoStack")
      
    if val ~= nil then
        popText.text = popText.text.." "..tostring(val)
    end
end

Queue

-- create a queue
DemoQueue = GBCDataCabinet.createQueue("DemoQueue")
    
-- put 5 values in the queue
for i = 1, 5 do
    local val = math.random(1, 100)
    GBCDataCabinet.enqueue("DemoQueue", val)
    putText.text = putText.text.." "..tostring(val)
end
    
countText.text = "There are "..GBCDataCabinet.queueCount("DemoQueue")..
    " items in this queue"  
        
-- get the 5 values
for i = 1, 5 do
    local val = GBCDataCabinet.dequeue("DemoQueue")
        
    if val ~= nil then
        getText.text = getText.text.." "..tostring(val)
    end
end