type

File

abstract const class File : Obj

File is used to represent a Uri path to a file or directory. See examples.

constructors

make

Make a File for the Uri which represents a file on the local file system.

makeNew

Protected constructor for subclasses.

fields

modified

Get time the file was last modified or null if unknown.

pathSep

Return the platform's separator for a list of paths: semicolon on Windows, colon on Unix.

sep

Return the platform's separator for names within in a path: backslash on Windows, forward slash on Unix.

methods

basename

Convenience for uri.basename.

copyInto

Copy this file under the specified directory and return the destination file.

copyTo

Copy this file or directory to the new specified location.

create

Create a file or directory represented by this Uri.

createDir

Create a sub-directory under this directory.

createFile

Create a file under this directory.

createTemp

Create a temporary file which is guaranteed to be a new, empty file with a unique name.

delete

Delete this file.

deleteOnExit

Request that the file or directory represented by this File be deleted when the virtual machine exits.

eachLine

Convenience for in.eachLine.

equals

File equality is based on the un-normalized Uri used to create the File.

exists

Return if this file exists.

ext

Convenience for uri.ext.

hash

Return uri.hash.

in

Open a new buffered InStream used to read from this file.

isDir

Convenience for uri.isDir

isEmpty

If this is a file return if the file size is zero or null.

isExecutable

Return if this file is executable.

isHidden

Return if this file should be hidden to users.

isReadable

Return if this file is readable.

isWritable

Return if this file is writable.

list

List the files contained by this directory.

listDirs

List the child sub-directories contained by this directory.

listFiles

List the child files (excludes directories) contained by this directory.

mimeType

Convenience for uri.mimeType.

mmap

Memory map the region of the file specified by pos and size.

moveInto

Move this file under the specified directory and return the destination file.

moveTo

Move this file to the specified location.

name

Convenience for uri.name.

normalize

Normalize this file path to its canonical representation.

open

Open this file for random access.

os

Make a File for the specified operating system specific path on the local file system.

osPath

Get this File as an operating system specific path on the local system.

osRoots

Get the root directories of the operating system's local file system.

out

Open a new buffered OutStream used to write to this file.

parent

Get the parent directory of this file or null.

path

Convenience for uri.path.

pathStr

Convenience for uri.pathStr.

plus

Make a new File instance by joining this file's Uri together with the specified path.

readAllBuf

Convenience for in.readAllBuf.

readAllLines

Convenience for in.readAllLines.

readAllStr

Convenience for in.readAllStr.

readObj

Convenience for in.readObj The input stream is guaranteed to be closed.

readProps

Convenience for in.readProps().

rename

Renaming this file within its current directory.

size

Return the size of the file in bytes otherwise null if a directory or unknown.

store

Get the store instance which models the storage pool, device, partition, or volume used to store this file.

toStr

Return uri.toStr.

uri

Return the Uri path used to create this File.

walk

Recursively walk this file/directory top down.

writeObj

Convenience for out.writeObj The output stream is guaranteed to be closed.

writeProps

Convenience for out.writeProps().

Slot Details

basename

Str basename()

Convenience for uri.basename.

copyInto

virtual File copyInto(File dir, [Str:Obj]? options := null)

Copy this file under the specified directory and return the destination file. This method is a convenience for:

return this.copyTo(dir + this.name, options)

copyTo

virtual File copyTo(File to, [Str:Obj]? options := null)

Copy this file or directory to the new specified location. If this file represents a directory, then it recursively copies the entire directory tree.

The options map is used to customize how the copy is performed. The following summarizes the options:

  • exclude: Regex or |File f->Bool|
  • overwrite: Bool or |File f->Bool|

If the "exclude" option is a Regex - each source file's Uri string is is checked for a match to skip. If a directory is skipped, then its children are skipped also. The exclude option can also be a function of type |File f->Bool| to check each file. Exclude processing is performed first before checking for an overwrite.

If during the copy, an existing file of the same name is found, then the "overwrite" option should be to true to overwrite or false to skip. The overwrite option can also be a function of type |File to,File from->Bool| which is passed every to/from file to be overwritten. If the overwrite function throws an exception, it is raised to the copyTo caller. If a directory overwrite is skipped, then it its children are skipped too. If options are null or overwrite is unspecified then the copy is immediately terminated with an IOErr.

Any IOErr or other error encountered during the file copy immediately terminates the copy and is raised to the caller, which might leave the copy in an unfinished state.

Return the to destination file.

create

abstract File create()

