Module file
ballerina/file Ballerina library
Package Overview
This package contains functions to perform file system based operations such as create, delete, rename the file/directory, and retrieve metadata of the file.
For an example on the usage of the operations, see the File Example.
Directory Listener
The Directory Listener is used to listen to a directory in the local file system. It notifies when new files are created in the directory or when the existing files are deleted or modified.
For an example on the usage of the operations, see the Directory Listener Example.
Functions
basename
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.
string|file:Error name = file:basename("/A/B/C.txt");
Parameters
- path string - String value of file path
copy
function copy(string sourcePath, string destinationPath, CopyOption... options) returns Error?Copy the file/directory in the old path to the new path.
file:Error? results = file:copy("/A/B/C", "/A/B/D", true);
Parameters
- sourcePath string - String value of the old file path
- destinationPath string - String value of the new file path
- options CopyOption... - 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.
Return Type
- Error? - An
file:Errorif failed to copy
create
Creates a file in the specified file path. Truncates if the file already exists in the given path.
file:Error? results = file:create("bar.txt");
Parameters
- path string - String value of the file path
Return Type
- Error? - A
file:Errorif file creation failed
createDir
Creates a new directory with the specified name.
file:Error? results = file:createDir("foo/bar");
Parameters
- dir string - Directory name
- option DirOption (default NON_RECURSIVE) - Indicates whether the
createDirshould create non-existing parent directories. The default is only to create the given current directory.
Return Type
- Error? - A
file:Errorif the directory creation failed
createTemp
Creates a temporary file.
string|error tmpFile = file:createTemp();
createTempDir
Creates a temporary directory.
string|error tmpDir = file:createTempDir();
getAbsolutePath
Retrieves the absolute path from the provided location.
string|file:Error absolutePath = file:getAbsolutePath(<@untainted> "test.txt");
Parameters
- path string - String value of the file path free from potential malicious codes
getCurrentDir
function getCurrentDir() returns stringReturns the current working directory.
string dirPath = file:getCurrentDir();
Return Type
- string - Current working directory or else an empty string if the current working directory cannot be determined
getMetaData
Returns the metadata information of the file specified in the file path.
file:MetaData | error result = file:getMetaData("foo/bar.txt");
Parameters
- path string - String value of the file path.
isAbsolutePath
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.
boolean|file:Error isAbsolute = file:isAbsolutePath("/A/B/C");
Parameters
- path string - String value of the file path
joinPath
Joins any number of path elements into a single path.
string|file:Error path = file:joinPath("/", "foo", "bar");
Parameters
- parts string... - String values of the file path parts
normalizePath
function normalizePath(string path, NormOption option) returns string|ErrorNormalizes a path value.
string|file:Error normalizedPath = file:normalizePath("foo/../bar", file:CLEAN);
Parameters
- path string - String value of the file path
- option NormOption - 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 "\".
parentPath
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.
string|file:Error parentPath = file:parentPath("/A/B/C.txt");
Parameters
- path string - String value of the file/directory path
readDir
Reads the directory and returns a list of metadata of files and directories inside the specified directory.
file:MetaData[] | error results = file:readDir("foo/bar");
Parameters
- path string - String value of the directory path.
relativePath
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.
string|file:Error relative = file:relativePath("a/b/e", "a/c/d");
remove
Removes the specified file or directory.
file:Error? results = file:remove("foo/bar.txt");
Parameters
- path string - String value of the file/directory path
- option DirOption (default NON_RECURSIVE) - Indicates whether the
removeshould recursively remove all the files inside the given directory
Return Type
- Error? - An
file:Errorif failed to remove
rename
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.
file:Error? results = file:rename("/A/B/C", "/A/B/D");
Parameters
- oldPath string - String value of the old file path
- newPath string - String value of the new file path
Return Type
- Error? - An
file:Errorif failed to rename
splitPath
Splits a list of paths joined by the OS-specific path separator.
string[]|file:Error parts = file:splitPath("/A/B/C");
Parameters
- path string - String value of the file path
test
function test(string path, TestOption testOption) returns boolean|ErrorTests a file path against a test condition .
boolean|error result = file:test("foo/bar.txt", file:EXISTS);
Parameters
- path string - String value of the file path
- testOption TestOption - 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.
Enums
file: CopyOption
Represents options that can be used when copying files/directories
Members
file: DirOption
Represents options that can be used when creating or removing directories.
Members
file: NormOption
Represents the options that can be passed to normalizePath function.
Members
file: TestOption
Represents the options that can be passed to test function.
Members
Listeners
file: Listener
Represents the directory listener endpoint, which is used to listen to a directory in the local file system.
Constructor
Creates a new Directory listener.
init (ListenerConfig listenerConfig)- listenerConfig ListenerConfig - The
ListenerConfigrecord with the directory details
attach
Binds a service to the file:Listener.
Parameters
- s service object {} - Type descriptor of the service
Return Type
- error? - () or else error upon failure to attach to the service
'start
function 'start() returns error?Starts the file:Listener.
Return Type
- error? - () or else error upon failure to start the listener
gracefulStop
function gracefulStop() returns error?Stops the file:Listener gracefully.
Return Type
- error? - () or else error upon failure to stop the listener
immediateStop
function immediateStop() returns error?Stops the file:Listener forcefully.
Return Type
- error? - () or else error upon failure to stop the listener
detach
function detach(service object {} s) returns error?Stops listening to the directory and detaches the service from the file:Listener.
Parameters
- s service object {} - Type descriptor of the service
Return Type
- error? - () or else error upon failure to detach to the service
Records
file: FileEvent
Represents an event which will trigger when there is a changes to listining direcotry.
Fields
- name string - Absolute file URI for triggerd event
- operation string - Triggered event action. This can be create, delete or modify
file: ListenerConfig
Represents configurations that required for directory listener.
Fields
- path string - Directory path which need to listen
- recursive boolean(default false) - Recursively monitor all sub folders or not in the given direcotry path
file: MetaData
Metadata record contains metadata information of a file. This record is returned by getMetaData function.
Fields
- absPath string - Absolute path of the file
- size int - Size of the file (in bytes)
- modifiedTime Utc - The last modified time of the file
- dir boolean - Whether the file is a directory or not
- readable boolean - Whether the file is readable or not
- writable boolean - Whether the file is writable or not
Errors
file: Error
Represents file system related errors.