Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverage Status

A Lua library for handling paths when loading data files

Example usage:

local datafile = require("datafile")

local my_template ="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 datafile.openers sequence, which contain opener functions loaded from the datafile.openers.* modules (you may modify the datafile.openers sequence in an analog fashion to the package.loaders/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 [ XDG Base Directory Specification](--
  • 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.
  • 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.

API, [mode], [context])

Opens a file, trying the various loaders.

  • file is a relative filename: it is usually prepended by various prefixes as the openers attempt to construct absolute pathnames to find the file.
  • mode is the opening mode, as in file:open. If not given, "r" is the default.
  • context is 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?)
  • Testing

Feedback, pull requests, criticism, contributions, etc. are welcome!


A Lua library for handling paths when loading data files







No packages published