Files

ceramic.Files (Class)

Cross-platform filesystem utilities for Ceramic.

This class provides a uniform API for file system operations across different targets including native (sys), Node.js, and Electron. Methods automatically detect the runtime environment and use the appropriate implementation.

Most methods will log a warning if called on unsupported platforms rather than throwing exceptions, allowing code to be written once and deployed across platforms.

Supported platforms vary by method:

  • Native (sys): Full support for all operations
  • Node.js: Full support when running in Node environment
  • Web + Electron: Support through Electron's Node.js integration
  • Other web targets: No filesystem access (methods return defaults)

Static Members

haveSameContent(filePath1: String, filePath2: String): Bool

Compares the content of two files for equality.

Name Type Description
filePath1 String Path to the first file
filePath2 String Path to the second file
Returns Description
Bool True if both files exist and have identical content, false otherwise

haveSameLastModified(filePath1: String, filePath2: String): Bool

Checks if two files have the same last modified timestamp.

Useful for synchronization and caching operations where timestamp comparison is more efficient than content comparison.

Name Type Description
filePath1 String Path to the first file
filePath2 String Path to the second file
Returns Description
Bool True if both files exist and have the same modification time

setToSameLastModified(srcFilePath: String, dstFilePath: String): Void

Copies the last modified timestamp from source file to destination file.

This is useful for maintaining timestamp consistency when copying files or for cache validation purposes.

@note Currently only supported in Node.js environments

Name Type Description
srcFilePath String Source file to read timestamp from
dstFilePath String Destination file to apply timestamp to

getFlatDirectory(dir: String, ?excludeSystemFiles: Bool = true, ?subCall: Bool = false, ?recursive: Bool = true): Array<String>

Recursively lists all files in a directory tree.

Returns a flat array of file paths relative to the input directory. Directories themselves are not included in the result, only files.

Example:

var files = Files.getFlatDirectory("assets/images");
// Returns: ["icon.png", "sprites/player.png", "sprites/enemy.png"]
Name Type Default Description
dir String Root directory to scan
excludeSystemFiles Bool true Whether to exclude system files like .DS_Store (default: true)
subCall Bool false Internal parameter for recursion (do not use)
recursive Bool true Whether to scan subdirectories (default: true)
Returns Description
Array<String> Array of relative file paths

getLastModified(path: String): Float

Gets the last modified time of a file.

Name Type Description
path String Path to the file
Returns Description
Float Last modified time in seconds since Unix epoch, or -1 if unavailable

removeEmptyDirectories(dir: String, ?excludeSystemFiles: Bool = true): Void

Recursively removes all empty directories within a directory tree.

This method traverses the directory tree depth-first and removes any directories that contain no files (optionally ignoring system files).

Name Type Default Description
dir String Root directory to clean
excludeSystemFiles Bool true Whether to ignore .DS_Store when checking if empty

isEmptyDirectory(dir: String, ?excludeSystemFiles: Bool = true): Bool

Checks if a directory is empty.

Name Type Default Description
dir String Directory path to check
excludeSystemFiles Bool true Whether to ignore .DS_Store files
Returns Description
Bool True if the directory contains no files or subdirectories

deleteRecursive(toDelete: String): Void

Recursively deletes a file or directory and all its contents.

This is equivalent to rm -rf on Unix systems. Use with caution as deleted files cannot be recovered.

Name Type Description
toDelete String Path to file or directory to delete

getRelativePath(absolutePath: String, relativeTo: String): String

Calculates the relative path from one location to another.

Example:

var rel = Files.getRelativePath("/home/user/project/src/Main.hx", "/home/user/project");
// Returns: "./src/Main.hx"
Name Type Description
absolutePath String The target absolute path
relativeTo String The base path to calculate relative from
Returns Description
String The relative path from relativeTo to absolutePath

copyFileWithIntermediateDirs(srcPath: String, dstPath: String): Void

Copies a file, creating any necessary parent directories.

If the destination directory doesn't exist, it will be created automatically before copying the file.

Name Type Description
srcPath String Source file path
dstPath String Destination file path

copyDirectory(srcDir: String, dstDir: String, ?removeExisting: Bool = false): Void

Recursively copies a directory and all its contents.

Name Type Default Description
srcDir String Source directory to copy from
dstDir String Destination directory to copy to
removeExisting Bool false If true, removes existing destination before copying

deleteFile(path: String): Void

Deletes a single file.

Name Type Description
path String Path to the file to delete

getContent(path: String): Null<String>

Reads the entire content of a text file as a string.

Name Type Description
path String Path to the file to read
Returns Description
Null<String> The file content as a string, or null if unavailable

getBytes(path: String): Null<haxe.io.Bytes>

Reads the entire content of a file as binary data.

Name Type Description
path String Path to the file to read
Returns Description
Null<haxe.io.Bytes> The file content as bytes, or null if unavailable

saveContent(path: String, content: String): Void

Writes a string to a file, replacing any existing content.

Name Type Description
path String Path to the file to write
content String Text content to write to the file

saveBytes(path: String, bytes: haxe.io.Bytes): Void

Writes binary data to a file, replacing any existing content.

Name Type Description
path String Path to the file to write
bytes haxe.io.Bytes Binary data to write to the file

createDirectory(path: String): Void

Creates a directory, including any necessary parent directories.

This method creates the full directory path if it doesn't exist, similar to mkdir -p on Unix systems.

Name Type Description
path String Directory path to create

exists(path: String): Bool

Checks if a file or directory exists.

Name Type Description
path String Path to check
Returns Description
Bool True if the path exists (file or directory), false otherwise

isDirectory(path: String): Bool

Checks if a path points to a directory.

Name Type Description
path String Path to check
Returns Description
Bool True if the path exists and is a directory, false otherwise