Create a file or directory represented by this Uri. If isDir() is false then create an empty file, or if the file already exists overwrite it to empty. If isDir() is true then create a directory, or if the directory already exists do nothing. This method will automatically create any parent directories. Throw IOErr on error. Return this.

createDir

File createDir(Str name)

Create a sub-directory under this directory. Convenience for create:

return (this+name/.toUri).create

Throw IOErr is this file is not a directory or if there is a error creating the new directory. Return the directory created.

createFile

File createFile(Str name)

Create a file under this directory. Convenience for create:

return (this+name.toUri).create

Throw IOErr is this file is not a directory or if there is a error creating the new file. Return the file created.

createTemp

static File createTemp(Str prefix := "fan", Str suffix := ".tmp", File? dir := null)

Create a temporary file which is guaranteed to be a new, empty file with a unique name. The file name will be generated using the specified prefix and suffix. If dir is non-null then it is used as the file's parent directory, otherwise the system's default temporary directory is used. If dir is specified it must be a directory on the local file system. See deleteOnExit if you wish to have the file automatically deleted on exit. Throw IOErr on error.

Examples:

File.createTemp("x", ".txt") => `/tmp/x67392.txt`
File.createTemp.deleteOnExit => `/tmp/fan5284.tmp`

delete

abstract Void delete()

Delete this file. If this file represents a directory, then recursively delete it. If the file does not exist, then no action is taken. Throw IOErr on error.

deleteOnExit

abstract File deleteOnExit()

Request that the file or directory represented by this File be deleted when the virtual machine exits. Long running applications should use this method will care since each file marked to delete will consume resources. Throw IOErr on error. Return this.

eachLine

Void eachLine(|Str| f)

Convenience for in.eachLine. The input stream is guaranteed to be closed.

equals

virtual override Bool equals(Obj? that)

File equality is based on the un-normalized Uri used to create the File.

exists

abstract Bool exists()

Return if this file exists.

ext

Str? ext()

Convenience for uri.ext.

hash

virtual override Int hash()

Return uri.hash.

in

abstract InStream in(Int? bufferSize := 4096)

Open a new buffered InStream used to read from this file. A bufferSize of null or zero will return an unbuffered input stream. Throw IOErr on error.

isDir

Bool isDir()

Convenience for uri.isDir

isEmpty

virtual Bool isEmpty()

If this is a file return if the file size is zero or null. If this is a directory return if this directory has no files without reading a full listing.

isExecutable

virtual Bool isExecutable()

Return if this file is executable.

isHidden

virtual Bool isHidden()

Return if this file should be hidden to users. On Unix hidden files start with a dot and on Windows a metadata flag is used.

isReadable

virtual Bool isReadable()

Return if this file is readable.

isWritable

virtual Bool isWritable()

Return if this file is writable.

list

abstract File[] list(Regex? pattern := null)

List the files contained by this directory. This list includes both child sub-directories and normal files. If the directory is empty or this file doesn't represent a directory, then return an empty list. If pattern is non-null then only filenames matched are returned or if null then all filenames.

listDirs

virtual File[] listDirs(Regex? pattern := null)

List the child sub-directories contained by this directory. If the directory doesn't contain any sub-direcotries or this file doesn't represent a directory, then return an empty list. If pattern is non-null then only filenames matched are returned or if null then all filenames.

listFiles

virtual File[] listFiles(Regex? pattern := null)

List the child files (excludes directories) contained by this directory. If the directory doesn't contain any child files or this file doesn't represent a directory, then return an empty list. If pattern is non-null then only filenames matched are returned or if null then all filenames.

make

static new make(Uri uri, Bool checkSlash := true)

Make a File for the Uri which represents a file on the local file system. If creating a Uri to a directory, then the Uri must end in a trailing "/" slash or IOErr is thrown - or you may pass false for checkSlash in which case the trailing slash is implicitly added. However if a trailing slash is added, then the resulting File's uri will not match the uri passed to this method. If the file doesn't exist, then it is assumed to be to a directory based on a trailing slash (see isDir). If the Uri has a relative path, then it is assumed to be relative to the current working directory. Throw ArgErr if the Uri has a scheme other than null or "file:".

makeNew

new makeNew(Uri uri)

Protected constructor for subclasses.

mimeType

MimeType? mimeType()

Convenience for uri.mimeType.

mmap

abstract Buf mmap(Str mode := "rw", Int pos := 0, Int? size := null)

