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 the Scrupp 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 paths, the first one is chosen.
The standard io 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 constructs the search path and sets the working directory. In order to understand the way how that's done the following definitions are needed:
- base directory
- The directory that contains the executable.
- working directory
- This directory is important if you want to modify files using the input and output facilities of plain Lua.
SHARE_DIR- On Linux, the SHARE_DIR defaults to
${prefix}/share/scrupp. The prefix is defined by the configure script (default: /usr/local). During the installation, all support files ("main.slua" and the directories "examples", "fonts" and "scripts") are copied to this directory.
The following figure shows Scrupp's behaviour on startup, i. e. how it sets the search path and working directory. Click it for a bigger version.
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.