howl.io.File

Overview

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:

Class Properties

separator

Holds the directory separator character.

Properties

basename

The basename of the file.

  File('/foo/base.ext').basename -- => 'base.ext'

children

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"

contents

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.

display_name

The basename of the file, but with a trailing separator for directories.

etag

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.

exists

True if the file exists, and false otherwise.

extension

The basename of the file name.

  File('/foo/base.ext').extension -- => 'ext'
  File('/foo/base').extension -- => nil

file_type

The type of the file as a string. Possible values are:

is_backup

True if the file is a backup file, and false otherwise.

is_directory

True if the file’s path denotes a directory, an false otherwise.

is_hidden

True if the file is hidden, and false otherwise.

True if the file’s path denotes a symbolic link, an false otherwise.

is_mountable

True if the file’s path denotes a mountable location, and false otherwise.

is_regular

True if the file’s path denotes a regular file, and false otherwise.

is_special

True if the file’s path denotes a “special” file, such as a fifo, character device, sockets, etc. False if not.

modified_at

The UNIX time since the file was modified, as an unsigned 64-bit number.

  File('/bin/ls').modified_at -- => 1358406188ULL

parent

The file’s parent, if available, as another File instance.

  File('/foo/base.ext').parent.path -- => '/foo'
  File('/').parent -- => nil

readable

True if the file is readable, and false otherwise.

size

The size of the file, in bytes. Trying to read the size of a non-existing file is raises an error.

short_path

The file’s path, shortened by replacing any references to the home directory with ~.

writeable

True if the file is writeable, and false otherwise.

uri

The file’s path, as a URI.

  File('/foo/base.ext').uri -- => 'file:///foo/base.ext'

Functions

File(target, base_directory)

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. When target is a string holding a relative path, base_directory is used for resolving the relative path to an absolute path if given.

copy (dest, flags)

Copies the contents of the current file to dest. Valid values for the flags table include COPY_OVERWRITE, COPY_BACKUP, COPY_NOFOLLOW_SYMLINKS, COPY_ALL_METADATA, COPY_NO_FALLBACK_FOR_MOVE, and COPY_TARGET_DEFAULT_PERMS. (Their corresponding effects are documented here).

expand_path (path)

Replaces any ocurrences ~ with the full path to the home directory.

is_absolute (path)

Returns true if path is an absolute path, and false otherwise.

tmpdir()

Returns a File instance pointing to an existing temporary directory. The directory will not be automatically deleted.

tmpfile()

Returns a File instance pointing to an existing temporary file. The file will not be automatically deleted.

with_tmpfile (callback)

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. Returns the values returned by callback.

Methods

delete ()

Deletes the file. Raises an error if unsuccesful.

delete_all ()

For a directory, delete the directory and all files contained within it. Raises an error if unsuccesful.

find (options = {})

For a directory, returns all files within the directory or any sub directory of the directory. In addition to the files, a boolean is returned indicated whether the result is partial or not (true indicating a partial result and false a complete result). The result will always be complete, unless the execution is prematurely halted by use of the on_enter option. options allows for additional control of the operation, and can contain the following fields:

find_paths (options = {})

For a directory, returns the relative paths of all files or sub directories within the directory. In addition to the paths, a boolean is returned indicated whether the result is partial or not (true indicating a partial result and false a complete result). The result will always be complete, unless the execution is prematurely halted by use of the on_enter option. In contrast to find this will return a table of strings, and not files. Compared to find this is also a much more performant operation if all you want is a list of directories or files. In order to get any detailed information about type, etc., you will have to instantiate File object, but the basic type of entry (directory or other) can be deduced by looking at end of any path - directories have a trailing separator. No guarantees are given with regards to the order of the returned entries.

options allows for additional control of the operation, and can contain the following fields:

Example:

Given the following directory structure:

/tmp/foo
  child1.lua
  sub/
    sub_child.txt
  child2.lua

You can expect the following results (order is not defined however):

howl.io.File('/tmp/foo'):find_paths()
-- =>
{
  'child1.lua',
  'child2.moon',
  'sub/'
  'sub/sub_child.txt'
}

is_below (directory)

Returns true if the file is located below directory, and false otherwise.

join (…)

Joins the file with any path components passed in as parameters, and returns a new File pointing to the resulting path.

mkdir ()

Creates a new directory at the path denoted by the file. Raises an error if unsuccesful.

mkdir_p ()

Creates a new directory at the path denoted by the file, including any non-existing intermediate directories. Raises an error if unsuccesful.

open (mode = ‘r’, callback = nil)

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.

read (…)

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.

relative_to_parent (parent)

Returns the path for the current file relative to its parent.

File('/bin/ls'):relative_to_parent(File('/bin')) -- => 'ls'

rm ()

Alias for delete.

rm_r ()

Alias for delete_all.

touch ()

Ensures that the file exists, by creating it if not already present.

Alias for delete.

Meta methods

In addition to the above properties and methods, File instances also responds to certain meta methods.

Joining files

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 as strings

Files respond to the tostring meta method:

tostring(File('/bin/ls')) -- => '/bin/ls'

Comparing files

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