It's very....c
A valid criticism, well taken. I won't debate this choice here, but I understand it's a deal breaker for many. C++ bindings would be trivial, if you're interested in me adding those to the repository.
What advantage does this have over something like PhysFS?
For one thing, PhysFS doesn't implement the XDG Base Directory Specification, which locus does (with sensible values for Windows and OS X). For another, PhysFS doesn't have recursive directory enumeration. In locus, it is simple to, for instance, recurse over all files (excluding folders) in a directory.
locus_walk("my/dir", fn, NULL, LOCUS_RECURSE | LOCUS_FILE);
could you show a few use cases of your library?
Let's say you have a game that is cross-platform with distributions for Windows, Linux, and OS X. Where do you keep your global game data? Traditionally, this is kept in Program Files on Windows, which means it's often a simple matter of looking in the current working directory. Unfortunately, on Linux and OS X, program data is kept separate from program executables, so you might want /usr/share, for instance on Linux.
This is where locus_data_dirs() comes in. It'll be a list of traditional places to check for data files depending on what platform the game was compiled for. There is similarly locus_config_dirs() for configuration, although this is perhaps less important. For user-specific data we have locus_data_home() and locus_config_home().
Now let's say you want to run all the Lua scripts inside each active plugin. For this you'd use locus_walk() to walk through the plugin folders (which are inside some subdirectory of locus_data_home()). Putting it all together, we have:
int load_script(const char *path, void *data) {
return !luaL_dofile((lua_State*) data, path);
}
void load_plugin(const char *plugin_dir, const char *plugin, lua_State *L) {
char *plugin_path = locus_join(plugin_dir, plugin);
locus_walk(plugin_path, load_script, L, LOCUS_RECURSE | LOCUS_FILE);
free(plugin_path);
}
int main() {
lua_State *L = luaL_newstate();
const char **plugins = {"vanilla", "cool-mod1", "awesomer-mod2", NULL};
char *data_home = locus_data_home();
char *plugin_dir = locus_join(data_home, "MyGame/Plugins");
const char **plugin;
for (plugin = plugins; *plugin; ++plugin) {
load_plugin(plugin_dir, *plugin, L);
}
free(data_home);
free(plugin_dir);
lua_close(L);
return 0;
}