FileSystem

This module provides access to the file system. It allows you to read and write files, create directories and links etc.

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 Error

Represents an error that occured when working with the file system.

There are many different kinds of error depending on which operation you're performing and which operating system you're performing it on. To figure out which error it is, you'll need to use one of the helper functions below, or check the specific error code.
errorCode : Error -> String

A string that identifies a specific kind of error. There can be several error codes for the same kind of error, depending on the operating system that is in use.
errorToString : Error -> String

Returns a human readable description of the error.
errorIsPermissionDenied : Error -> Bool

If True, the error occured because you don't have the correct access permission to perform the operation.
errorIsFileExists : Error -> Bool

If True, a file exists when it was expected not to.
errorIsDirectoryFound : Error -> Bool

If True, a file operation was attempted on a directory.
errorIsTooManyOpenFiles : Error -> Bool

If True, the application has too many open files.
errorIsNoSuchFileOrDirectory : Error -> Bool

If True, the code was passed a Path which points to a file or directory that doesn't exist.
errorIsNotADirectory : Error -> Bool

If True, a directory was expected but it found a file or some other entity.
errorIsDirectoryNotEmpty : Error -> Bool

If True, the operation expected an empty directory, but the directory is not empty.
errorIsNotPermitted : Error -> Bool

If True, the operation was rejected because of missing privileges.
errorIsLinkLoop : Error -> Bool

If True, we seem to be stuck in a loop following link after link after...
errorIsPathTooLong : Error -> Bool

If True, the Path is too long.
errorIsInvalidInput : Error -> Bool

If True, the arguments passed to the function is invalid somehow.
errorIsIO : Error -> Bool

If True, the operation failed due to an IO error. This could be that the disk is busy, or even corrupt.

Metadata

type alias Metadata =
{ entityType : EntityType
, deviceID : Int
, userID : Int
, groupID : Int
, byteSize : Int
, blockSize : Int
, blocks : Int
, lastAccessed : Posix
, lastModified : Posix
, lastChanged : Posix
, created : Posix
}

Represents extra information about an entity in the file system.
type EntityType
= File
| Directory
| Socket
| Symlink
| Device
| Pipe

The type of an entity in the file system.
metadata :
Permission
-> { resolveLink : Bool }
-> Path
-> Task Error Metadata

Return metadata for the entity represented by Path.

If resolveLink is False, you will receive metadata for the link itself, not the entity pointed at by the link.
type AccessPermission
= Read
| Write
| Execute

Represents the permission to access an entity for a specific operation.

For example: if you, or your group, doesn't have the Read permission for a file, you're not allowed to read from it.
checkAccess :
Permission
-> Array AccessPermission
-> Path
-> Task Error Path

Check if the user running this application has the given access permissions for the entity represented by Path.

Passing an empty Array will check that the entity exists.
changeAccess :
Permission
-> { owner : Array AccessPermission, group : Array AccessPermission , others : Array AccessPermission }
-> Path
-> Task Error Path

Change the access permissions for the entity's owner, group and everyone else.
accessPermissionsToInt : Array AccessPermission -> Int

The integer representation of a set of access permissions in a posix system.

accessPermissionsToInt [ Read, Write ] == 6
changeOwner :
Permission
-> { userID : Int, groupID : Int , resolveLink : Bool }
-> Path
-> Task Error Path

Change the user and group that owns a file.

You'll need the ID of the owner and group to perform this operation.

If resolveLink is False, you're changing the owner of the link itself, not the entity it points to.
changeTimes :
Permission
-> { lastAccessed : Posix, lastModified : Posix , resolveLink : Bool }
-> Path
-> Task Error Path

Change the registered time (down to the second) an entity was accessed and modified.

If resolveLink is False, you're changing the last access and modification time of the link itself, not the entity it points to.
move : Permission -> Path -> Path -> Task Error Path

Move the entity represented by the last Path, to the location represented by the first Path. This can also be used to rename an entity.
realPath : Permission -> Path -> Task Error Path

If you have a Path that is relative to the current directory, or points at a link, you can use this find the true Path of the entity.

Files

copyFile : Permission -> Path -> Path -> Task Error Path

Copy the file represented by the last Path, to the location represented by the first Path.
appendToFile : Permission -> Bytes -> Path -> Task Error Path

Add Bytes to the end of a file.
readFile : Permission -> Path -> Task Error Bytes

Read the entire contents of a file.

Note: This will return the entire contents of a file at once. For very large files this might cause you to run out of memory. In those cases you might want to use readFileStream instead.
readFileStream : Permission -> Path -> Task Error (Readable Bytes)

Read the contents of a file as a stream.
writeFile : Permission -> Bytes -> Path -> Task Error Path

Write the given Bytes into a file. The file will be created if it doesn't exist, and overwritten if it does.
writeFileStream : Permission -> Path -> Task Error (Writable Bytes)

Create a writable stream backed by a file.
truncateFile : Permission -> Int -> Path -> Task Error Path

Make sure the given file is of a specific length. If the file is smaller than the given length, zeroes is added to the file until it is the correct length. If the file is larger than the given length, the excess bytes are removed.
remove :
Permission
-> { recursive : Bool, ignoreErrors : Bool }
-> Path
-> Task Error Path

Remove the file or directory at the given path.

  • recursive will delete everything inside a directory.
  • ignoreErrors will... ignore any errors related to a remove operation.

Directories

listDirectory :
Permission
-> Path
-> Task Error (Array { path : Path, entityType : EntityType })

List the contents of a directory. The returned Paths are relative to the directory being listed.
makeDirectory :
Permission
-> { recursive : Bool }
-> Path
-> Task Error Path

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.
makeTempDirectory : Permission -> String -> Task Error Path

Create a directory, prefixed by a given name, that ends up in a section of the file system reserved for temporary files. You're given the Path to this new directory.

Links

Watch for changes

type WatchEvent
= Changed (Maybe Path)
| Moved (Maybe Path)

Represents a change within a watched directory.

  • Changed means that the contents of a file has changed in some way.
  • Moved means that an entity has been added or removed. A rename is usually two Moved events.

On most operating systems, each event will be associated with a Path relative to the watched directory, but some operating systems will not provide that information.
watch : Permission -> (WatchEvent -> msg) -> Path -> Sub msg

This notifies your application every time there is a change within the directory represented by the given Path.
watchRecursive : Permission -> (WatchEvent -> msg) -> Path -> Sub msg

Same as watch, but this will also watch for changes in sub-directories.

Special paths

homeDirectory : Permission -> Task x Path

Find the Path that represents the home directory of the current user.
currentWorkingDirectory : Permission -> Task x Path

Returns the current working directory of the program.

This is the directory that all relative paths are relative to, and is usually the directory that the program was executed from.
tmpDirectory : Permission -> Task x Path

Find a Path that represents a directory meant to hold temporary files.
devNull : Permission -> Task x Path

Path to a file which is always empty. Anything written to this file will be discarded.