Scrappy Data

Scrappy Data is a simple data management library for Solar2D that allows for unlimited containers and optional encryption.

A basic rundown is that the system uses “containers” to store data in, there is a single primary one by default and then if you want you can create extra as required.

Each of these containers then get broken down into “boxes”, they each have a primary one and then again you can create extra as required.

The simplest use case it to just use the primary container with its’ primary box, then you won’t need to think about how it’s working under the hood.

However, if you want a bit more separation such as having a container for each pack of rooms in a room escape game, and then inside each of those containers you’d have a box for each individual room escape, you are also able to do that.

As with all my plugins it is free to use however if you find it useful, and are able to, I’d appreciate a coffee.

Image Credit: data store by ProSymbols from the Noun Project.

Getting Started

There are multiple ways to include the library in your project, the simplest is probably via the plugin, as outlined below, however if you wish you can also access the source code.

Plugin

build.settings

settings =
{
    plugins =
    {
        ["plugin.scrappyData"] =
        {
            publisherId = "com.scrappyferret",
            supportedPlatforms =
            {
                iphone = { url="https://plugins.scrappyferret.com/scrappyData/iphone.tgz" },
                android = { url="https://plugins.scrappyferret.com/scrappyData/android.tgz" },
                macos = false,
                win32 = false
            },
        },
    },
}

main.lua

require( "plugin.scrappyData" )

Scrappy.Data:init( params )

Source Code

If you wish you to access the source code directly it is available on GitLab here.

You can then clone or fork it if you wish, or add the library as a submodule to your project with this command:

git submodule add https://gitlab.com/scrappyferret-libs/scrappy-data.git data

However you get the source code into your project, you will then need to include it and initiate it.

main.lua

require( "data.core" )

Scrappy.Data:init( params )

API

Scrappy.Data:init( params )

Initiates the library.

params ( table ) – Parameter table for the initiation.

Scrappy.Data:get( name, box )

Gets a stored value.

name ( string ) – The name of the value to get.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – The value, or nil if not found.

Scrappy.Data:set( name, value, box )

Sets a stored value.

name ( string ) – The name of the value to set.

value ( string, number, boolean, table ) – The value to set.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:setIfNew( name, value, box )

Sets a stored value if it isn’t currently set.

name ( string ) – The name of the value to set.

value ( string, number, boolean, table ) – The value to set.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:is( name, value, box )

Checks if a stored value matches another value.

name ( string ) – The name of the value to check.

value ( string, number, boolean, table ) – The value to compare.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if the values match, false if not.

Scrappy.Data:isHigher( name, value, box )

Checks if a number value is higher than another value.

name ( string ) – The name of the value to check.

value ( number ) – The other value.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if the values is higher, false if not.

Scrappy.Data:isLower( name, value, box )

Checks if a number value is lower than another value.

name ( string ) – The name of the value to check.

value ( number ) – The other value.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if the value is lower, false if not.

Scrappy.Data:isSet( name, box )

Checks if a value has been set.

name ( string ) – The name of the value to check.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if the value is set, false if not.

Scrappy.Data:increment( name, amount, box )

Increments a number value.

name ( string ) – The name of the value to increment.

amount ( number ) – The amount to increment by. Optional, defaults to 1.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:decrement( name, amount, box )

Decrements a number value.

name ( string ) – The name of the value to decrement.

amount ( number ) – The amount to decrement by. Optional, defaults to 1.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:isNumber( name, box )

Checks if a value is a number.

name ( string ) – The name of the value to check.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if it is, false if not.

Scrappy.Data:isString( name, box )

Checks if a value is a string.

name ( string ) – The name of the value to check.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if it is, false if not.

Scrappy.Data:isTable( name, box )

Checks if a value is a table.

name ( string ) – The name of the value to check.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if it is, false if not.

Scrappy.Data:import( name, box )

Imports a data box.

data ( string ) – The exported data to import. This should be a json encoded string that is then b64 encoded.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – True if it is, false if not.

Scrappy.Data:export( name, box )

Exports a data box.

box ( string ) – The name of the box. Optional, defaults to the global box.

returns – The exported data. It will be a json string that is then b64 encoded.

