Skip to Content
Skip to Content
API Referencefs

File System

zune.fs

A library that provides access to the file system.

Functions

createFile

Creates a file. If the file already exists, the function will throw an error only when exclusive is true.

createFile(path: string, opts: export type FileCreateOptions = {
    exclusive: boolean?,
    truncate: boolean?, 
}FileCreateOptionsexport type FileCreateOptions = {
    exclusive: boolean?,
    truncate: boolean?, 
}?): FileHandle

Parameters

  • path: string - The path to the file to open/create.
  • opts: FileCreateOptions? - The create options.
    • exclusive: boolean? - If true, the function will fail if the file already exists.
      • default: false
    • truncate: boolean? - If true, the file will be truncated if it already exists.
      • default: true

Throws

  • IO Error

openFile

Opens a file. If the file does not exists, the function will throw an error.

openFile(path: string, opts: export type FileOpenOptions = {
    mode: string?, 
}FileOpenOptionsexport type FileOpenOptions = {
    mode: string?, 
}?): FileHandle

Parameters

  • path: string - The path to the file to open.
  • opts: FileOpenOptions? - The open options.
    • mode: string? - If provided, the file will be opened in the specified mode.
      • modes: "r" | "w" | "rw"
      • default: "rw"

Throws

  • IO Error

readFile

Read the contents of a file from the provided path.

readFile(path: string): string
readFile(path: string, bytes: false?): string
readFile(path: string, bytes: true): buffer
readFile(path: string, bytes: boolean): string | buffer

Parameters

  • path: string - The path to the file to read.
  • bytes: false? | true | boolean? - If true, returns a buffer instead of a string.
    • default: false

Throws

  • IO Error

readFileSync

Read the contents of a file from the provided path synchronously.

readFileSync(path: string): string
readFileSync(path: string, bytes: false?): string
readFileSync(path: string, bytes: true): buffer
readFileSync(path: string, bytes: boolean): string | buffer

Parameters

  • path: string - The path to the file to read.
  • bytes: false? | true | boolean? - If true, returns a buffer instead of a string.
    • default: false

Throws

  • IO Error

entries

Get directory entries from the provided path.

entries(path: string): {export type MetadataKind = 
    | "file"
    | "directory"
    | "sym_link"
    | "door"
    | "character_device"
    | "unix_domain_socket"
    | "block_device"
    | "event_port"
    | "named_pipe"
    | "whiteout"
    | "unknown"
 
type DirectoryEntry = {
    name: string,
    kind: MetadataKind, 
}DirectoryEntryexport type MetadataKind = 
    | "file"
    | "directory"
    | "sym_link"
    | "door"
    | "character_device"
    | "unix_domain_socket"
    | "block_device"
    | "event_port"
    | "named_pipe"
    | "whiteout"
    | "unknown"
 
type DirectoryEntry = {
    name: string,
    kind: MetadataKind, 
}}

Parameters

  • path: string - The path to the directory to read.

Throws

  • IO Error

writeFile

Write the contents to a file at the provided path.

writeFile(path: string, contents: string | buffer): ()

Parameters

  • path: string - The path to the file to write.
  • contents: string | buffer - The contents to write to the file. (This may be limited to the max luau string).

Throws

  • IO Error

writeFileSync

Write the contents to a file at the provided path synchronously.

writeFileSync(path: string, contents: string | buffer): ()

Parameters

  • path: string - The path to the file to write.
  • contents: string | buffer - The contents to write to the file. (This may be limited to the max luau string).

Throws

  • IO Error

makeDir

Creates a directory at the provided path.

makeDir(path: string, recursive: boolean?): ()

Parameters

  • path: string - The path to the directory to create.
  • recursive: boolean? - If true, the function will create all parent directories if they do not
    • default: false

Throws

  • IO Error

deleteFile

Removes a file at the provided path.

deleteFile(path: string): ()

Parameters

  • path: string - The path to the file to remove.

Throws

  • IO Error

deleteDir

Removes a directory at the provided path.

deleteDir(path: string, recursive: boolean?): ()

Parameters

  • path: string - The path to the directory to remove.
  • recursive: boolean? - If true, the function will remove all files and directories inside the directory.
    • default: false

Throws

  • IO Error

metadata

Get metadata of a file or directory at the provided path.

metadata(path: string): export type MetadataKind = 
    | "file"
    | "directory"
    | "sym_link"
    | "door"
    | "character_device"
    | "unix_domain_socket"
    | "block_device"
    | "event_port"
    | "named_pipe"
    | "whiteout"
    | "unknown"
 
export type Metadata = {
    kind: MetadataKind,
    symlink: boolean,
    created_at: number,
    modified_at: number,
    accessed_at: number,
    size: number,
    permissions: {
        read_only: boolean, 
    }, 
}Metadataexport type MetadataKind = 
    | "file"
    | "directory"
    | "sym_link"
    | "door"
    | "character_device"
    | "unix_domain_socket"
    | "block_device"
    | "event_port"
    | "named_pipe"
    | "whiteout"
    | "unknown"
 
export type Metadata = {
    kind: MetadataKind,
    symlink: boolean,
    created_at: number,
    modified_at: number,
    accessed_at: number,
    size: number,
    permissions: {
        read_only: boolean, 
    }, 
}

Parameters

  • path: string - The path to the file or directory to get metadata from.

Throws

  • IO Error

stat

Get stats of the provided path. This should not error, as if a path does not exist, it will always return a FileStat with kind set to "none".

