howl.ui.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:

• The spec for File

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:

• ‘directory’
• ‘regular’
• ‘symlink’
• ‘special’
• ‘unknown’
• ‘mountable’

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.

is_link

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.

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.

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. 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.

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.

unlink ()

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