File Access
Overview
Scrupp uses a so called virtual filesystem (VFS) which is implemented using the PhysicsFS library. The VFS consists of a list of paths to directories and archives: the search path.
Everytime a file is accessed using one of Scrupp's functions (e.g. scrupp.addImage()) every entry of the search path is checked for the existance of the specified file. If the file exists in multiple directories or archives, the first one is chosen.
The standard I/O facilities of Lua (all functions in the global io table) do not support the virtual filesystem. These functions modify files in the working directory.
Startup
On startup, Scrupp configures the search path and sets the working directory. The entries of the search path are printed to stdout (or stdout.txt on Windows) in the order that is later used when looking for files.
On Linux, if Scrupp was installed to /usr/local, the output would look like this:
search path: . search path: /usr/local/bin/ search path: /usr/local/share/scrupp
- The first entry (.) points to the working directory, i.e., the directory that containts the executed script.
- The second entry points to the directory where the Scrupp binary is located.
- The third entry points to the directory where the scripts and examples that come with Scrupp were installed to.
Generally, you don't have to worry about the search path, because it is initialized to a sane default value. For more details, have a look at the search path configuration.
Functions
- require(modname)
- Loads the specified module. The first thing is to look for the module in the virtual filesystem using the new path.scrupppath. The default list of paths is "?.lua;scripts/?.lua;scripts/?/init.lua;scripts/socket/?.lua". That means the question mark in the semicolon separated list of paths is replaced by the modname. If the virtual filesystem contains a file with the resulting name, it is loaded. Otherwise the next path of the list is processed. The default list of paths can be overridden by the environment variable SCRUPP_PATH. If the module is not found in the virtual filesystem, require falls back to its default behaviour.
- dofile(filename)
- Opens the named Lua file and executes its content. It looks for the file in the virtual filesystem. If the file is not found, it falls back to the default behaviour.
- scrupp.getSearchPath()
- Returns an array with the paths of the current search path.
- scrupp.setSearchPath(array)
- Sets the search path to the paths in the array.
- scrupp.fileExists(filename)
- Returns true if the file exists in the virtual filesystem, false otherwise.
- scrupp.isDirectory(path)
- Returns true if the path points to a directory in the virtual filesystem, false otherwise.
- scrupp.isSymbolicLink(filename)
- Returns true if the file is a symbolic link, false otherwise.
LuaFileSystem
Scrupp includes the Lua library LuaFileSystem (v1.4.2) that provides additional functions related to file system access. By using this library you can retrieve the current working directory, create directories, iterate over all elements in a directory etc.
Note:The functions of this library do not support the virtual filesystem.