Memory map the region of the file specified by pos and size. If size is null, then use the file's size as a default. The file is paged into virtual memory on demand. Modes are:

  • "r": map the file for reading only. Throws IOErr if file does not exist.
  • "rw": open the file for reading and writing; create if the file does not exist.
  • "p": private read/write mode will not propagate changes to other processes which have mapped the file.

modified

abstract DateTime? modified

Get time the file was last modified or null if unknown.

moveInto

virtual File moveInto(File dir)

Move this file under the specified directory and return the destination file. This method is a convenience for:

return this.moveTo(dir + this.name)

moveTo

abstract File moveTo(File to)

Move this file to the specified location. If this file is a directory, then the entire directory is moved. If the target file already exists or the move fails, then an IOErr is thrown. Return the to destination file.

name

Str name()

Convenience for uri.name.

normalize

abstract File normalize()

Normalize this file path to its canonical representation. If a file on the local file system, then the uri will include the "file:" scheme. Throw IOErr on error.

open

abstract Buf open(Str mode := "rw")

Open this file for random access. Modes are:

  • "r": open the file for reading only. Throws IOErr if file does not exist.
  • "rw": open the file for reading and writing; create if the file does not exist.

The Buf instance returned is backed by a random access file pointer. It provides the same functionality as a memory backed buffer, except for a couple exceptions such as Buf.unread. The resulting Buf is a raw interface to the random access file, no buffering is provided at the framework level - so use methods which only access a few bytes carefully. However methods which transfer data with other Bufs and IO streams will use an internal buffer for efficiency.

os

static File os(Str osPath)

Make a File for the specified operating system specific path on the local file system.

osPath

abstract Str? osPath()

Get this File as an operating system specific path on the local system. If this File doesn't represent a path on the local file system then return null.

osRoots

static File[] osRoots()

Get the root directories of the operating system's local file system.

out

abstract OutStream out(Bool append := false, Int? bufferSize := 4096)

Open a new buffered OutStream used to write to this file. If append is true, then we open the file to append to the end, otherwise it is opened as an empty file. A bufferSize of null or zero will return an unbuffered output stream. Throw IOErr on error.

parent

abstract File? parent()

Get the parent directory of this file or null. Also see Uri.parent.

path

Str[] path()

Convenience for uri.path.

pathSep

const static Str pathSep

Return the platform's separator for a list of paths: semicolon on Windows, colon on Unix.

pathStr

Str pathStr()

Convenience for uri.pathStr.

plus

@Operator
abstract File plus(Uri path, Bool checkSlash := true)

Make a new File instance by joining this file's Uri together with the specified path. If the file maps to a directory and the resulting Uri doesn't end in slash then an IOErr is thrown - or pass false for checkSlash to have the slash implicitly added.

Examples:

File(`a/b/`) + `c` => File(`a/b/c`)
File(`a/b`) + `c`  => File(`a/c`)

readAllBuf

Buf readAllBuf()

Convenience for in.readAllBuf. The input stream is guaranteed to be closed.

readAllLines

Str[] readAllLines()

Convenience for in.readAllLines. The input stream is guaranteed to be closed.

readAllStr

Str readAllStr(Bool normalizeNewlines := true)

Convenience for in.readAllStr. The input stream is guaranteed to be closed.

readObj

Obj? readObj([Str:Obj]? options := null)

Convenience for in.readObj The input stream is guaranteed to be closed.

readProps

Str:Str readProps()

Convenience for in.readProps(). The input stream is guaranteed to be closed.

rename

virtual File rename(Str newName)

Renaming this file within its current directory. It is a convenience for:

return this.moveTo(parent + newName)

sep

const static Str sep

Return the platform's separator for names within in a path: backslash on Windows, forward slash on Unix.

size

abstract Int? size()

Return the size of the file in bytes otherwise null if a directory or unknown.

store

virtual FileStore store()

Get the store instance which models the storage pool, device, partition, or volume used to store this file. Raise UnsupportedErr if this file is not associated with a store.

toStr

virtual override Str toStr()

Return uri.toStr.

uri

Uri uri()

Return the Uri path used to create this File. This Uri may be absolute or relative.

walk

virtual Void walk(|File| c)

Recursively walk this file/directory top down. If this file is not a directory then the callback is invoked exactly once with this file. If a directory, then the callback is invoked with this file, then recursively for each child file.

writeObj

Void writeObj(Obj? obj, [Str:Obj]? options := null)

Convenience for out.writeObj The output stream is guaranteed to be closed.

writeProps

Void writeProps(Str:Str props)

Convenience for out.writeProps(). The output stream is guaranteed to be closed.