## Overview

This module provides APIs, which perform file, file path, and directory operations, and a `Directory Listener`, which is used to listen to a directory in the local file system.

This provides the interface to create, delete, rename the file/directory, retrieve metadata of the given file, and manipulate the 
filename paths in a way that is compatible according to the target file paths defined by the operating system.

The path of the file/directory needs to be defined with either forward slashes or back slashes depending on the operating system.

### Directory Listener

The `file:Listener` is used to monitor all the files and subdirectories inside the specified directory. 

A `Listener` endpoint can be defined using the mandatory `path` parameter and the optional `recursive` parameter as follows.

```ballerina
listener file:Listener inFolder = new ({
    path: "<The directory path>",
    recursive: false
});
```

If the listener needs to monitor subdirectories of the given directory, `recursive` needs to be set to `true`. The default value of this is `false`.

A `Service` has the defined remote methods with the `file:FileEvent` and can be exposed via a `Listener` endpoint. 
When there are changes in the listening directory, the `file:FileEvent` will be triggered with the action of the file 
such as creating, modifying, or deleting. 

The remote methods supported by the `Service` are as follows.

**onCreate:** This method is invoked once a new file is created in the listening directory.

**onDelete:** This method is invoked once an existing file is deleted from the listening directory.

**onModify:** This method is invoked once an existing file is modified in the listening directory.

The following code sample shows how to create a `Service` with the `onCreate` remote method and attach it to the above `Listener` endpoint:

```ballerina
service "localObserver" on inFolder {

    remote function onCreate(file:FileEvent m) {
        string msg = "Create: " + m.name;
        log:printInfo(msg);
    }
}
```

For information on the operations, which you can perform with the file module, see the below **Functions**.


Represents options that can be used when copying files/directories



Replace the target path if it already exists


REPLACE_EXISTING

Copy the file attributes as well to the target


COPY_ATTRIBUTES

If source is a symlink, only the link is copied, not the target of the link


NO_FOLLOW_LINKS

CopyOption

Represents options that can be used when creating or removing directories.



Create non-existing parent directories or remove all the files inside the given directory


RECURSIVE

NON_RECURSIVE

DirOption

Represents the options that can be passed to the `normalizePath` function.



Get the shortest path name equivalent to the given path by eliminating multiple separators, '.', and '..'


CLEAN

SYMLINK

Normalize the case of a pathname. On windows, all the characters are converted to lowercase and "/" is
converted to "\".


NORMCASE

NormOption

Represents the options that can be passed to the test function.



EXISTS

IS_DIR

IS_SYMLINK

READABLE

WRITABLE

TestOption

Error

Represents an error, which occurs when the file/directory does not exist in the given file path.


FileNotFoundError

Represents an error that occurs when a file system operation fails.


FileSystemError

Represents a generic error for the file path.


GenericError

Represents an error that occurs when a file system operation is denied due to invalidity.


InvalidOperationError

Represents an error, which occurs when the given file path is invalid.


InvalidPathError

Represents an error, which occurs when the given pattern is not a valid file path pattern.


InvalidPatternError

Represents an IO error, which occurs when trying to access the file in the given file path.


IOError

Represents an error, which occurs when the file in the given file path is not a symbolic link.


NotLinkError

Represents an error that occurs when a file system operation is denied, due to the absence of file permission.


PermissionError

Represents an error, which occurs when the given target file path cannot be derived relative to the base file path.


RelativePathError

Represents a security error, which occurs when trying to access the file in the given file path.


SecurityError

Represents an error, which occurs in the UNC path.


UNCPathError

Retrieves the base name of the file from the provided location,
which is the last element of the path.
Trailing path separators are removed before extracting the last element.
```ballerina
 string name = check file:basename("/A/B/C.txt");
```



basename

path

string

The name of the file or else a `file:Error` if the path is invalid


Copy the file/directory in the old path to the new path.
```ballerina
check file:copy("/A/B/C", "/A/B/D", true);
```



copy

sourcePath

destinationPath

Parameter to denote how the copy operation should be done. Supported options are,
`REPLACE_EXISTING` - Replace the target path if it already exists,
`COPY_ATTRIBUTES` - Copy the file attributes as well to the target,
`NO_FOLLOW_LINKS` - If source is a symlink, only the link is copied, not the target of the link.


options

Creates a file in the specified file path.
Truncates if the file already exists in the given path.
```ballerina
check file:create("bar.txt");
```



create

Creates a new directory with the specified name.
```ballerina
check file:createDir("foo/bar");
```



createDir

Indicates whether the `createDir` should create non-existing parent directories. The default is only to
create the given current directory.


option

A `file:Error` if the directory creation failed


Creates a temporary file.
```ballerina
string tmpFile = check file:createTemp();
```



createTemp

suffix

prefix

The directory path where the temp file should be created. If not specified,
temp file will be created in the default temp directory of the OS.


Temporary file path or else a `file:Error` if there is an error


Creates a temporary directory.
```ballerina
string tmpDir = check file:createTempDir();
```



