FileSystem

This module provides access to the file system. It allows you to read and write files or directories.

Initialization

type Permission

This value represents the permission to perform file system operations.

Only code you trust should have access to this value.
initialize : Task Permission

Initialize the FileSystem subsystem, which gains you the permission to perform file system operations.

Errors

type AccessError
= AccessErrorNotFound
| AccessErrorNoAccess
| AccessErrorNotADirectory
| AccessErrorUnknown String

The set of errors that can happen when accessing a file or directory.
type UnknownFileSystemError
= UnknownFileSystemError String

An error thrown by the OS, in situations where we don't expect errors to happen, or have been unable to reproduce such an error in development.

File open/close

type FileHandle readAccess writeAccess

A file handle is used to perform operations on a file, like reading and writing.

Having a file handle gives you access to perform certain operations, so make sure you only pass a file handle to code you can trust.

The FileHandle type also contains the read and write access permissions as part of its type.
type alias ReadableFileHandle a = FileHandle ReadPermission a

A FileHandle that can be used in read operations.
type alias WriteableFileHandle a = FileHandle a WritePermission

A FileHandle that can be used in write operations.
type alias ReadWriteableFileHandle = FileHandle ReadPermission WritePermission

A FileHandle that can be used for both read and write operations.
type ReadPermission

A type that represents the permission to read from a file.
type WritePermission

A type that represents the permission to write to a file.
makeReadOnly : ReadWriteableFileHandle -> FileHandle ReadPermission Never

This lets you downgrade a ReadWriteableFileHandle to a FileHandle that only has read permission.

Comes in handy when you want full access to a file in some parts of your code, but limited access in other parts of your code.
makeWriteOnly : ReadWriteableFileHandle -> FileHandle Never WritePermission

This let's you downgrade a ReadWriteableFileHandle to a FileHandle that only has write permission.

Comes in handy when you want full access to a file in some parts of your code, but limited access in other parts of your code.
openForRead :
Permission
-> String
-> Task AccessError (FileHandle ReadPermission Never)

Open the file at the provided path with read permissions.
type OpenForWriteBehaviour
= EnsureEmpty
| ExpectExisting
| ExpectNotExisting

There are several ways to open a file for writing.

  • EnsureEmpty will create an empty file if it doesn't exist, or remove all contents of a file if it does exist.
  • ExpectExisting will fail the task if it doesn't exist.
  • ExpectNotExisting will fail the task if the file does exist.
openForWrite :
Permission
-> OpenForWriteBehaviour
-> String
-> Task AccessError (FileHandle Never WritePermission)

Open a file at the provided path with write permissions.
openForReadAndWrite :
Permission
-> OpenForWriteBehaviour
-> String
-> Task AccessError ReadWriteableFileHandle

Open a file for at the provided path with both read and write permissions.
close : FileHandle a b -> Task UnknownFileSystemError {}

Close a file. All operations performed against the given FileHandle will fail.

Read from file

read : ReadableFileHandle a -> Task UnknownFileSystemError Bytes

Read all bytes in a file.
readFromOffset :
ReadableFileHandle a
-> { offset : Int, length : Int }
-> Task UnknownFileSystemError Bytes

Read length number of bytes from a file, starting at offset bytes.

Write to file

write :
WriteableFileHandle a
-> Bytes
-> Task UnknownFileSystemError {}

Write the provided bytes into the file. If the file is not empty, bytes will be overwritten.
writeFromOffset :
WriteableFileHandle a
-> Int
-> Bytes
-> Task UnknownFileSystemError {}

Write bytes into a specific location of a file.

Remove files and directories

type alias RemoveOptions = { recursive : Bool, ignoreErrors : Bool }

This record allows you to customize the behaviour of remove.

  • recursive will delete everything inside a directory.
  • ignoreErrors will... ignore any errors related to a remove operation.
remove :
Permission
-> String
-> RemoveOptions
-> Task AccessError {}

Remove the file or directory at the given path.

Directories

makeDirectory :
Permission
-> String
-> { recursive : Bool }
-> Task AccessError {}

Create a new directory at the given path.

If recursive is True, then a directory will be created for every section of the given path.
type DirEntry
= File String
| Directory String
| Socket String
| Symlink String
| Device String
| Pipe String

Represents entries in a directory.

Variants for each type of entry, with a String representing the relative path.

As returned by FileSystem.listDirectory.
listDirectory : Permission -> String -> Task AccessError (Array DirEntry)

Returns an Array of DirEntry variants holding names of the files in the directory at the given path.

Paths

buildPath : Array String -> String

Joins an array of strings using the filesystem's path seperator, then normalizes the result. An empty array will result in ".", a path to the current working directory.

buildPath [] == "."
buildPath [ "one", "two", "three" ] == "one/two/three" -- On Unix based operating systems
normalizePath : String -> String

Removes redundant symbols from the path.

normalizePath "one/two/.." == "one/two"
currentWorkingDirectory : Permission -> Task Never String

Returns the current working directory of the program. This is the directory that all relative paths are relative to.