simplifile

Types

FileError

This type represents all of the reasons for 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 specific to this library.

pub type FileError {
  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
  Unknown(inner: String)
}

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.
```
Unknown(inner: String)
```
Any error not accounted for by this type

FileInfo

</>

Represents the intersection of information available from erlang’s file:read_file_info and node’s fs.stat. For more details on what these things mean, see: the man page

pub type FileInfo {
  FileInfo(
    size: Int,
    mode: Int,
    nlinks: Int,
    inode: Int,
    user_id: Int,
    group_id: Int,
    dev: Int,
    atime_seconds: Int,
    mtime_seconds: Int,
    ctime_seconds: Int,
  )
}

Constructors

```
FileInfo(
  size: Int,
  mode: Int,
  nlinks: Int,
  inode: Int,
  user_id: Int,
  group_id: Int,
  dev: Int,
  atime_seconds: Int,
  mtime_seconds: Int,
  ctime_seconds: Int,
)
```
Arguments

size

File size in bytes.

mode

File mode that indicates the file type and its permissions. For example, in Unix and Linux, a mode value of 33188 indicates a regular file and the permissions associated with it (read and write for the owner, and read-only for others, in this case).

nlinks

Number of hard links that exist for the file.

inode

Inode number, which is a unique identifier for the file in the filesystem.

user_id

User ID of the file’s owner.

group_id

Group ID of the file’s group.

dev

Device ID of the file’s major device. TODO: We can actually get a major device and minor device from both node and erlang. The fs.stat in node returns a dev and rdev, so we can use some bitwise operations to get the minor out of rdev. Someone who’s not me should totally make a PR for that.

atime_seconds

The last access time in seconds since the UNIX epoch (00:00:00 UTC on 1 January 1970).

mtime_seconds

The last modification time in seconds since the UNIX epoch (00:00:00 UTC on 1 January 1970).

ctime_seconds

The last change time in seconds since the UNIX epoch (00:00:00 UTC on 1 January 1970).

FilePermissions

</>

Represents a set of file permissions for a given file

pub type FilePermissions {
  FilePermissions(
    user: Set(Permission),
    group: Set(Permission),
    other: Set(Permission),
  )
}

Constructors

FilePermissions(
  user: Set(Permission),
  group: Set(Permission),
  other: Set(Permission),
)

FileType

</>

An enumeration of different types of files.

pub type FileType {
  File
  Directory
  Symlink
  Other
}

Constructors

```
File
```
A regular file
```
Directory
```
A directory
```
Symlink
```
A symbolic link
```
Other
```
Another special file type present on some systems, lika a socket or device

Functions

append

</>

pub fn append(
  to filepath: String,
  contents contents: String,
) -> Result(Nil, FileError)

Append a string to the contents of a file at the given path

Example

let assert Ok(Nil) = append(to: "./needs_more_text.txt", contents: "more text")

append_bits

</>

pub fn append_bits(
  to filepath: String,
  bits bits: BitArray,
) -> Result(Nil, FileError)

Append a bitstring to the contents of a file at the given path

Example

let assert Ok(Nil) = append_bits(to: "./needs_more_text.txt", bits: <<"more text":utf8>>)

clear_directory

</>

pub fn clear_directory(at path: String) -> Result(Nil, FileError)

Clear the contents of a directory, deleting all files and directories within but leaving the top level directory in place.

copy

</>

pub fn copy(
  src src: String,
  dest dest: String,
) -> Result(Nil, FileError)

Copy a file or a directory to a new path. Copies directories recursively.

Performance Note

This function does work to determine if the src path points to a file or a directory. Consider using one of the the dedicated functions copy_file or copy_directory if you already know which one you need.

copy_directory

</>

pub fn copy_directory(
  at src: String,
  to dest: String,
) -> Result(Nil, FileError)

Copy a directory recursively

copy_file

</>

pub fn copy_file(
  at src: String,
  to dest: String,
) -> Result(Nil, FileError)

Copy a file at a given path to another path. Note: destination should include the filename, not just the directory

create_directory

</>

pub fn create_directory(
  filepath: String,
) -> Result(Nil, FileError)

Create a directory at the provided filepath. Returns an error if the directory already exists.

Example

create_directory("./test")

create_directory_all

</>

pub fn create_directory_all(
  dirpath: String,
) -> Result(Nil, FileError)

Recursively creates necessary directories for a given directory path. Note that if you pass a path that “looks like” a file, i.e. ./a/b.txt, a folder named b.txt will be created, so be sure to pass only the path to the required directory.

create_file

</>

pub fn create_file(at filepath: String) -> Result(Nil, FileError)

Creates an empty file at the given filepath. Returns an Error(Eexist) if the file already exists.

create_symlink

</>

pub fn create_symlink(
  to target: String,
  from symlink: String,
) -> Result(Nil, FileError)

Create a symbolic link called symlink pointing to target.

Footgun Alert

the target path is relative to the symlink, not the current working directory. I will likely be updating the label on the next major version to reflect that.

Example

create_symlink("../target", "./symlink")

current_directory

</>

pub fn current_directory() -> Result(String, FileError)

Returns the current working directory

delete

</>

pub fn delete(
  file_or_dir_at path: String,
) -> Result(Nil, FileError)

Delete a file or directory at a given path. Performs a recursive delete on a directory. Throws an error if the path does not exist.

Example

