Skip to content

Backends

Jump to bottom
Adrian Pistol edited this page Jun 23, 2016 · 2 revisions

Backends

VFS supports multiple backends. You can implement them on your own, too, if you want.

There are a couple backends by default, however.

Generic backends

Generic backends are always there.

native Backend

This backend uses io.open and other native Lua I/O functions to make a simple. yet complete, backend.

Initialize it with vfs.new(drivename, "native", "/root/path").

Example:

vfs.new("temp", "native", "/tmp") -- Create the drive "temp" with the native backend with its root set to /tmp.

vfs.write("temp:/test.txt", "Hello World!") -- writes /tmp/test.txt on the real file system.

print(vfs.read("temp:/test.txt"))
-- Prints "Hello World!" to the console

carbon Backends

These backends are only there if used from Carbon.

Note: Carbon bundles vfs, no need to have it installed somewhere else.

physfs Backend

This one behaves similar to the native backend, however, no writing is allowed.

"Why would anyone use this?". you might wonder. Well, physfs can mount archives like zip files, too.

Initialize it with vfs.new("compressed", "physfs", "/path/to/compressed_assets.zip"[, already_mounted]) and use it like every other backend, but read-only, so no write, mkdir and delete.

Warning: Do not mount the same archive twice under a different drive name without unmounting. If you mounted it already and want to use it from a different thread, just set already_mounted to true: It will not unmount the drive automatically, nor mount it twice.

shared Backend

This one is special.

Some backends do not like being initialized multiple times, but you still want to...

  • Share cwd set with vfs.chdir across threads
  • Force syncronous usage

To share a backend, all you need to do is vfs.new(myshareddrive, "shared", real_backend[, options...]), substituting real_backend with the backend you want your shared drive to use and on every thread you want to use said shared drive, just do vfs.new(myshareddrive, "shared").

sql Backend

This one is not that useful.

The sql backend creates a VFS which stores files in a database.

Initializing it is a bit hard, since databases are very different compared to others, therefore, you have to do a lot more work to initialize it. Sorry.

vfs.new(drivename, "sql", initialized_db, opts)

initialized_db is a database gets returned by sql.open from Carbon. Check the wiki on how to use it.

Now, opts: This is a bit complicated.

opts is a table of options. Here they are along with their default:

local opts = {
  tablename = nil, -- The table which the file system gets stored in. Must be set.

  type_string = "string", -- The type in the database for strings such as the filename and content,
  type_number = "float64", -- The type in the database for numbers such as the modification time stamp and content length

  equals_operator = "==", -- The operator you check if two are equal in a conditional.
}

The defaults correspond to the settings required for the ql/ql-mem databases.

Example:

local storagedb = sql.open("ql", "storage.ql") -- initialize the storage database

vfs.new("storage", "sql", storagedb, {
  tablename = "files"
})

print("Writing /test.txt:")
assert(vfs.write("storage:/test.txt", "Hello World!"))

print("Reading /test.txt:")
local str = assert(vfs.read("storage:/test.txt"))
print(str)

print("Size /test.txt:")
local size = assert(vfs.size("storage:/test.txt"))
print(size)

print("Listing /:")
for _, n in pairs(assert(vfs.list("storage:/"))) do
	print("> "..n)
end

Above example should print the following:

Writing /test.txt:
Reading /test.txt:
Hello World!
Size /test.txt:
12
Listing /:
> test.txt
Clone this wiki locally