module watt.io.file

Simple file handling functions.

Functions for reading an entire file into memory, to check if a file exists, for deleting a file, searching a directory for a file, and so on.

Code Map

//! Simple file handling functions.
module watt.io.file;


//! Tell searchDir what to do after calling your delegate.
enum SearchStatus
{
	//! Call the delegate for any further entries.
	Continue,
	//! Stop searching; don't call the delegate further.
	Halt,
}

//! Thrown when a filesystem operation fails.
class FileException : Exception
{
public:
	this(msg: string) { }
}

//! Read a file into an array.
fn read(filename: scope (SinkArg)) void[] { }
//! Write an array of data to a file.
fn write(data: void[], filename: scope (SinkArg)) { }
//! Get the size of a file.
fn size(filename: scope (SinkArg)) size_t { }
//! Check if path matches pattern.
fn globMatch(path: string, pattern: string) bool { }
//! Call a delegate for a file in a directory that matches a given
//! pattern.
fn searchDir(dirName: string, glob: string, dgt: scope (SearchStatus delegate(string))) { }
//! Is a given path a file?
fn isFile(path: scope (SinkArg)) bool { }
//! Is a given path a directory?
fn isDir(path: scope (const(scope (char)[])) bool { }
//! Does a given path exist?
fn exists(path: const(char)[]) bool { }
//! Rename a file or directory.
fn rename(oldname: string, newname: string) { }
//! Delete a file pointed to by a given path.
fn remove(path: const(char)[]) { }
//! Change the current working directory of the calling process.
fn chdir(path: const(char)[]) { }
//! Get the current working directory of the calling process.
fn getcwd() string { }
class FileException : Exception

Thrown when a filesystem operation fails.

fn read(filename: scope (SinkArg)) void[]

Read a file into an array.

Read the contents of the file pointed to by filename into a void[] array. The intepretation is left up to the caller.

For example, if you want to treat the data as a string:

str := cast(string)read("file.txt");

The entire file is read into memory at once, so be wary of using this function for very large files.

Parameters

filename

The path to the file to read.

Return

The entire contents of the file.

Throws

  • FileException if the file cannot be read.

fn write(data: void[], filename: scope (SinkArg))

Write an array of data to a file.

data is interpreted as an array of bytes, and each byte is written to a new file named filename.
If filename is an existing file, it will be overwritten.

Throws

  • FileException if a file cannot be opened for writing.

fn size(filename: scope (SinkArg)) size_t

Get the size of a file.

Return

the size of filename in bytes.

Throws

  • FileException if the file cannot be read.

fn globMatch(path: string, pattern: string) bool

Check if path matches pattern.

pattern is treated as a regular string except for two special characters:

  • * matches zero or more characters.
  • ? matches a single character.

    Examples

globMatch("file.txt", "file.txt");       // true
globMatch("file.txt", "file.txtextra");  // false
globMatch("file.txt", "*.txt");          // true
globMatch("file.txt", "*.???");          // true
globMatch("file.txt", "*.??");           // false

Return

true if pattern matches path.

fn searchDir(dirName: string, glob: string, dgt: scope (SearchStatus delegate(string)))

Call a delegate for a file in a directory that matches a given pattern.

Example

sourceFiles: string[];
fn addFile(s: string) SearchStatus { sourceFiles ~= s; return SearchStatus.Continue; }
searchDir(".", "*.volt", addFile);

If you are calling this recursively (i.e., calling searchDir on directories in a directory), be aware that the special directories . and .. will make an appearance if glob is *, and so your delegate will likely have to special case them.

Parameters

dirName

The directory to search the contents of.

glob

The pattern to check every entry in dirName against. The matching rules are the same as the pattern parameter of the globMatch function.

dgt

A delegate that is called with every path in dirName that matches glob.

Throws

  • FileException If dirName could not be opened or read.

enum SearchStatus

Tell searchDir what to do after calling your delegate.

enum Continue

Call the delegate for any further entries.

enum Halt

Stop searching; don't call the delegate further.

fn isFile(path: scope (SinkArg)) bool

Is a given path a file?

For example, a directory would not be classified as a file.

Return

true if path points to a file.

fn isDir(path: scope (const(scope (char)[])) bool

Is a given path a directory?

For example, a file is not a directory.

Return

true if path points to a directory.

fn exists(path: const(char)[]) bool

Does a given path exist?

Return

true if path exists.

fn rename(oldname: string, newname: string)

Rename a file or directory.

This is a thing wrapper around the C library's rename; consult your system's libc documentation for more details.

Parameters

oldname

The path to rename.

newname

The path rename oldname to.

fn remove(path: const(char)[])

Delete a file pointed to by a given path.

This could fail for a number of reasons.
As the functions in this module are intended to be simple, more detailed failure information is not available. If you need more information, use the functions provided by your operating system.

Throws

  • FileException if the file could not be deleted for some reason.

fn chdir(path: const(char)[])

Change the current working directory of the calling process.

Throws

  • FileException if the path could not be changed to.

fn getcwd() string

Get the current working directory of the calling process.

Throws

  • FileException if there was a error retrieving the current working directory.