let assert Ok(Nil) = delete(file_at: "./delete_me.txt")

delete_all

</>

pub fn delete_all(
  paths paths: List(String),
) -> Result(Nil, FileError)

Delete all files/directories specified in a list of paths. Recursively deletes provided directories. Does not return an error if one or more of the provided paths do not exist.

describe_error

</>

pub fn describe_error(error: FileError) -> String

Convert an error into a human-readable description

Example

let assert "Input/output error" = describe_error(Eio)

file_info

</>

pub fn file_info(filepath: String) -> Result(FileInfo, FileError)

Get information about a file at a given path

When the given filepath points to a symlink, this function will follow the symlink and return information about the target file.

See link_info if you want to get information about a symlink instead.

file_info_permissions

</>

pub fn file_info_permissions(
  from file_info: FileInfo,
) -> FilePermissions

Extract the FilePermissions from a given FileInfo value.

file_info_permissions_octal

</>

pub fn file_info_permissions_octal(
  from file_info: FileInfo,
) -> Int

Extract the file permissions from a given FileInfo value in their octal representation.

Example

use info <- result.try(simplifile.file_info("src/app.gleam"))
simplifile.file_info_permissions_octal(info)
// --> 0o644

file_info_type

</>

pub fn file_info_type(from file_info: FileInfo) -> FileType

Extract the file type from a given FileInfo value.

Example

use info <- result.try(simplifile.file_info("src/app.gleam"))
simplifile.file_info_type(info)
// --> simplifile.File

file_permissions_to_octal

</>

pub fn file_permissions_to_octal(
  permissions: FilePermissions,
) -> Int

get_files

</>

pub fn get_files(
  in directory: String,
) -> Result(List(String), FileError)

Returns a list of filepaths for every file in the directory, including nested files.

is_directory

</>

pub fn is_directory(filepath: String) -> Result(Bool, FileError)

Checks if the provided filepath exists and is a directory. Returns an error if it lacks permissions to read the directory.

Example

let assert Ok(True) = is_directory("./test")

is_file

</>

pub fn is_file(filepath: String) -> Result(Bool, FileError)

Checks if the file at the provided filepath exists and is a file. Returns an Error if it lacks permissions to read the file.

Example

let assert Ok(True) = is_file("./test.txt")

is_symlink

</>

pub fn is_symlink(filepath: String) -> Result(Bool, FileError)

Checks if the file at the provided filepath exists and is a symbolic link. Returns an Error if it lacks permissions to read the file.

Example

let assert Ok(True) = is_symlink("./symlink")

link_info

</>

pub fn link_info(filepath: String) -> Result(FileInfo, FileError)

Get information about a file at a given path

When the given filepath is a symlink, this function will return infromation about the symlink itself.

See file_info if you want to follow symlinks instead.

read

</>

pub fn read(from filepath: String) -> Result(String, FileError)

Read a files contents as a string

Example

let assert Ok(records) = read(from: "./users.csv")

read_bits

</>

pub fn read_bits(
  from filepath: String,
) -> Result(BitArray, FileError)

Read a files contents as a bitstring

Example

let assert Ok(records) = read_bits(from: "./users.csv")

read_directory

</>

pub fn read_directory(
  at path: String,
) -> Result(List(String), FileError)

Lists the contents of a directory. The list contains directory and file names, and is not recursive.

Example

let assert Ok(files_and_folders) = read_directory(at: "./Folder1")

rename

</>

pub fn rename(
  at src: String,
  to dest: String,
) -> Result(Nil, FileError)

Rename a file or directory.

rename_directory

</>

pub fn rename_directory(
  at src: String,
  to dest: String,
) -> Result(Nil, FileError)

Deprecated: Use the `rename` function, which can rename a file or a directory.

Copy a directory recursively and then delete the old one.

rename_file

</>

pub fn rename_file(
  at src: String,
  to dest: String,
) -> Result(Nil, FileError)

Deprecated: This function can move a file or a directory, so it's being renamed `rename`.

Rename a file at a given path to another path. Note: destination should include the filename, not just the directory

set_permissions

</>

pub fn set_permissions(
  for_file_at filepath: String,
  to permissions: FilePermissions,
) -> Result(Nil, FileError)

Sets the permissions for a given file

Example

let all = set.from_list([Read, Write, Execute])
let all = FilePermissions(user: all, group: all, other: all)
let assert Ok(Nil) = set_permissions("./script.sh", all)

set_permissions_octal

</>

pub fn set_permissions_octal(
  for_file_at filepath: String,
  to permissions: Int,
) -> Result(Nil, FileError)

Sets the permissions for a given file using an octal representation

Example

set_permissions_octal("./script.sh", 0o777)

write

</>

pub fn write(
  to filepath: String,
  contents contents: String,
) -> Result(Nil, FileError)

Write a string to a file at the given path

Example

let assert Ok(Nil) = write(to: "./hello_world.txt", contents: "Hello, World!")

write_bits

</>

pub fn write_bits(
  to filepath: String,
  bits bits: BitArray,
) -> Result(Nil, FileError)

Write a bitstring to a file at the given path

Example

let assert Ok(Nil) = write_bits(to: "./hello_world.txt", bits: <<"Hello, World!":utf8>>)

Constructors

Constructors

Arguments

Constructors

Constructors

Constructors

Example

Example

Performance Note

Example

Footgun Alert

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example