A Lua library for handling paths when loading data files
local datafile = require("datafile") local my_template = datafile.open("myapp/my_template.txt", "r")
This will try to find and open
myapp/my_template.txt in a series
of locations, based on the "opener" plugins found at the
sequence, which contain opener functions loaded from the
modules (you may modify the
datafile.openers sequence in an analog fashion
package.searchers sequence from Lua).
A few default openers are included:
datafile.openers.luarocks: which tries to determine the LuaRocks context of the running module (only loaded if LuaRocks is detected).
datafile.openers.caller: tries to find the file based on the path of the caller script.
datafile.openers.xdg: follows the [freedesktop.org XDG Base Directory Specification](-- http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html)
datafile.openers.unix: tries traditional Unix paths for data and config files (/etc and dotfiles at the home dir) -- this is an example of a platform-specific opener.
datafile.openers.windows: tries traditional Windows paths for user and config files. For config files, it tries user configuration first, then system wide. For data/user files, it tries the user directory first, then the public directory.
Note: when installing trough LuaRocks, only files for the relevant platform will be installed.
datafile.open(file, [mode], [context])
Opens a file, trying the various loaders.
fileis a relative filename: it is usually prepended by various prefixes as the openers attempt to construct absolute pathnames to find the file.
modeis the opening mode, as in file:open. If not given, "r" is the default.
contextis an optional hint to be used by the openers. Currently, the following contexts are supported:
- nil - the default context
- "config" - this is a configuration file
- "cache" - a runtime cache file
Some openers may operate only on specific contexts, or ignore the context altogether.
If successful, returns two arguments: the open file handle and its pathname. If failed, returns nil and an error message.
datafile.path(file, [mode], [context])
A shorthand function that looks for a file and returns its pathname. The return pathname may be relative.
The input arguments are the same as for
If successful, returns one argument: the pathname, which may be relative. If failed, returns nil and an error message.
- More openers (any Mac-specific paths?)
Feedback, pull requests, criticism, contributions, etc. are welcome!