Filesystem, Path, and Environment API

File System Operations

readFile

Read entire file contents as UTF-8 string Throws if file doesn't exist, isn't readable, or isn't valid UTF-8. For binary files, this will fail. For large files, consider memory usage.

readFile(path: string): Promise<string>

Parameters:

writeFile

Write string content to a NEW file (fails if file exists) Creates a new file with the given content. Fails if the file already exists to prevent plugins from accidentally overwriting user data.

writeFile(path: string, content: string): Promise<void>

Parameters:

fileExists

Check if a path exists (file, directory, or symlink) Does not follow symlinks; returns true for broken symlinks. Use fileStat for more detailed information.

fileExists(path: string): boolean

Parameters:

fileStat

Get metadata about a file or directory Follows symlinks. Returns exists=false for non-existent paths rather than throwing. Size is in bytes; directories may report 0.

fileStat(path: string): FileStat

Parameters:

readDir

List directory contents Returns unsorted entries with type info. Entry names are relative to the directory (use pathJoin to construct full paths). Throws on permission errors or if path is not a directory.

readDir(path: string): DirEntry[]

Parameters:

Example:

const entries = editor.readDir("/home/user");
for (const e of entries) {
const fullPath = editor.pathJoin("/home/user", e.name);
}

Environment Operations

getEnv

Get an environment variable

getEnv(name: string): string

Parameters:

getCwd

Returns the editor's working directory set at startup. Use as base for resolving relative paths.

getCwd(): string

Path Operations

pathJoin

Join path segments using the OS path separator Handles empty segments and normalizes separators. If a segment is absolute, previous segments are discarded.

pathJoin(parts: string[]): string

Parameters:

Example:

pathJoin("/home", "user", "file.txt") // "/home/user/file.txt"
pathJoin("relative", "/absolute") // "/absolute"

pathDirname

Get the parent directory of a path Returns empty string for root paths or paths without parent. Does not resolve symlinks or check existence.

pathDirname(path: string): string

Parameters:

Example:

pathDirname("/home/user/file.txt") // "/home/user"
pathDirname("/") // ""

pathBasename

Get the final component of a path Returns empty string for root paths. Does not strip file extension; use pathExtname for that.

pathBasename(path: string): string

Parameters:

Example:

pathBasename("/home/user/file.txt") // "file.txt"
pathBasename("/home/user/") // "user"

pathExtname

Get the file extension including the dot Returns empty string if no extension. Only returns the last extension for files like "archive.tar.gz" (returns ".gz").

pathExtname(path: string): string

Parameters:

Example:

pathExtname("file.txt") // ".txt"
pathExtname("archive.tar.gz") // ".gz"
pathExtname("Makefile") // ""

pathIsAbsolute

Check if a path is absolute On Unix: starts with "/". On Windows: starts with drive letter or UNC path.

pathIsAbsolute(path: string): boolean

Parameters:

Event/Hook Operations