file

Working with files on the filesystem.

The functions included in this module are for high-level concepts such as reading and writing.

Types

Reason

Reason represents all of the reasons that Erlang surfaces of why a file system operation could fail. Most of these reasons are POSIX errors, which come from the operating system and start with E. Others have been added to represent other issues that may arise.

pub type Reason {
  Eacces
  Eagain
  Ebadf
  Ebadmsg
  Ebusy
  Edeadlk
  Edeadlock
  Edquot
  Eexist
  Efault
  Efbig
  Eftype
  Eintr
  Einval
  Eio
  Eisdir
  Eloop
  Emfile
  Emlink
  Emultihop
  Enametoolong
  Enfile
  Enobufs
  Enodev
  Enolck
  Enolink
  Enoent
  Enomem
  Enospc
  Enosr
  Enostr
  Enosys
  Enotblk
  Enotdir
  Enotsup
  Enxio
  Eopnotsupp
  Eoverflow
  Eperm
  Epipe
  Erange
  Erofs
  Espipe
  Esrch
  Estale
  Etxtbsy
  Exdev
  NotUtf8
}

Constructors

```
Eacces
```
Permission denied.
```
Eagain
```
Resource temporarily unavailable.
```
Ebadf
```
Bad file number
```
Ebadmsg
```
Bad message.
```
Ebusy
```
File busy.
```
Edeadlk
```
Resource deadlock avoided.
```
Edeadlock
```
On most architectures, same as Edeadlk. On some architectures, it means “File locking deadlock error.”
```
Edquot
```
Disk quota exceeded.
```
Eexist
```
File already exists.
```
Efault
```
Bad address in system call argument.
```
Efbig
```
File too large.
```
Eftype
```
Inappropriate file type or format. Usually caused by trying to set the “sticky bit” on a regular file (not a directory).
```
Eintr
```
Interrupted system call.
```
Einval
```
Invalid argument.
```
Eio
```
I/O error.
```
Eisdir
```
Illegal operation on a directory.
```
Eloop
```
Too many levels of symbolic links.
```
Emfile
```
Too many open files.
```
Emlink
```
Too many links.
```
Emultihop
```
Multihop attempted.
```
Enametoolong
```
Filename too long
```
Enfile
```
File table overflow
```
Enobufs
```
No buffer space available.
```
Enodev
```
No such device.
```
Enolck
```
No locks available.
```
Enolink
```
Link has been severed.
```
Enoent
```
No such file or directory.
```
Enomem
```
Not enough memory.
```
Enospc
```
No space left on device.
```
Enosr
```
No STREAM resources.
```
Enostr
```
Not a STREAM.
```
Enosys
```
Function not implemented.
```
Enotblk
```
Block device required.
```
Enotdir
```
Not a directory.
```
Enotsup
```
Operation not supported.
```
Enxio
```
No such device or address.
```
Eopnotsupp
```
Operation not supported on socket.
```
Eoverflow
```
Value too large to be stored in data type.
```
Eperm
```
Not owner.
```
Epipe
```
Broken pipe.
```
Erange
```
Result too large.
```
Erofs
```
Read-only file system.
```
Espipe
```
Invalid seek.
```
Esrch
```
No such process.
```
Estale
```
Stale remote file handle.
```
Etxtbsy
```
Text file busy.
```
Exdev
```
Cross-domain link.
```
NotUtf8
```
File was requested to be read as UTF-8, but is not UTF-8 encoded.

Functions

append

</>

pub fn append(contents contents: String, to path: String) -> Result(
  Nil,
  Reason,
)

Append the given String contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> append("Hello, World!", "file.txt")
Ok(Nil)

> append(to: "file.txt", contents: "Hello, World!")
Ok(Nil)

> append("Hello, World!", "does_not_exist/file.txt")
Error(Enoent)

append_bits

</>

pub fn append_bits(contents contents: BitString, to path: String) -> Result(
  Nil,
  Reason,
)

Append the given BitString contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> append_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "cat.gif")
Ok(Nil)

