1.05 - Files

This module provides functions to manually read and write files from the quest data directory and from quest write directory.

Overview

Data files of the quest are located either in a data/ directory or in a data.solarus or data.solarus.zip archive. Files that you write are in the write directory of the quest.

This module encapsulates the transparent search of these files in both locations. You can access them independently of their actual place.

However, note that all built-in file accesses in Solarus (loading maps, loading sprites, reading and writing savegames, etc.) already implement this transparent search. You will only need this module if you implement your custom data files or if you have some custom files to save.

In all functions of sol.file, the notation for the directory separator is always "/" (slash), no matter the underlying platform.

You can read and write files in the quest write directory, and you can only read files in the data directory or archive. If a file to read exists in both locations, the quest write directory is given priority.

Examples of use:

Functions of sol.file

sol.file.open(file_name, [mode])

Same as io.open(), but relative to the quest write directory or to the data directory.

If a valid quest write directory is set (in your quest.dat file or by calling sol.main.set_quest_write_dir()), that directory is tried first. Then, the data directory of your quest is tried if the mode is "r" (read mode).

This function just calls io.open() with the actual path and the mode as parameters, and returns its results.

sol.file.exists(file_name)

Returns whether the specified file exists in the quest write directory of in the data directory.

If a valid quest write directory is set (in your quest.dat file or by calling sol.main.set_quest_write_dir()), that directory is tried first. Then, the data directory of your quest is tried.

sol.file.remove(file_name)

Deletes a file or a directory from the quest write directory.

A valid quest write directory must be set (in your quest.dat file or by calling sol.main.set_quest_write_dir()), otherwise this function generates a Lua error.

sol.file.rename(old_file_name, new_file_name)

Renames a file or a directory in the quest write directory.

A valid quest write directory must be set (in your quest.dat file or by calling sol.main.set_quest_write_dir()), otherwise this function generates a Lua error.

sol.file.mkdir(dir_name)

Creates a directory in the quest write directory.

A valid quest write directory must be set (in your quest.dat file or by calling sol.main.set_quest_write_dir()), otherwise this function generates a Lua error.