FileSystem.FileHandle

This module provides access to files through FileHandles. A FileHandle represents an open file. If you know you're going to perform repeated operations on a file, it will be more efficient through a FileHandle.

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

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

An alias for a FileHandle that can be used in write operations.
type alias ReadWriteableFileHandle = FileHandle ReadPermission WritePermission

An alias for 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.

File open/close

openForRead :
Permission
-> Path
-> Task Error (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
-> Path
-> Task Error (FileHandle Never WritePermission)

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

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

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

File metadata

metadata :
ReadableFileHandle a
-> Task Error (ReadableFileHandle Metadata)

Retrieve Metadata about the file represented by the FileHandle.
changeAccess :
{ owner : Array AccessPermission
, group : Array AccessPermission
, others : Array AccessPermission
}
-> WriteableFileHandle a
-> Task Error (WriteableFileHandle a)

Change how different users can access a file.
changeOwner :
{ userID : Int
, groupID : Int
}
-> WriteableFileHandle a
-> Task Error (WriteableFileHandle a)

Change who owns the file. You'll need the ID of the new user and group who will own the file.
changeTimes :
{ lastAccessed : Posix
, lastModified : Posix
}
-> WriteableFileHandle a
-> Task Error (WriteableFileHandle a)

This will let you set the timestamp for when the file was last accessed, and last modified. The times will be rounded down to the closest second.

Read from file

read : ReadableFileHandle a -> Task Error Bytes

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

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

Write to file

write :
WriteableFileHandle a
-> Bytes
-> Task Error (WriteableFileHandle a)

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

Write bytes into a specific location of a file.
truncate :
Int
-> WriteableFileHandle a
-> Task Error (WriteableFileHandle a)

Make sure that a file is of the given size. If the file is larger than the given size, excess bytes are discarded. If the file is smaller than the given size, zeroes will be added until it is of the given size.
sync : WriteableFileHandle a -> Task Error (WriteableFileHandle a)

Usually when you make changes to a file, the changes aren't actually written to disk right away. The changes are likely placed in an OS-level buffer, and flushed to disk when the OS decides its time to do so.

This task, when executed, will force changes to be written to disk.
syncData : WriteableFileHandle a -> Task Error (WriteableFileHandle a)

Same as sync, except it only forces the contents of the file to be written. Changes to a file's metadata are not synced. This operation might be a little faster than a full sync, at the risk of loosing changes to metadata.