The File class provides an abstraction over a path in the file system, and allows for querying the file for associated information as well as modifying it.
See also:
Holds the directory separator character.
The basename of the file name.
File('/foo/base.ext').basename -- => 'base.ext'
A list of children for the file, as File instances.
children = howl.io.File('/bin/').children #children -- => 161 basenames = [f.basename for f in *children] table.concat basenames, ', ', 1, 5 -- => "bunzip2, bzcat, bzcmp, bzdiff, bzegrep"
The contents of the file. Provides an easy way of reading a file’s content in one go. This is also writeable - assigning to this causes the file’s content on disk to be replaced with the assigned value.
The “entity tag” for the file. Entity tags provides a way of determining whether a file is changed on disk or not, and provides a more abstract alternative to checking modified times, etc.
True if the file exists, and false otherwise.
The basename of the file name.
File('/foo/base.ext').extension -- => 'ext' File('/foo/base').extension -- => nil
The type of the file as a string. Possible values are:
True if the file is a backup file, and false otherwise.
True if the file’s path denotes a directory, an false otherwise.
True if the file is hidden, and false otherwise.
True if the file’s path denotes a symbolic link, an false otherwise.
True if the file’s path denotes a mountable location, and false otherwise.
True if the file’s path denotes a regular file, and false otherwise.
True if the file’s path denotes a “special” file, such as a fifo, character device, sockets, etc. False if not.
The UNIX time since the file was modified, as an unsigned 64-bit number.
File('/bin/ls').modified_at -- => 1358406188ULL
The file’s parent, if available, as another File instance.
File('/foo/base.ext').parent.path -- => '/foo' File('/').parent -- => nil
True if the file is readable, and false otherwise.
The size of the file, in bytes. Trying to read the size of a non-existing file is raises an error.
The file’s path, shortened by replacing any references to the home directory
with ~
.
True if the file is writeable, and false otherwise.
The file’s path, as a URI.
File('/foo/base.ext').uri -- => 'file:///foo/base.ext'
Creates a new File instance, pointing to target
. target
can either a string,
in which case it is considered a path, or another File instance.
Replaces any ocurrences ~
with the full path to the home directory.
Returns true if path
is an absolute path, and false otherwise.
Returns a File instance pointing to an existing temporary directory. The directory will not be automatically deleted.
Returns a File instance pointing to an existing temporary file. The file will not be automatically deleted.
Invokes callback
with a File instance pointing to an existing temporary file.
The temporary file will be automatically deleted upon the return of callback
,
if it exists.
Deletes the file. Raises an error if unsuccesful.
For a directory, delete the directory and all files contained within it. Raises an error if unsuccesful.
For a directory, returns all files within the directory or any sub directory of
the directory. options
allows for additional control of the operation, and can
contain the following fields:
filter
: A callback that will recieve each file as its sole argument. To
filter a file, i.e. exclude it from the results, the callback should return
true. The search is performed breadth first, so filtering a directory means that
it won’t be descended into at all.
sort
: Causes the entries of all directories to be sorted before processing.
Returns true if the file is located below directory
, and false otherwise.
Joins the file with any path components passed in as parameters, and returns a new File pointing to the resulting path.
Creates a new directory at the path denoted by the file. Raises an error if unsuccesful.
Creates a new directory at the path denoted by the file, including any non-existing intermediate directories. Raises an error if unsuccesful.
Opens the file in the mode specified by mode
, and returns the Lua file
descriptor. Any error when opening the file causes an error to be raised.
When callback
is specified it is invoked with the file descriptor, and any
return values from the callback are used as the return values for open
. The
file description will in this case always be closed prior to open
returning.
A quick way of issuing a Lua read call for the file. This will open the file for reading, issue the read call, and close the file before returning the resulting values.
Returns the path for the current file relative to its parent.
File('/bin/ls'):relative_to_parent(File('/bin')) -- => 'ls'
Alias for delete.
Alias for delete_all.
Ensures that the file exists, by creating it if not already present.
Alias for delete.
In addition to the above properties and methods, File instances also responds to certain meta methods.
Apart from using the join method, File instances can also be joined by
using the /
operator or the ..
operator:
(File('/bin') / 'ls').path -- => '/bin/ls' (File('/bin') .. 'ls').path -- => '/bin/ls'
Concatenating a File instance to a string returns a string though:
"File is " .. File('/bin') -- => 'File is /bin'
Files respond to the tostring meta method:
tostring(File('/bin/ls')) -- => '/bin/ls'
Files can be lexically compared to other File instances.
File('/bin/ls') == File('/bin/ls') -- => true File('/bin/ls') == File('/bin/cat') -- => false File('/bin/ls') < File('/bin/cat') -- => false File('/bin/ls') > File('/bin/cat') -- => true