> append_bits(to: "cat.gif", contents: <<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>)
Ok(Nil)

> append_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "does_not_exist/cat.gif")
Error(Enoent)

delete

</>

pub external fn delete(String) -> Result(Nil, Reason)

Delete the given file.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> delete("file.txt")
Ok(Nil)

> delete("does_not_exist.txt")
Error(Enoent)

delete_directory

</>

pub external fn delete_directory(
  path: String,
) -> Result(Nil, Reason)

Deletes a directory.

The directory must be empty before it can be deleted. Returns a nil Success or Reason if the operation failed.

Examples

> delete_directory("foo")
Ok(Nil)

> delete_directory("does_not_exist/")
Error(Enoent)

is_directory

</>

pub external fn is_directory(path: String) -> Bool

Returns true if path refers to a directory, otherwise false.

Examples

> is_directory("/tmp")
True

> is_directory("resume.pdf")
False

is_file

</>

pub external fn is_file(path: String) -> Bool

Returns true if path refers to a file, otherwise false.

Examples

> is_file("resume.pdf")
True

> is_file("/tmp")
True

> is_file("/does_not_exist")
False

list_directory

</>

pub external fn list_directory(
  path: String,
) -> Result(List(String), Reason)

Lists all files in a directory, except files with raw filenames.

Returns a Result containing the list of filenames in the directory, or Reason if the operation failed.

Examples

> list_directory("/tmp")
Ok(["FB01293B-8597-4359-80D5-130140A0C0DE","AlTest2.out"])

> list_directory("resume.docx")
Error(Enotdir)

make_directory

</>

pub external fn make_directory(
  path: String,
) -> Result(Nil, Reason)

Tries to create a directory. Missing parent directories are not created.

Returns a Result of nil if the directory is created or Reason if the operation failed.

Examples

> make_directory("/tmp/foo")
Ok(Nil)

> make_directory("relative_directory")
Ok(Nil)

> make_directory("/tmp/missing_intermediate_directory/foo")
Error(Enoent)

read

</>

pub fn read(from path: String) -> Result(String, Reason)

Read the contents of the given file as a String

Assumes the file is UTF-8 encoded. Returns a Result containing the file’s contents as a String if the operation was successful, or Reason if the file operation failed. If the file is not UTF-8 encoded, the NotUTF8 variant will be returned.

Examples

> read("example.txt")
Ok("Hello, World!")

> read(from: "example.txt")
Ok("Hello, World!")

> read("does_not_exist.txt")
Error(Enoent)

> read("cat.gif")
Error(NotUTF8)

read_bits

</>

pub fn read_bits(from path: String) -> Result(BitString, Reason)

Read the contents of the given file as a BitString

Returns a Result containing the file’s contents as a BitString if the operation was successful, or Reason if the operation failed.

Examples

> read_bits("example.txt")
Ok(<<"Hello, World!">>)

> read_bits(from: "cat.gif")
Ok(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>)

> read_bits("does_not_exist.txt")
Error(Enoent)

recursive_delete

</>

pub external fn recursive_delete(
  path: String,
) -> Result(Nil, Reason)

Deletes a file or directory recursively.

Returns a nil Success or Reason if the operation failed.

Examples

> recursive_delete("foo")
Ok(Nil)

> recursive_delete("/bar")
Ok(Nil)

> recursive_delete("does_not_exist/")
Error(Enoent)

write

</>

pub fn write(contents contents: String, to path: String) -> Result(
  Nil,
  Reason,
)

Write the given String contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> write("Hello, World!", "file.txt")
Ok(Nil)

> write(to: "file.txt", contents: "Hello, World!")
Ok(Nil)

> write("Hello, World!", "does_not_exist/file.txt")
Error(Enoent)

write_bits

</>

pub fn write_bits(contents contents: BitString, to path: String) -> Result(
  Nil,
  Reason,
)

Write the given BitString contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> write_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "cat.gif")
Ok(Nil)

> write_bits(to: "cat.gif", contents: <<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>)
Ok(Nil)

> write_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "does_not_exist/cat.gif")
Error(Enoent)