Source Code

API for accessing hierarchical file systems. Clients use Paths to obtain Resources representing files or directories.

Path contains many useful operations for manipulating paths:

value path = parsePath("/Users/Trompon/Documents");
value child = path.childPath("hello.txt");
value sibling = child.siblingPath("goodbye.txt");
value parent = path.parent;

The attribute resource of Path is used to obtain a Resource. It is usually necessary to narrow a Resource to one of the following enumerated subtypes before performing operations on it:

  • a File contains data,
  • a Directory contains other resources,
  • a Link is a symbolic link to another resource, or
  • a Nil is an unoccupied location in the filesystem where a resource may safely be created.

To create a file named hello.txt in the home directory, we could do the following:

value filePath = home.childPath("hello.txt");
if (is Nil loc = filePath.resource) {
    value file = loc.createFile();
    try (writer = file.Overwriter()) {
        writer.writeLine("Hello, World!");
    }
}
else {
    print("file already exists");
}

Note the difference between a File.Overwriter, which destroys the existing contents of the file, if any, and a File.Appender, which leaves them intact.

To print the contents of the file we just created, we could do this:

value filePath = home.childPath("hello.txt");
if (is File file = filePath.resource) {
    try (reader = file.Reader()) {
        print(reader.readLine());
    }
}
else {
    print("file does not exist");
}

Now, to rename the file:

value filePath = home.childPath("hello.txt");
if (is File file = filePath.resource) {
    value newPath = filePath.siblingPath("goodbye.txt");
    if (is Nil loc = newPath.resource) {
       file.move(loc);
    }
    else {
        print("target file already exists");
    }
}
else {
    print("source file does not exist");
}

To list the contents of a directory, we have two possibilities. We can list just the direct contents:

if (is Directory dir = home.resource) {
    for (path in dir.childPaths()) {
        print(path);
    }
}
else {
    print("directory does not exist");
}

Alternatively, we can create a Visitor that walks the whole directory tree rooted at a given path:

object visitor extends Visitor() {
    file(File file) => print(file.path);
}
home.visit(visitor);

File systems other than the default file system are supported. For example, a file system for a zip file may be created using the convenience function createZipFileSystem().

value zipPath = home.childPath("myzip.zip");
if (is Nil|File loc = zipPath.resource) {
    value zipSystem = createZipFileSystem(loc);
    value entryPath = zipSystem.parsePath("/hello.txt");
    if (is Nil entry = entryPath.resource) {
        value filePath = home.childPath("hello.txt");
        if (is File file = filePath.resource) {
            file.copy(entry);
        }
        else {
            print("source file does not exist");
        }
    }
    else {
        print("entry already exists");
    }
    zipSystem.close();
}
Platform: Java
By: Gavin King
Packages
ceylon.file

Public API for the file system module.

Dependencies
ceylon.collection1.3.0
java.base8

Public API for the file system module.

Aliases
AttributeSource Codeshared Attribute=> String[2]

A view-name, attribute-name pair that identifies a file system attribute, for example ["dos", "hidden"], ["posix", "group"], ["unix", "uid"], or ["basic", "lastAccessTime"].

See also BasicFileAttributeView
Values
currentSource Codeshared Path current

The Path representing the user current working directory.

defaultSystemSource Codeshared defaultSystem defaultSystem

A System representing the default file system.

homeSource Codeshared Path home

The Path representing the user home directory.

rootDirectoriesSource Codeshared Directory[] rootDirectories

The Directorys representing the root directories of the default file system.

See also defaultSystem
rootPathsSource Codeshared Path[] rootPaths

The Paths representing the root directories of the default file system.

See also defaultSystem
storesSource Codeshared Store[] stores

The Stores representing the stores of the default file system.

See also defaultSystem
temporaryDirectorySource Codeshared Directory temporaryDirectory

The system default temporary directory.

Functions
createFileIfNilSource Codeshared File createFileIfNil(File|Nil res)

Return a File, creating a new file if the given resource is Nil, or returning the given File otherwise.

createSystemSource Codeshared System createSystem(String uriString, <String->String>[] properties)

Create a System given a URI and a sequence of named values.

Parameters:
  • uriString

    The URI, as a string.

  • properties

    A sequence of file system-specific named values.

createZipFileSystemSource Codeshared System createZipFileSystem(File|Nil file, String encoding = ...)

Create a System for accessing entries in a zip file.

Parameters:
  • file

    The zip file. If Nil, a new zip file will be automatically created.

  • encoding = "UTF-8"

    The character encoding for entry names.

forEachLineSource Codeshared void forEachLine(File file, void do(String line))

Call the given function for each line of text in the given file.

For example, to print the contents of the file:

forEachLine(file, print);

Or:

forEachLine(file, (line) {
    print(line);
});
linesSource Codeshared String[] lines(File file)

All lines of text in the given file.

parsePathSource Codeshared Path parsePath(String pathString)

Obtain a Path in the default file system given the string representation of a path.

See also defaultSystem
parseURISource Codeshared Path parseURI(String uriString)

Obtain a Path given the string representation of a URI. The scheme determines the file system the path belongs to. The scheme file: refers to the default file system.

See also System
readAndAppendLinesSource Codeshared void readAndAppendLines(File from, File to, String replacing(String line) = ...)

Copy lines from one file to a second file, appending to the second file.

Parameters:
  • replacing = line

    A transformation to apply to each line of text.

readAndOverwriteLinesSource Codeshared void readAndOverwriteLines(File from, File to, String replacing(String line) = ...)

Copy lines from one file to a second file, overwriting the second file.

Parameters:
  • replacing = line

    A transformation to apply to each line of text.

sameFileSource Codeshared Boolean sameFile(File x, File y)

Determines if the two given File objects represent the same file.

Interfaces
DirectorySource Codeshared Directory

Represents a directory in a hierarchical file system.

ExistingResourceSource Codeshared ExistingResource

A resource that actually exists—that is one that is not Nil.

FileSource Codeshared File

Represents a file in a hierarchical file system.

Source Codeshared Link

Represents a symbolic link.

NilSource Codeshared Nil

Represents the absence of any existing file or directory at a certain path in a hierarchical file system.

PathSource Codeshared Path

Represents a path in a hierarchical file system. A path is a sequence of path elements. A path may be an absolute path that begins at the root of the file system, or a relative path.

ReaderSource Codeshared Reader

Reads lines of text from a File.

ResourceSource Codeshared Resource

Represents a file, link, or directory located at a certain path, or the absence of a file or directory at that path.

StoreSource Codeshared Store

Represents a file system store.

SystemSource Codeshared System

Represents a special-purpose file system.

WriterSource Codeshared Writer

Writes text to a File.

Classes
VisitorSource Codeshared Visitor

A file visitor.

defaultSystemSource Codeshared defaultSystem

A System representing the default file system.

Exceptions
NoSuchPrincipalExceptionSource Codeshared NoSuchPrincipalException

Thrown if there is no principal with the specified name.