stat(path: string): export type MetadataKind = 
    | "file"
    | "directory"
    | "sym_link"
    | "door"
    | "character_device"
    | "unix_domain_socket"
    | "block_device"
    | "event_port"
    | "named_pipe"
    | "whiteout"
    | "unknown"
 
export type FileStat = {
    kind: MetadataKind,
    changed_at: number,
    modified_at: number,
    accessed_at: number,
    size: number,
    mode: number, 
} | {
    kind: "none", 
}FileStatexport type MetadataKind = 
    | "file"
    | "directory"
    | "sym_link"
    | "door"
    | "character_device"
    | "unix_domain_socket"
    | "block_device"
    | "event_port"
    | "named_pipe"
    | "whiteout"
    | "unknown"
 
export type FileStat = {
    kind: MetadataKind,
    changed_at: number,
    modified_at: number,
    accessed_at: number,
    size: number,
    mode: number, 
} | {
    kind: "none", 
}

Parameters

  • path: string - The path to the file or directory to get stats from.

move

Moves a file or directory from one path to another path.

move(from: string, to: string, overwrite: boolean?): ()

Parameters

  • from: string - The path to the file or directory to move.
  • to: string - The path to move the file or directory to.
  • overwrite: boolean? - If true, the function will overwrite the file if to exists.
    • default: false

Throws

  • IO Error

copy

Copies a file or directory from one path to another path.

copy(from: string, to: string, overwrite: boolean?): ()

Parameters

  • from: string - The path to the file or directory to copy.
  • to: string - The path to copy the file or directory to.
  • overwrite: boolean? - If true, the function will overwrite the file if it exists.
    • default: false

Throws

  • IO Error

Create a symbolic link from one path to another path.

symlink(from: string, to: string): ()
Windows: must have developer mode enabled

Parameters

  • from: string - The path to the file or directory to link.
  • to: string - The path to link the file or directory to.

Throws

  • IO Error
  • Not Supported (Windows)

getExePath

Get the path to the current executable.

getExePath(): string

Throws

  • IO Error

realPath

Get absolute path to the file or directory.

realPath(path: string): string

Parameters

  • path: string - The path to resolve.

watch

Watches a directory for changes.

Does not watch subdirectories. Windows: Can watch changes in first child subdirectories.

watch(path: string, callback: (path: string, events: {type WatchEvent = "created" | "modified" | "moved" | "renamed" | "deleted" | "metadata"WatchEventtype WatchEvent = "created" | "modified" | "moved" | "renamed" | "deleted" | "metadata"}) -> ()): FileWatcher

Parameters

  • path: string - The path to the directory to watch.
  • callback: (path: string, events: {WatchEvent}) -> () - The function to call when a change is detected.

Throws

  • IO Error

embedFile

When called from a bundled context, this would get and load the contents of the embedded file. Otherwise would synchronously read a file relative to the calling script.

embedFile(path: string): buffer

Parameters

  • path: string - The file path relative to calling script.

Throws

  • IO Error

embeddedFiles

Will return the list of all embedded files, the table will always be empty when called from an unbundled context.

embeddedFiles(): {string}

Throws

  • Memory Error

embeddedScripts

Will return the list of all embedded scripts, the table will always be empty when called from an unbundled context.

embeddedScripts(): {string}

Throws

  • Memory Error

Namespaces

path

FUNCTIONS

join

Joins multiple paths into a single path with OS specific separator.

  • (lib, main.luau) -> lib/main.luau
  • (lib, lib/main.luau) -> lib/lib/main.luau
path.join(...string): string

Parameters

  • ...string - The paths to join. if no arguments are provided, the result will be nil.

relative

Gets the relative path from one path to another.

  • (lib, lib/main.luau) -> main.luau
  • (lib, main.luau) -> ../main.luau
path.relative(from: string, to: string): string

Parameters

  • from: string - The path to resolve from.
  • to: string - The path to resolve to.

resolve

Resolves relatives and parent paths combined.

  • (lib, main.luau) -> lib/main.luau
  • (lib, ../main.luau) -> main.luau
path.resolve(...string): string

Parameters

  • ...string - The paths to resolve.

dirname

Returns the directory name of the provided path, will return nil if there are no more directories.

  • lib/main.luau -> lib
  • lib -> nil
path.dirname(path: string): string?

Parameters

  • path: string - The path to get the directory name from.

basename

Returns the base name of the provided path.

  • /lib/main.test.luau -> main.test.luau
  • /lib/main.luau -> main.luau
path.basename(path: string): string

Parameters

  • path: string - The path to get the base name from.

stem

Returns the name of file without extension of the provided path.

  • /lib/main.test.luau -> main.test
  • /lib/main.luau -> main
path.stem(path: string): string

Parameters

  • path: string - The path to get the stem from.

extension

Returns the extension of the provided path.

  • /lib/main.test.luau -> .luau
  • /lib/main.luau -> .luau
  • /lib/main. -> .
  • /lib/main -> “
path.extension(path: string): string

Parameters

  • path: string - The path to get the extension from.

isAbsolute

Checks if the provided path is an absolute path based on OS.

path.isAbsolute(path: string): boolean

Parameters

  • path: string - The path to check if it is absolute.

globMatch

Checks if the provided path matches the glob pattern.

path.globMatch(path: string, pattern: string): boolean

Parameters

  • path: string - The path to check.
  • pattern: string - The glob pattern to match against.
Last updated on
<globals>process