Reading and Writing Files

Reading Lines

Another common task when reading data is to process each line of a file and use it for some purpose. For example, if you have a text file representing a list of products along with a price for each, you can loop through the file by lines and output or parse each line (product) individually.

The file:lines() function, in conjunction with a for loop, accomplishes this:

-- Path for the file to read
local path = system.pathForFile( "myfile.txt", system.DocumentsDirectory )

-- 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
    -- Output lines
    for line in file:lines() do
        print( line )
    end
    -- Close the file handle
    io.close( file )
end

file = nil

This process will return the next line on each iteration and continue until no more lines are available. Each line can be used in its entirety or parsed into smaller elements using string patterns. See the String Manipulation guide for details.

Creating Subfolders

Subfolders can be added to system.DocumentsDirectory and system.TemporaryDirectory using the LuaFileSystem (LFS).

Here's how to create an images folder within system.DocumentsDirectory.

local lfs = require( "lfs" )

-- Get raw path to documents directory
local docs_path = system.pathForFile( "", system.DocumentsDirectory )

-- Change current working directory
local success = lfs.chdir( docs_path )  -- Returns true on success

local new_folder_path
local dname = "images"

if ( success ) then
    lfs.mkdir( dname )
    new_folder_path = lfs.currentdir() .. "/" .. dname
end

Accessing Files in Subfolders

You can access files in a subfolder in two ways, depending on what you want to do with the file. If you want to display an image or play a sound from the subfolder, concatenate the subfolder name with the file name and then supply the base directory. For example, if you want to display the cat.png file in the images subfolder, do the following:

local catImage = display.newImage( "images/cat.png", system.DocumentsDirectory, 0, 0 )

Note that you don't use system.pathForFile() in API calls that require a baseDirectory parameter, for example display.newImage(), display.newImageRect(), audio.loadSound(), etc.

If you want to access a file in a subfolder for reading or writing, do the following:

local path = system.pathForFile( "images/readme.txt", system.DocumentsDirectory )
local file, errorString = io.open( path )

If the file doesn't exist, it returns nil — this leads to the next topic.

Testing if Files Exist

The following function can be used to test if a file exists in a folder or subfolder. Just remember to append the subfolder name to the file name before calling this function.

local function doesFileExist( fname, path )

    local results = false

    -- Path for the file
    local filePath = system.pathForFile( fname, path )

    if ( filePath ) then
        local file, errorString = io.open( filePath, "r" )

        if not file then
            -- Error occurred; output the cause
            print( "File error: " .. errorString )
        else
            -- File exists!
            print( "File found: " .. fname )
            results = true
            -- Close the file handle
            file:close()
        end
    end

    return results
end

-- Check for file in "system.DocumentsDirectory"
local results = doesFileExist( "images/cat.png", system.DocumentsDirectory )

-- Check for file in "system.ResourceDirectory"
local results = doesFileExist( "images/cat.png" )

Copying Files to Subfolders

The following function copies a file from one folder to another. This is useful if you need to copy a file bundled in system.ResourceDirectory to system.DocumentsDirectory. Note that you must create the destination subfolder before using this function.

function copyFile( srcName, srcPath, dstName, dstPath, overwrite )

    local results = false

    local fileExists = doesFileExist( srcName, srcPath )
    if ( fileExists == false ) then
        return nil  -- nil = Source file not found
    end

    -- Check to see if destination file already exists
    if not ( overwrite ) then
        if ( fileLib.doesFileExist( dstName, dstPath ) ) then
            return 1  -- 1 = File already exists (don't overwrite)
        end
    end

    -- Copy the source file to the destination file
    local rFilePath = system.pathForFile( srcName, srcPath )
    local wFilePath = system.pathForFile( dstName, dstPath )

    local rfh = io.open( rFilePath, "rb" )
    local wfh, errorString = io.open( wFilePath, "wb" )

    if not ( wfh ) then
        -- Error occurred; output the cause
        print( "File error: " .. errorString )
        return false
    else
        -- Read the file and write to the destination directory
        local data = rfh:read( "*a" )
        if not ( data ) then
            print( "Read error!" )
            return false
        else
            if not ( wfh:write( data ) ) then
                print( "Write error!" )
                return false
            end
        end
    end

    results = 2  -- 2 = File copied successfully!

    -- Close file handles
    rfh:close()
    wfh:close()

    return results
end

-- Copy "readme.txt" from "system.ResourceDirectory" to "system.DocumentsDirectory"
copyFile( "readme.txt", nil, "readme.txt", system.DocumentsDirectory, true )

Android File Restrictions

File access in Corona is based on the underlying operating system which varies by platform. On iOS devices, you can access files in all of the directories described above. On Android, however, there is no literal system.ResourceDirectory because all resource files reside inside a compressed APK file.

Corona allows direct loading of images and audio files using the appropriate APIs, but it has limited access to resource files on Android using the file I/O APIs. Specifically, the following types can not be read from the resources directory: .html, .htm, .3gp, .lua, .m4v, .mp4, .png, .jpg, and .ttf.

Because of this limitation, if you have files of these types bundled in the core directory that you need to copy to another directory, you must change the file name so it can be accessed by the file I/O APIs. For example, if you want to move cat.png from the resource directory to the documents directory, it must be renamed cat.png.txt to be copied.

Here's how to copy cat.png to the documents directory on Android, assuming it's stored as cat.png.txt. This technique works for all platforms, so if you make it work for Android, it will work everywhere.

copyFile( "cat.png.txt", nil, "cat.png", system.DocumentsDirectory, true )
local catImage = display.newImage( "cat.png", system.DocumentsDirectory, 0, 100 )