Scrappy.Data:duplicate( name, box )

Duplicates a data box.

name ( string ) – The name of the new box.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:save()

Saves all data. Won’t be needed if autosave is enabled.

Scrappy.Data:load()

Loads all data.

Scrappy.Data:wipe()

Wipes a data box.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:delete()

Deletes a data box.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:enableAutosave()

Enables autosave for this container.

Scrappy.Data:disableAutosave()

Disables autosave for this container.

Scrappy.Data:isAutosaveEnabled()

Checks if autosave is enabled for this container.

returns – True if it is, false otherwise.

Scrappy.Data:enableSaveOnSuspend()

Enables saving on suspend for this container.

Scrappy.Data:disableSaveOnSuspend()

Disables saving on suspend for this container.

Scrappy.Data:isSavingOnSuspendEnabled()

Checks if saving on system suspend is enabled.

returns – True if it is, false otherwise.

Scrappy.Data:enableSaveOnExit()

Enables saving on exit for this container.

Scrappy.Data:disableSaveOnExit()

Disables saving on exit for this container.

Scrappy.Data:isSavingOnExitEnabled()

Checks if saving on system exit is enabled.

returns – True if it is, false otherwise.

Scrappy.Data:enableLog()

Enables logging.

Scrappy.Data:disableLog()

Disables logging.

Scrappy.Data:isLogEnabled()

Checks if logging is enabled.

returns – True if it is, false otherwise.

Scrappy.Data:isInitiated()

Checks if this container is initiated.

returns – True if it is, false otherwise.

Scrappy.Data:isSaving()

Checks if this container is currently saving.

returns – True if it is, false otherwise.

Scrappy.Data:isLoading()

Checks if this container is currently loading.

returns – True if it is, false otherwise.

Scrappy.Data:print( box )

Prints a data box.

box ( string ) – The name of the box. Optional, defaults to the global box.

Scrappy.Data:clearLog()

Clears the current log file.

Scrappy.Data:list()

Gets a list of the names of all current boxes.

returns – The list of box names.

Scrappy.Data:hash( box, key )

Calculates a checksum of a box’s data.

box ( string ) – The name of the box. Optional, defaults to the global box.

key ( string ) – The key to use for the hashing, optional defaults to nil for a digest hash.

returns – The calculated hash.

Scrappy.Data:authenticate( box, key )

Confirms a stored checksum matches the current one.

box ( string ) – The name of the box. Optional, defaults to the global box.

key ( string ) – The key to use for the hashing, optional defaults to nil for a digest hash.

returns – True if it does, false otherwise.

Scrappy.Data:getVersion()

Gets the current version number of the library.

returns – The version number.

Scrappy.Data:b64Encode( data )

Binary encodes some data.

data ( string ) – The data to encode.

returns – The encoded data.

Scrappy.Data:b64Decode( data )

Binary decodes some data.

data ( string ) – The data to decode.

returns – The decoded data.

Scrappy.Data:addEventListener( name, listener )

Adds an event listener.

data ( string ) – The name of the event you wish to listen for. Valid events are ‘save’, ‘load’, ‘import’, ‘export’, and ‘set’.

listener ( function, table ) – Listeners can be either functions or table objects.

Scrappy.Data:removeEventListener( name, listener )

Removes an event listener.

data ( string ) – The name of the event you were listening for.

listener ( function, table ) – Reference to the listener to remove from the list.

Examples

A basic settings.ini file to include in your project’s root directory.

language:en
volume:0.7
debugMode:false

Accessing some settings, changing them, and resetting back to defaults.

-- Get the current language
local language = Scrappy.Settings:get( "language" )

-- Is it English? If so, say hello!
if language == "en" then
    print( "Hello, world!" )
end

-- Now change it to German
Scrappy.Settings:set( "language", "de" )

-- Check that we are in fact in German, and if so say hallo!
if Scrappy.Settings:is( "language", "de" ) then
    print( "Hallo Welt!" )
end

-- Now reset back to default
Scrappy.Settings:reset( "language" )

-- And finally print out the language again to confirm the reset
print( Scrappy.Settings:get( "language" ) )