simplifile

Types

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

Represents the intersection of information available from erlang’s file:read_file_info and node’s fs.stat

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).

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),
    )

Represents a file permission

pub type Permission {
  Read
  Write
  Execute
}

Constructors

  • Read
  • Write
  • Execute

Functions

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")
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>>)
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.

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

Copy a directory recursively

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

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")
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.

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.

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

Create a symbolic link called symlink pointing to target.

Example

create_symlink("../target", "./symlink")
pub fn current_directory() -> Result(String, FileError)

Returns the current working directory

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")
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.

pub fn describe_error(error: FileError) -> String

Convert an error into a human-readable description

Example

let assert "Input/output error" = describe_error(Eio)
pub fn file_info(filepath: String) -> Result(FileInfo, FileError)

Get information about a file at a given path

pub fn file_permissions_to_octal(
  permissions: FilePermissions,
) -> Int
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.

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")
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")
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")
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")
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")
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")
pub fn rename_directory(
  at src: String,
  to dest: String,
) -> Result(Nil, FileError)

Copy a directory recursively and then delete the old one.

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

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

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)
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)
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!")
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>>)
Search Document