# fs Module - File System Operations

The fs module provides a unified interface for file system operations across different platforms.

## File Operations

### fs.readFile(path)

Read entire file content as string.

- **Parameters**: `path` (string) - File path
- **Returns**: File content (string) or nil if error

```lua
local content = fs.readFile("config.txt")
```

### fs.writeFile(path, data)

Write data to file (creates/overwrites).

- **Parameters**: `path` (string), `data` (string)
- **Returns**: Full path of written file or nil if error

```lua
local result = fs.writeFile("output.txt", "Hello World")
```

### fs.appendFile(path, data)

Append data to end of file.

- **Parameters**: `path` (string), `data` (string)
- **Returns**: Full path or nil if error

```lua
fs.appendFile("log.txt", "New entry\n")
```

### fs.prependFile(path, data)

Prepend data to beginning of file.

- **Parameters**: `path` (string), `data` (string)
- **Returns**: Full path or nil if error

```lua
fs.prependFile("file.txt", "Header: ")
```

### fs.copyFile(sourcePath, destPath)

Copy file from source to destination.

- **Parameters**: `sourcePath` (string), `destPath` (string)
- **Returns**: true on success

```lua
fs.copyFile("src.txt", "backup/src.txt")
```

### fs.move(sourcePath, destPath)

Move/rename file.

- **Parameters**: `sourcePath` (string), `destPath` (string)
- **Returns**: true on success

```lua
fs.move("old.txt", "new.txt")
```

### fs.deleteFile(path)

Delete file.

- **Parameters**: `path` (string)
- **Returns**: true on success

```lua
fs.deleteFile("temp.txt")
```

## File Information

### fs.fileExists(path)

Check if file exists.

- **Parameters**: `path` (string)
- **Returns**: Full path if exists, false otherwise

```lua
if fs.fileExists("data.txt") then
    -- process file
end
```

### fs.fileSize(path)

Get file size in bytes.

- **Parameters**: `path` (string)
- **Returns**: Size (number) or nil if error

```lua
local size = fs.fileSize("large-file.dat")
```

### fs.fileModification(path)

Get file modification timestamp.

- **Parameters**: `path` (string)
- **Returns**: Timestamp (number) or nil if error

```lua
local modTime = fs.fileModification("document.pdf")
```

### fs.attributes(path)

Get detailed file attributes.

- **Parameters**: `path` (string)
- **Returns**: Table with attributes or nil

```lua
local attr = fs.attributes("file.txt")
print(attr.mode, attr.size)
```

## Directory Operations

### fs.createFilePath(path)

Create directory structure (like mkdir -p).

- **Parameters**: `path` (string)
- **Returns**: Created path or nil if error

```lua
fs.createFilePath("data/2024/reports/")
```

### fs.currentPath()

Get current working directory.

- **Returns**: Current directory path

```lua
local cwd = fs.currentPath()
```

### fs.dirTreeIter(path, options)

Iterate through directory tree.

- **Parameters**: `path` (string), `options` (table, optional)
- **Options**: `suffix`, `directory`, `recursive`
- **Returns**: Iterator yielding filename, attributes

```lua
for file, attr in fs.dirTreeIter("/path", {suffix=".lua"}) do
    print(file)
end
```

## Path Utilities

### fs.filePath(path)

Extract directory path from filename.

- **Parameters**: `path` (string)
- **Returns**: Directory path with trailing "/" or nil

```lua
local dir = fs.filePath("dir/subdir/file.txt") -- "dir/subdir/"
```

### fs.upperPath(path)

Get parent directory path.

- **Parameters**: `path` (string)
- **Returns**: Parent directory path

```lua
local parent = fs.upperPath("dir/file.txt") -- "dir/"
```

### fs.fixSaveFileName(filename)

Sanitize filename for saving.

- **Parameters**: `filename` (string)
- **Returns**: Safe filename string

```lua
local safe = fs.fixSaveFileName("file:name?.txt")
```

## JSON Operations

### fs.readJsonFile(path)

Read and parse JSON file.

- **Parameters**: `path` (string)
- **Returns**: Parsed data (table) or nil if error

```lua
local data = fs.readJsonFile("config.json")
```

### fs.writeFile(path, table)

Write table as JSON file.

- **Parameters**: `path` (string), data (table)
- **Returns**: Full path or nil if error

```lua
fs.writeFile("data.json", {key = "value"})
```

## Special Operations

### fs.touch(path)

Update file modification time (creates if not exists).

- **Parameters**: `path` (string)
- **Returns**: true on success

```lua
fs.touch("timestamp.txt")
```

### fs.lastReadFilePath()

Get path of last file read via fs module.

- **Returns**: File path string

```lua
local lastFile = fs.lastReadFilePath()
```

### fs.setWindowsDrive(drive)

Set Windows drive letter for path operations.

- **Parameters**: `drive` (string, e.g., "C:")

```lua
fs.setWindowsDrive("D:")
```
