frost.io

Class File

    └ Immutable
         └ Object

Implemented Interfaces:
HashKey<File>

Represents a file path, providing methods to query, read, and write files. A File object itself is merely the path to the file, not the actual physical file on disk, so creating a File object does not in and of itself cause any interaction with the filesystem.

File always uses "/" as a path separator regardless of the operating environment's native path separator. Relative paths (that is, those that do not begin with "/") are interpreted relative to System.workingDirectory(), which never changes while a program is running.

Source Code:
View Source

Initializer Summary

init(path:String)
Creates a new File with the specified path.

Field Summary

path:String
The path represented by this File.
isAbsolute:Bit
true if this file represents an absolute path.
directory:File?
The directory containing this file, or null if this file is the root directory or `".
name:String
The name (not including directory) of this file.
simpleName:String
The name of this file without its extension.
Inherited Fields:
toString

Instance Method Summary

resolve(path:String):File
Resolves a path relative to this File.
lines():Maybe<Iterator<String>>
Returns an iterator which reads from the file line-by-line.
absolute():Maybe<File>
Returns a File representing the absolute path of this file.
parent():File?
withExtension(ext:String):File
Removes the extension (including the period) from this path and replaces it with a new extension.
exists():Bit
Returns true if this file exists.
isDirectory():Bit
Returns true if this path represents a directory.
list():Maybe<ListView<File>>
Returns a list of files contained by this directory, or an Error if the path could not be listed.
createDirectory():Error?
Creates a directory at this path.
createDirectories():Error?
Creates a directory at this path, including all required parent directories.
openInputStream():Maybe<InputStream>
Returns an InputStream for reading this file.
openOutputStream():Maybe<OutputStream>
Destroys any existing contents of this file and returns an OutputStream for writing it.
openForAppend():Maybe<OutputStream>
Returns an OutputStream for writing to the end of this file.
readFully():Maybe<String>
Reads the entire contents of the file into memory as a String and returns it.
readFully():Maybe<Array<UInt8>>
Reads the entire contents of the file into memory as an Array<UInt8> and returns it.
write(contents:String):Error?
Writes a string to this path.
rename(path:File):Error?
Attempts to rename the file to a different path.
delete():Error?
Attempts to delete the file.
-- equals operator --
=(other:File):Bit
Returns true if both files refer to the same path.
Inherited Methods:
!=(T):Bit

Initializers

init (path:String)

Creates a new File with the specified path. This merely creates a new object representing the path does not access the file system in any way.

Parameters:
path - value of type String

Fields

def path:String

The path represented by this File.

property isAbsolute:Bit

true if this file represents an absolute path.

property directory:File?

The directory containing this file, or null if this file is the root directory or ".". The directory is computed based purely on the path string, without accessing the filesystem. Use parent() to determine the directory by accessing the filesystem.

property name:String

The name (not including directory) of this file. For instance, File("/tmp/data/log.txt").name is "log.txt".

property simpleName:String

The name of this file without its extension. The file's extension is considered to start at the last period ('.') it contains, so File("/tmp/foo.bar.baz").simpleName() returns the path "foo.bar". If the filename does not contain a period, this property is equivalen to name.

Instance Methods

function resolve (path:String
):File

Resolves a path relative to this File. If the path begins with "/", it is absolute and returned as-is. Otherwise this File is interpreted as a directory containing the relative path, so for instance File("/tmp/output").relative("data/dump.xml") results in the path "/tmp/output/data/dump.xml". This function merely performs string manipulation and does not access the filesystem.

Parameters:
path - the relative or absolute path
Returns:
the final path
function lines ():Maybe<Iterator<String>>

Returns an iterator which reads from the file line-by-line. Either "\r\n" or "\n" is accepted as a line ending, and the line endings are not part of the returned strings.

Returns:
the contents of the file line-by-line
method absolute ():Maybe<File>

Returns a File representing the absolute path of this file. This queries the filesystem and thus is not guaranteed to succeed.

Returns:
the file's absolute path
function parent ():File?
function withExtension (ext:String
):File

Removes the extension (including the period) from this path and replaces it with a new extension. This does not alter the file on disk; it merely performs string manipulation to compute a new path. The new extension does not have to contain a period; it is possible to turn a path with an extension into one without using this method. It is a safety violation to call this on a path which does not have a filename (e.g. "/" or "..").

Examples:

File("/tmp/foo.gif").withExtension(".png") => /tmp/foo.png
File("/tmp/foo").withExtension(".png") => /tmp/foo.png
File("/tmp/foo.gif").withExtension("") => /tmp/foo
File("/tmp/foo.tar.gz").withExtension("") => /tmp/foo.tar
Try it!
Parameters:
ext - the new extension
Returns:
the path with a new extension
method exists ():Bit

Returns true if this file exists. A return value of false indicates either that the path does not exist or that an error occurred while trying to query the filesystem.

Returns:
true if this file exists
method isDirectory ():Bit

Returns true if this path represents a directory. A return value of false indicates either that the path does not exist, is not a directory, or that an error occurred while trying to query the filesystem.

Returns:
true if this is a directory
method list ():Maybe<ListView<File>>

Returns a list of files contained by this directory, or an Error if the path could not be listed.

method createDirectory ():Error?

Creates a directory at this path. It is not an error to attempt to create a directory which already exists.

method createDirectories ():Error?

Creates a directory at this path, including all required parent directories. It is not an error to attempt to create a directory which already exists.

method openInputStream ():Maybe<InputStream>

Returns an InputStream for reading this file.

Returns:
an InputStream
method openOutputStream ():Maybe<OutputStream>

Destroys any existing contents of this file and returns an OutputStream for writing it. If the file does not already exist, it is created.

Returns:
an OutputStream
method openForAppend ():Maybe<OutputStream>

Returns an OutputStream for writing to the end of this file. If the file does not already exist, it is created.

Returns:
an OutputStream
method readFully ():Maybe<String>

Reads the entire contents of the file into memory as a String and returns it. Naturally, you should be careful to only call readFully() for files which comfortably fit into memory.

Returns:
the contents of the file
method readFully ():Maybe<Array<UInt8>>

Reads the entire contents of the file into memory as an Array<UInt8> and returns it. Naturally, you should be careful to only call readFully() for files which comfortably fit into memory.

Returns:
the contents of the file
method write (contents:String
):Error?

Writes a string to this path. If the file already exists, its contents are replaced. If it does not exist, it is created.

Parameters:
contents - the data to write
method rename (path:File
):Error?

Attempts to rename the file to a different path. The rules about when files can be renamed and to which paths depend upon the operating environment, but generally speaking the source and destination paths must be on the same filesystem for this operation to succeed. Returns an Error if the file could not be renamed.

Parameters:
path - value of type File
method delete ():Error?

Attempts to delete the file. If the file is a directory, it must be empty or the operation will fail. Returns an Error if the file could not be deleted.

-- equals operator --
@override
function = (other:File
):Bit

Returns true if both files refer to the same path. Note that two files can refer to the same physical file on disk without being the same path (e.g. File("src/Foo.frost") and File("src/../src/Foo.frost")); these are considered not equal despite resolving to the same physical file.

Parameters:
other - value of type File
Returns:
true if the files refer to the same path
Overrides:
frost.core.Equatable.=