file-mumu 0.1.6

File handling function and steams plugin for the Lava language
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# file-mumu

**File handling functions and streams plugin for the [Lava language](https://lava.nu11.uk) / Mumu engine**

[![crates.io](https://img.shields.io/crates/v/mumu-file.svg)](https://crates.io/crates/mumu-file)
[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/mumu-file)](#license)

---

## Overview

`mumu-file` provides Lava/Mumu scripts with file reading, writing, and streaming capabilities.  
It supports synchronous and streaming I/O, large file handling, and is suitable for both direct scripting and use as a dynamic plugin.

- **Read files** (entire or as streams/chunks)
- **Write files** (sync, streaming, or with iterators/transforms)
- **Integrates natively** with Lava's function system

## Features

- `file:read` — Read files as a string or in streaming/chunked mode.
- `file:write` — Write data, arrays, iterators, or streaming transforms to files.
- `file:stream` — Utility for chunked streaming to stdout.

Fully asynchronous at the Rust level (threaded), with Lava/Ink integration for safe, ergonomic script access.

---

## Installation

### As a Rust plugin

Add to your `Cargo.toml`:

```toml
[dependencies]
mumu-file = "0.1"
```

### Building for Lava/Mumu

Clone and build (Linux example):

```sh
git clone https://gitlab.com/tofo/mumu-file.git
cd mumu-file
make
make install
```
This installs the `libmumufile.so` plugin to `/usr/local/lib/`, making it available for Lava/Mumu.

---

## Usage

### In Lava/Mumu scripts

```lava
extend("file")

# Synchronous read
file:read("hello.txt", (data) => {
  slog("File contents:", data)
})

# Streaming read (chunked)
file:read("bigfile.txt", file:stream)

# Synchronous write
file:write("out.txt", "Hello, world!")

# Write from array
file:write("numbers.txt", [1,2,3,4])

# Partial application
let write_hello = file:write("out.txt")
write_hello("Extra text")

# Stream-based write (see docs)
```

### In Rust

```rust
use mumu_file; // (libmumufile.so)
```
The plugin is loaded dynamically by Lava/Mumu via `extend("file")`.  
Direct usage as a Rust crate is possible for advanced users; see API docs for details.

---

## API

### `file:read(path, callback)`

- Reads a file and invokes the callback with the contents.
- If the callback is `file:stream`, reads in chunks (for large files).
- Returns `true` on start; actual results are passed to the callback.

### `file:write(path, data)`

- Writes data to a file. Data may be:
  - a string
  - an array
  - an iterator (for large/growing data)
  - a transform (function)
- Supports partial application: `let writer = file:write(path)` returns a function.

### `file:stream(chunk)`

- Prints a chunk (usually from a streaming read) to stdout with no newline.
- If chunk is empty, closes stream.

---

## Minimum Supported Rust Version (MSRV)

Rust 1.60 or newer.

---

## License

Licensed under either of:

- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE) or <https://www.apache.org/licenses/LICENSE-2.0>)

at your option.

---

## Links

- [Lava language homepage](https://lava.nu11.uk)
- [GitLab repository](https://gitlab.com/tofo/mumu-file)
- [Crates.io page](https://crates.io/crates/mumu-file)

---

## Author

Tom Fotheringham <tom@nu11.co.uk>