File System

Read, write, and manage files across SAF and local storage

Klyx provides a unified file system API. The KxFile class is a pure data model representing a file or directory, while the FileSystem service provides all I/O operations through URI-based methods. This design abstracts over Android’s Storage Access Framework (SAF) and local file system access.

KxFile

KxFile is a data class that wraps a URI and provides file metadata. It does not perform I/O directly — use the FileSystem service for read/write operations.

@Serializable
@Immutable
class KxFile(
    uri: Uri,
    name: String,
    isDirectory: Boolean = false,
    size: Long = 0L,
    lastModified: Long = 0L
)

Creating KxFile instances

// From a URI
val file: KxFile = fileSystem.wrapUri(uri)

// From existing types
val kxFile: KxFile = File("/path/to/file").wrap()
val kxFile: KxFile = uri.wrap()
val kxFile: KxFile = KxFile(uri)

KxFile properties

file.name          // "myfile.txt"
file.uri           // Uri
file.extension     // "txt" (without dot, empty string if none)
file.isDirectory   // true/false
file.size          // Size in bytes
file.lastModified  // Timestamp in milliseconds since epoch
file.isHidden      // true if name starts with '.'
file.parent        // KxFile? -- parent directory, or null if at root
file.providerKey   // Extension if non-empty, otherwise lowercased name (used for LSP matching)

FileSystem service

The FileSystem service provides all file operations. Access it with:

private val fileSystem: FileSystem by plugin()

Listing and navigating

// List directory contents
val files: List<KxFile> = fileSystem.list(directoryUri)

// Check if a path exists
val exists: Boolean = fileSystem.exists(uri)

// Resolve a display name
val name: String = fileSystem.resolveName(file)

Reading files

// Open an InputStream for reading
val input: InputStream = fileSystem.inputStream(file.uri)

// Read a specific byte range
val buffer = ByteArray(1024)
val bytesRead: Int = fileSystem.readRange(file.uri, position = 0, buffer, offset = 0, length = 1024)

Writing files

// Open an OutputStream for writing
val output: OutputStream = fileSystem.outputStream(file.uri, mode = "w")

// Modes: "r" (read), "w" (write/truncate), "wt" (write text), "wa" (append), "rw" (read/write), "rwt" (read/write text)

File operations

// Delete a file or directory
val deleted: Boolean = fileSystem.delete(file.uri)

// Rename a file
val newUri: Uri? = fileSystem.rename(file.uri, "newname.txt")

// Create a new file
val newFileUri: Uri? = fileSystem.createFile(parentDirUri, "newfile.txt", "text/plain")

// Create a new directory
val newDirUri: Uri? = fileSystem.createDirectory(parentDirUri, "newdir")

// Copy a file
val copyUri: Uri? = fileSystem.copy(sourceUri, targetParentUri)

// Move a file
val movedUri: Uri? = fileSystem.move(sourceUri, sourceParentUri, targetParentUri)

File metadata

// File capabilities (what operations are supported)
val caps: FileCapabilities = fileSystem.capabilities(file.uri)
caps.canWrite    // true/false
caps.canDelete   // true/false
caps.canRename   // true/false
caps.canCreate   // true/false

// Detailed file statistics (Unix-like)
val stat: FileStatInfo? = fileSystem.stat(file.uri)
stat.mode            // Raw file mode
stat.permissions     // "rw-r--r--"
stat.ownerUid        // Numeric UID
stat.ownerName       // Username
stat.groupName       // Group name
stat.hardLinks       // Hard link count
stat.inode           // Inode number
stat.deviceId        // Device ID
stat.blockSize       // Block size
stat.blocksAllocated // Blocks allocated (512B each)
stat.lastAccessed    // atime
stat.lastModified    // mtime
stat.lastChanged     // ctime

// File type detection
val category: FileCategory = fileSystem.determineFileCategory(file.uri)

// MIME type
val mime: String? = fileSystem.mimeType(file.uri)

// File name from URI
val name: String? = fileSystem.fileName(file.uri)

Symbolic links

val isSymlink: Boolean = fileSystem.isSymlink(file.uri)
val target: String? = fileSystem.symlinkTarget(file.uri)

Protected paths

val isProtected: Boolean = fileSystem.isProtectedPath(file.uri)

Directory size calculation

// Returns a Flow that emits progress updates
fileSystem.calculateSize(dirUri).collect { progress ->
    progress.bytes       // Total bytes so far
    progress.fileCount    // Files counted
    progress.dirCount    // Directories counted
    progress.isFinished   // True when complete
}

FileCategory

An enum describing how a file should be handled:

Value	Description
TEXT	Text file, can be opened in the editor
IMAGE	Image file, can be displayed
BINARY_UNSUPPORTED	Binary file not currently supported
ERROR	An error occurred determining the category

FileCapabilities

A data class describing allowed operations:

data class FileCapabilities(
    val canWrite: Boolean,
    val canDelete: Boolean,
    val canRename: Boolean,
    val canCreate: Boolean
)

FileStatInfo

A data class with detailed Unix-like file statistics:

data class FileStatInfo(
    val mode: Int,
    val permissions: String,
    val ownerUid: Int,
    val ownerName: String,
    val groupGid: Int,
    val groupName: String,
    val hardLinks: Long,
    val inode: Long,
    val deviceId: Long,
    val blockSize: Long,
    val blocksAllocated: Long,
    val lastAccessed: Long,
    val lastModified: Long,
    val lastChanged: Long
)

Paths utility

Paths is an object providing common Android and Klyx-specific directory paths:

Paths.filesDir           // Internal files directory
Paths.dataDir            // Application data directory
Paths.tempDir            // Cache directory (for temp files)
Paths.externalFilesDir   // External storage files directory
Paths.nativeLibraryDir   // Native libraries directory
Paths.externalCacheDir   // External cache directory (nullable)
Paths.noBackupFilesDir   // No-backup files directory
Paths.codeCacheDir       // Code cache directory
Paths.externalCacheDirs  // All external cache directories
Paths.externalFilesDirs  // All external files directories

Klyx-specific path extensions

Paths.pluginsDir            // dataDir/klyx/plugins -- installed plugins directory
Paths.installedPluginsJson  // pluginsDir/installed.json -- list of installed plugin IDs
Paths.rootFs                // dataDir/rootfs -- terminal root filesystem
Paths.home                  // filesDir/home -- terminal home directory
Paths.projects              // home/projects -- user projects directory
Paths.versionFile           // rootFs/.bootstrap-version -- bootstrap version file

Terminal native libraries

prootFile()         // File path to the PRoot executable
prootLoaderFile()   // File path to the PRoot loader library

File search

// Search for files matching a query string
fileSystem.search(roots = listOf(projectUri), query = "MainActivity").collect { match ->
    // match is a KxFile
}

File utility functions

// Check if a file is likely text (by inspecting content, not just extension)
val isText: Boolean = isTextFile(uri, contentResolver)

// Format a byte size as human-readable string
1_500_000L.humanBytes()  // "1.5 MB"
1024.humanBytes()        // "1.0 KB"

// Create a directory if it does not exist
val file = File("/path/to/dir")
file.createDirIfMissing()  // Boolean

Example

A file system demo screen demonstrates:

• Listing directory contents and showing file properties
• Determining file categories with determineFileCategory
• Checking file capabilities with capabilities
• Formatting file sizes with humanBytes()
• Searching files with search
• Accessing Paths directories and terminal paths