Saving/Loading Tables Using JSON

What is JSON?

JSON stands for JavaScript Object Notation. It’s how developers define objects as arrays in JavaScript (tables in Lua) and these objects are defined using key-value pairs, similar to Lua. The syntax is a little different, but a Lua programmer should be able to comprehend it. Consider this data:

If we create a table for this data in Lua, it might look like this:

local hero = {
    name = "Clark Kent",
    nickname = "Superman",
    address = "Metropolis",
    age = 32
}

Alternatively, the same data could be represented in JSON like this:

var hero = {
    "name":"Clark Kent",
    "nickname":"Superman",
    "address":"Metropolis",
    "age":32
};

Notice the similarities between the JSON and Lua code. In both, we declare key-value pairs where the key is on the left side of the = (Lua) or : (JSON) and the value is on the right side. One slight difference is that JSON uses a string for the key because one purpose of the notation is to facilitate serialization. More specifically, this means turning an in-memory binary object into something that can be transmitted over a network and then converted back into an in-memory binary object. Because of this, text, numbers, and booleans (true/false) are the only individual items that can be specified in JSON data — you can not include things like Corona display objects or anything dependent on userdata/C memory.

For more complex tables, JSON also supports the use of arrays of items inside square brackets ([]) and objects inside of curly braces ({}). Let’s expand our example data to multiple heroes in a Lua array:

local heroes = {
    { name="Clark Kent", nickname="Superman", address="Metropolis", age=32 },
    { name="Bruce Wayne", nickname="Batman", address="Gotham", age=36 },
    { name="Diana Prince", nickname="Wonder Woman", address="New York", age=28 },
}

Or in JSON…

var heroes = [
    { "name":"Clark Kent", "nickname":"Superman", "address":"Metropolis", "age":32 },
    { "name":"Bruce Wayne", "nickname":"Batman", "address":"Gotham", "age":36 },
    { "name":"Diana Prince", "nickname":"Wonder Woman", "address":"New York", "age":28 },
    ]
};

Notice again that it’s quite similar to Lua — this is one reason why JSON is popular among Lua developers. The syntax of JSON is also more compact and lightweight compared to XML where you need both an opening and closing tag in addition to the data. Finally, JSON is also used by many online services which your app may connect to.

Putting JSON to Work

As a Corona developer, it’s not necessary to fully understand JSON to utilize it because we provide two convenient API calls as part of the built-in JSON library. The function json.encode() accepts a Lua table and converts it to string-formatted JSON (this is where the data is serialized). Conversely, when handling a string of formatted JSON data, it can be converted back to a Lua table using json.decode() (this is where the data is de-serialized).

Using the example data above, let’s encode a Lua table to JSON using json.encode() and print() its value to the Corona console:

local json = require( "json" )  -- Include the Corona JSON library

local heroes = {
    { name="Clark Kent", nickname="Superman", address="Metropolis", age=32 },
    { name="Bruce Wayne", nickname="Batman", address="Gotham", age=36 },
    { name="Diana Prince", nickname="Wonder Woman", address="New York", age=28 },
}

local serializedJSON = json.encode( heroes )
print( serializedJSON )

This outputs something like the following:

[{"nickname":"Superman","age":32,"name":"Clark Kent","address":"Metropolis"},{"nickname":"Batman","age":36,"name":"Bruce Wayne","address":"Gotham"},{"nickname":"Wonder Woman","age":28,"name":"Diana Prince","address":"New York"}]

Now, to decode this JSON string back into a Lua table, simply call json.decode() and print() its value to the console. This will output a typical memory reference to the Lua table created, for instance table: 0x6080010613c0, and that table of data can be used just like any other Lua table.

local serializedJSON = json.encode( heroes )
print( serializedJSON )

local newHeroes = json.decode( serializedJSON )
print( newHeroes )

With these two steps, we converted a Lua table into a JSON string and then converted it back to a Lua table, and it wasn’t even necessary to understand JSON. This is how simple JSON can be!

Saving/Loading Tables to JSON

One of the most useful purposes of encoding and decoding data between Lua and JSON is saving and loading data to/from local storage. This lets you accomplish a myriad of tasks including storing game settings, reading level data/configurations, keeping track of high scores between sessions, and nearly any other task where you need to store a reasonably predictable amount of data.

Let’s begin by creating a convenient Lua module to contain the necessary functions. You can study this concept further in the External Modules in Corona tutorial, but basically we’ll begin with a typical setup:

local M = {}

local json = require( "json" )
local defaultLocation = system.DocumentsDirectory

return M

Save this file to your main project directory as loadsave.lua. Essentially, this initial code sets up a Lua table M which will store the functions we create in the following sections, and it returns that table so that those functions will be accessible to any module which require()-s this module. Additionally, since we’re obviously going to use JSON, we include the Corona JSON library and set the default persistent location (system.DocumentsDirectory) to save/load JSON files to/from.

local M = {}

local json = require( "json" )
local defaultLocation = system.DocumentsDirectory


function M.saveTable( t, filename, location )

    local loc = location
    if not location then
        loc = defaultLocation
    end

    -- Path for the file to write
    local path = system.pathForFile( filename, loc )

    -- Open the file handle
    local file, errorString = io.open( path, "w" )

    if not file then
        -- Error occurred; output the cause
        print( "File error: " .. errorString )
        return false
    else
        -- Write encoded JSON data to file
        file:write( json.encode( t ) )
        -- Close the file handle
        io.close( file )
        return true
    end
end

return M

function M.loadTable( filename, location )

    local loc = location
    if not location then
        loc = defaultLocation
    end

    -- Path for the file to read
    local path = system.pathForFile( filename, loc )

    -- Open the file handle
    local file, errorString = io.open( path, "r" )

    if not file then
        -- Error occurred; output the cause
        print( "File error: " .. errorString )
    else
        -- Read data from file
        local contents = file:read( "*a" )
        -- Decode JSON data into Lua table
        local t = json.decode( contents )
        -- Close the file handle
        io.close( file )
        -- Return table
        return t
    end
end

return M

local loadsave = require( "loadsave" )

local gameSettings = {
    musicOn = true,
    soundOn = true,
    difficulty = "easy",
    highScore = 10000,
    highestLevel = 7
}

loadsave.saveTable( gameSettings, "settings.json" )

local loadedSettings = loadsave.loadTable( "settings.json" )

Conclusion

As illustrated in this tutorial, JSON provides a lightweight method to convert Lua tables into serialized text strings which can be exchanged between online services or saved to local files. Then, with just one line, they can be restored to the original Lua format.