createTempDir

The directory path where the temp directory should be created. If not specified, temp directory
will be created in the default temp directory of the OS.


Temporary directory path or else a `file:Error` if there is an error


Retrieves the absolute path from the provided location.
```ballerina
 string absolutePath = check file:getAbsolutePath("test.txt");
```



getAbsolutePath

String value of the file path free from potential malicious codes


The absolute path reference or else a `file:Error` if the path cannot be derived


Returns the current working directory.
```ballerina
string dirPath = file:getCurrentDir();
```



getCurrentDir

Current working directory or else an empty string if the current working directory cannot be determined


Returns the metadata information of the file specified in the file path.
```ballerina
file:MetaData result = check file:getMetaData("foo/bar.txt");
```



getMetaData

The `MetaData` instance with the file metadata or else a `file:Error`


Reports whether the path is absolute.
A path is absolute if it is independent of the current directory.
On Unix, a path is absolute if it starts with the root.
On Windows, a path is absolute if it has a prefix and starts with the root: c:\windows.
```ballerina
 boolean isAbsolute = check file:isAbsolutePath("/A/B/C");
```



isAbsolutePath

`true` if path is absolute, `false` otherwise, or else an `file:Error`
occurred if the path is invalid


boolean

Joins any number of path elements into a single path.
```ballerina
 string path = check file:joinPath("/", "foo", "bar");
```



joinPath

parts

String value of the file path or else a `file:Error` if the parts are invalid


Normalizes a path value.
```ballerina
 string normalizedPath = check file:normalizePath("foo/../bar", file:CLEAN);
```



normalizePath

Normalization option. Supported options are,
`CLEAN` - Get the shortest path name equivalent to the given path by eliminating multiple separators, '.', and '..',
`SYMLINK` - Evaluate a symlink,
`NORMCASE` - Normalize the case of a pathname. On windows, all the characters are converted to lowercase and "/" is
converted to "\\".


Normalized file path or else a `file:Error` if the path is invalid


Returns the enclosing parent directory.
If the path is empty, parent returns ".".
The returned path does not end in a separator unless it is the root directory.
```ballerina
 string parentPath = check file:parentPath("/A/B/C.txt");
```



parentPath

Path of the parent directory or else a `file:Error`
if an error occurred while getting the parent directory


Reads the directory and returns a list of metadata of files and directories
inside the specified directory.
```ballerina
file:MetaData[] results = check file:readDir("foo/bar");
```



readDir

The `MetaData` array or else a `file:Error` if there is an error


Returns a relative path, which is logically equivalent to the target path when joined to the base path with an
intervening separator.
An error is returned if the target path cannot be made relative to the base path.
```ballerina
 string relative = check file:relativePath("a/b/e", "a/c/d");
```



relativePath

base

target

The target path relative to the base path, or else an
`file:Error` if target path cannot be made relative to the base path


Removes the specified file or directory.
```ballerina
check file:remove("foo/bar.txt");
```



remove

Indicates whether the `remove` should recursively remove all the files inside the given directory


Renames(Moves) the old path with the new path.
If the new path already exists and it is not a directory, this replaces the file.
```ballerina
check file:rename("/A/B/C", "/A/B/D");
```



rename

oldPath

newPath

Splits a list of paths joined by the OS-specific path separator.
```ballerina
 string[] parts = check file:splitPath("/A/B/C");
```



splitPath

String array of the path components or else a `file:Error` if the path is invalid


Tests a file path against a test condition .
```ballerina
boolean result = check file:test("foo/bar.txt", file:EXISTS);
```



test

The option to be tested upon the path. Supported options are,
`EXISTS` - Test whether a file path exists,
`IS_DIR` - Test whether a file path is a directory,
`IS_SYMLINK` - Test whether a file path is a symlink,
`READABLE` - Test whether a file path is readable,
`WRITABLE` - Test whether a file path is writable.


testOption

True/false depending on the option to be tested or else a `file:Error` if there is an error


Represents the directory listener endpoint, which is used to listen to a directory in the local file system.


init

The `ListenerConfig` record with the directory details 


listenerConfig

ListenerConfig

error

Binds a service to the `file:Listener`.



attach

Service

name

() or else error upon failure to attach to the service


'start

() or else error upon failure to start the listener 


gracefulStop

() or else error upon failure to stop the listener 


immediateStop

Stops listening to the directory and detaches the service from the `file:Listener`.



detach

() or else error upon failure to detach to the service


Listener

Represents an event, which will trigger when there is a change to the listening directory.



Triggered event action. This can be create, delete or modify


operation

FileEvent

Represents the configurations that are required for a directory listener.



Recursively monitor all sub folders or not in the given direcotry path


recursive

Metadata record contains metadata information of a file.
This record is returned by getMetaData function.



absPath

size

modifiedTime

readable

writable

MetaData

This module provides APIs, which perform file, file path, and directory operations, and a `Directory Listener`, which is used to listen to a directory in the local file system.


Object type: Service