> ## Documentation Index
> Fetch the complete documentation index at: https://klyx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File System

Klyx provides a unified file system API that abstracts over Android's Storage Access Framework (SAF) and local file system access.

## KxFile

`KxFile` wraps both `DocumentFile` (SAF) and `java.io.File`, providing a unified interface.

### Creating KxFile instances

```kotlin theme={null}
// From a path
val file = KxFile("/data/data/com.klyx/files/myfile.txt")

// From a URI
val file = KxFile(Uri.parse("content://..."))

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

### Reading files

```kotlin theme={null}
val bytes: ByteArray = file.readBytes()
val text: String = file.readText()
val lines: List<String> = file.readLines()
val input: InputStream = file.inputStream()
```

### Writing files

```kotlin theme={null}
file.writeBytes(byteArrayOf(1, 2, 3))
file.writeText("Hello, world!")
file.outputStream().use { it.write(data) }
```

### File properties

```kotlin theme={null}
file.name          // "myfile.txt"
file.absolutePath  // Full path
file.extension     // "txt"
file.mimeType      // "text/plain"
file.exists        // true/false
file.isDirectory   // true/false
file.isFile        // true/false
file.length        // Size in bytes
file.lastModified  // Timestamp
file.canRead       // true/false
file.canWrite      // true/false
```

### Directory operations

```kotlin theme={null}
file.list()                       // Array<String>?
file.listFiles()                  // Array<KxFile>?
file.listFiles(filter) { it.isFile }
file.mkdirs()                     // Boolean
```

### Delete and rename

```kotlin theme={null}
file.delete()                     // Boolean
file.deleteRecursively()          // Boolean
file.renameTo(newFile)            // Boolean
```

## FileSystem service

The `FileSystem` service provides additional file operations with URI-based access.

```kotlin theme={null}
private val fileSystem: FileSystem by plugin()
```

| Function                                   | Returns            | Description                             |
| ------------------------------------------ | ------------------ | --------------------------------------- |
| `list(uri)`                                | `List<KxFile>`     | List directory contents                 |
| `inputStream(uri)`                         | `InputStream`      | Open for reading                        |
| `outputStream(uri, mode)`                  | `OutputStream`     | Open for writing                        |
| `delete(uri)`                              | `Boolean`          | Delete file or directory                |
| `rename(uri, newName)`                     | `Boolean`          | Rename file                             |
| `createFile(parent, name, mime)`           | `KxFile?`          | Create new file                         |
| `createDirectory(parent, name)`            | `KxFile?`          | Create new directory                    |
| `exists(uri)`                              | `Boolean`          | Check existence                         |
| `copy(source, targetParent)`               | `Boolean`          | Copy file                               |
| `move(source, sourceParent, targetParent)` | `Boolean`          | Move file                               |
| `capabilities(uri)`                        | `FileCapabilities` | Check what operations are supported     |
| `fileName(uri)`                            | `String`           | Extract file name from URI              |
| `determineFileCategory(uri)`               | `FileCategory`     | TEXT, IMAGE, BINARY\_UNSUPPORTED, ERROR |
| `mimeType(uri)`                            | `String`           | Resolve MIME type                       |
| `search(roots, query)`                     | `Flow<KxFile>`     | Search files with a query               |

### FileCapabilities

```kotlin theme={null}
data class FileCapabilities(
    val canWrite: Boolean,
    val canDelete: Boolean,
    val canRename: Boolean,
    val canCreate: Boolean
)
```

## Paths utility

`Paths` provides common directory paths:

```kotlin theme={null}
Paths.filesDir
Paths.dataDir
Paths.tempDir
Paths.externalFilesDir
Paths.nativeLibraryDir
Paths.pluginsDir         // dataDir/klyx/plugins
Paths.installedPluginsJson // pluginsDir/installed.json
```

## File category detection

```kotlin theme={null}
val category = fileSystem.determineFileCategory(uri)
when (category) {
    FileCategory.TEXT -> // Open in editor
    FileCategory.IMAGE -> // Show image viewer
    FileCategory.BINARY_UNSUPPORTED -> // Show error
    FileCategory.ERROR -> // Handle error
}
```