About GBC Data Cabinet

The GBCDataCabinet plugin allows the Corona SDK 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

First thing to do, is to activate the plugin from the Corona Marketplace.

In your applications build.settings file, include the reference to the plugin:

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

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

Sample project is available for download here.

Cabinet

Stack

Queue

%d bloggers like this: