Module file

The path is guaranteed to be absolute, by may contain unresolved symlinks. However, a path may not exist, in which case nil will be returned.

Open a read stream.

The consumer is responsible for properly closing the stream:

stream:close_async(GLib.PRIORITY_DEFAULT, nil, function(_, token)
    local _, err = stream:close_finish(token)
    cb(err)
end)

A GDataInputStream adds additional reading utilities:

stream = Gio.DataInputStream.new(stream)

Open a write stream.

Write operations are buffered, so the stream needs to be flushed (or closed) to be sure that changes are written to disk. Especially in replace mode, reading before flushing will yield stale content.

The consumer is responsible for properly closing the stream:

stream:close_async(GLib.PRIORITY_DEFAULT, nil, function(_, token)
    local _, err = stream:close_finish(token)
    cb(err)
end)

If there is not enough data to read, the result may contain less than size bytes of data.

This collects the content into a Lua string, so text files an be used as-is. For binary content, use string.byte to access the raw values or manually wrap the result of file:read_stream in a Gio.DataInputStream and read individual values based on their binary size.

Like all other operations, this always reads from the beginning of the file. Calling this function repeatedly on the same file will always yield the first line.

To iterate over all lines, use file:iterate_lines. To read more than just one line, use file:read_bytes or file:read_string.

This function opens a read stream and starts reading the file line-wise, asynchronously. For every line read, the given iteratee is called with any potential error, the line’s content (without the trailing newline) and a callback function. The callback must always be called to ensure the file handle is cleaned up eventually. The expected signature for the callback is cb(err, stop). If err ~= nil or a value for stop is given, iteration stops immediately and cb will be called.

Changed 0.2.0: Renamed from read_lines.

Due to limitations in GObject Introspection, this can currently only be implemented as “copy and delete” operation.

This has the same semantics as POSIX unlink(), i.e. the link at the given path is removed. If it was the last link to the file, the disk space occupied by that file is freed as well.

Empty directories are deleted by this as well.

Support for this depends on the platform and file system. If unsupported an error of type Gio.IOErrorEnum.NOT_SUPPORTED will be returned.

This can be used to query for any file info attribute supported by GIO. The attribute parameter may either be plain string, such as "standard::size", a wildcard "standard::*" or a list of both "standard::*,owner::user".

GIO also offers constants for these attribute values, which can be found by querying the GIO docs for G_FILE_ATTRIBUTE_* constants: https://docs.gtk.org/gio/index.html?q=G_FILE_ATTRIBUTE_

See docs.gtk.org for additional details.

Keep in mind that checking for existence before reading or writing a file is subject to race conditions. An external process may still alter a file between those two operations.

Also note that, due to limitations in GLib, this method cannot distinguish between a file that is actually absent and a file that the user has no access to.

Note that due to limitations in GLib, this will return 0 for files that the user has no access to.

Common scenarios would be to compare this against Gio.FileType.

Note that due to limitations in GLib, this will return Gio.FileType.UNKNOWN for files that the user has no access to.

Attempting to call this on an existing file will result in an error with type Gio.IOErrorEnum.EXISTS.

Do not use this when you intend to write to the file immediately after creation, as it is subject to race conditions. Write operations, such as file.write and file.write_stream create files when needed.