This is an example page of an actual documentation taken from coro-docs.

# Documentation

Unofficial docs for the module coro-fs version 2.2.4.

coro-fs is a library for filesystem manipulations while keeping the sync style of your code, making use of Lua coroutines.

This library is a great replacement for the Luvit built-in callback styled fs library, since it uses coroutines to keep the sync style of your code, without blocking the main event loop of luv, and most importantly, without the ugly callbacks! It is also somewhat simpler to use than the built-in fs library.

# Errors

All of the functions documented here will return a fail tuple in case of failure, that is, nil, errMsg, hence why all of the first returns have the /nil. The errMsg return is a string that looks something similar to EEXIST: file already exists: foo. Be aware that this only applies to operation failure, meaning, if you for example supply the wrong amount/type of parameters it WILL raise an error.

The first part of the error is the error code, those are defined by libuv and listed up by man7 (each fs method individually). The second part explains what went wrong exactly, and the last part explains what file/directory the error refers to.

# Functions

# mkdir(path[, mode])

Creates a new directory using the provided path.

The owner of the created directory should be the effective user/group ID of said process, or it could inherit the parent directory group-ID. The exact behavior is filesystem dependant.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
path string The path of the directory you want to create ❌
mode number The inode bit mode at which to create said directory. Not implemented on Windows. ✔
Default: 511.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# open(path[, flags[, mode]])

Opens a file, or possibly creates one using the said file path.

The owner of a created file should be the effective user/group ID of said process, or it could inherit the parent directory group-ID. The exact behavior is filesystem dependant.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
path string The path of the file to open/create. ❌
flags string The access mode of the opened file. See TODO for valid values. ✔
Default: "r".
mode number The file’s inode mode to be applied when a file is created. Note that this only applies to future access of the newly created file. ✔
Default: 438.

# Returns

Name Type Description Provided On
descriptor number/nil The file descriptor number of the opened file on success, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

Deletes (unlinks) a file from the filesystem.

This method MUST be run in a coroutine

Param Type Description
path string The path of the file to be deleted/unlinked.
Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# stat(path)

Retrieves information about the file/directory pointed out by path.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The path to the file or directory you want to retrieve information about.

# Returns

Name Type Description Provided On
info table/nil The information about said file/directory on success, see TODO, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# lstat(path)

Identical to stat, except if the path was for a symbolic link, the information will be about the link itself instead of its target.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The path to the file or directory you want to retrieve information about.

# Returns

Name Type Description Provided On
info table/nil The information about said file/directory on success, see TODO, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# fstat(fd)

Identical to stat, except that instead of accepting a path to file/directory, this accepts a file descriptor.

This method MUST be run in a coroutine

# Parameters

Param Type Description
fd number The descriptor of the file you want to retrieve the information about.

# Returns

Name Type Description Provided On
info table/nil The information about said file/directory on success, see TODO, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

Creates a symbolic link (also known as soft link) at path that points up to target.

WARNING: There is currently a bug with this, it was fixed in the latest GH version but not yet published to Lit. TODO: In the next release of coro-fs a new parameter will be added, document it when it is published to Lit.

This method MUST be run in a coroutine

Param Type Description
target string The path of the file you want to link against.
path string The path to where to create the said link at.
Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

Retrieves the target path (the content) of the said symbolic link path.

This method MUST be run in a coroutine

Param Type Description
path string The path to the symbolic link you want to retrieve its content.
Name Type Description Provided On
cont string/nil The target path (the content) of the symlink on success, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# chmod(path, mode)

Changes the inode mode bits (e.g. the permissions) of said file.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string Path to the file you want to manipulate.
mode number Decimal number representing the bit mode.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# fchmod(fd, mode)

Identical to chmod, except that instead of accepting a file path, you use a file descriptor.

This method MUST be run in a coroutine

# Parameters

Param Type Description
fd number The descriptor of the file to manipulate.
mode number Decimal number representing the bit mode.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# read(fd[, length[, offset]])

Reads length bytes of fd file’s contents.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
fd number The descriptor of the file to read from. ❌
length number How many bytes should be read from the file. ✔
Default: 49152.
offset number How many bytes should be sought before start reading. -1 means “Use current file position”. ✔
Default: -1.

# Returns

Name Type Description Provided On
data string/nil The read contents on success, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# write(fd, data[, offset])

Writes data to file using its descriptor fd.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
fd number The descriptor of the file to write data to. ❌
data string The data you want to write to the file as string. ❌
offset number How many bytes should be sought before writing the data. -1 means “Use the current file position”. ✔
Default: -1.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# close(fd)

Closes the opened file fd, so fd don’t refer to anything anymore.

This method MUST be run in a coroutine

# Parameters

Param Type Description
fd number The descriptor of the file to be closed.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# access(path[, mode])

Checks whether the current process have permissions to access the file/directory path.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
path string The path to the file/directory you want to check against. ❌
mode number/string The accessibility check, number to specify the bit permissions mode, string to specify access mode ("R" for read, "W" for write, "X" for execute). ✔
Default: "".

# Returns

Name Type Description Provided On
perm boolean/nil Boolean indicts whether you have permissions to access said file/directory or not on success, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# rename(path, newPath)

Renames a file or a directory to newPath. Can be also used to move a file/directory just by specifying newPath to the target path to move files into.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The path to the file or directory you want to rename/move.
newPath string The new path/name of the renamed/moved file or directory.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# rmdir(path)

Removes and deletes an empty (and only an empty) directory. For recursive remove see rmrf.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The path to the directory you want to delete.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# rmrf(path)

Tries to recursively delete path, while handling most possible scenarios. Most suitable for deleting non-empty directories, or when you just want something to be deleted without having to handle additional exceptions.

  • If the path is a directory its contents will be deleted first then it will be removed.
  • If the path is a file it will be deleted.
  • If the path is a symbolic link it will be unlinked.

WARNING: You cannot undo this!

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The path to the object you want to remove.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# scandir(path)

An iterator that iterates a directory for files and sub-directories.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The directory path to be scanned.

# Returns

Name Type Description Provided On
entry table/nil A table that contains two fields name and type on success, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

TODO: Example.

# readFile(path)

Fully reads a file and returns its contents as a single string.

NOTE: In some rare and system specific cases, only a chunk of the file will be read.

This method MUST be run in a coroutine

# Parameters

Param Type Description
path string The path to the file you want to read.

# Returns

Name Type Description Provided On
data string/nil The contents of the file on success, otherwise nil. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# writeFile(path, data[, mkdir])

Writes data to file path in a one go.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
path string The path to the file you want to write into. ❌
data string The data you want to write into the file as string. ❌
mkdir boolean Whether you want coro-fs to create any missing directories in the provided path or not. ✔️
Default: false.

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# mkdirp(path[, mode])

Recursively creates missing directories in a path with the said bit mode.

For example mkdir("./a/b/c/") this call will create a directory a that contains directory b if they don’t already exists, etc.

This method MUST be run in a coroutine

# Parameters

Param Type Description Optional
path string The path that might contains the missing directories to be created. ❌
mode number Decimal number of the indoe mode bits (e.g. its permissions). ✔️

# Returns

Name Type Description Provided On
success boolean/nil Whether or not said operation have succeeded. Always
err string A string explaining what went wrong when executing said operation. Failure Only

# chroot(base)

TODO: Document this.

This method does not require running in a coroutine