file-editor 0.1.0

Clean, elegant API for creating and editing text files
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

# file-editor

[![CI](https://github.com/davidwilliam/file-editor/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/davidwilliam/file-editor/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/davidwilliam/file-editor/branch/master/graph/badge.svg)](https://app.codecov.io/gh/davidwilliam/file-editor)
[![crates.io](https://img.shields.io/crates/v/file-editor.svg)](https://crates.io/crates/file-editor)
[![docs.rs](https://img.shields.io/docsrs/file-editor)](https://docs.rs/file-editor)

Clean, chain-friendly **text-file editing for Rust** • *edition 2024*

`file-editor` is a zero-dependency library that makes it painless to create,
modify and query UTF-8 text files.  
All mutating methods return **`&mut self`**, so edits compose naturally:

```rust
use file_editor::Editor;

fn main() -> std::io::Result<()> {
    Editor::create("notes.txt")?               // new file
        .append("Rust 🦀 is fun\n")
        .prepend("# My Notes\n")
        .insert_after("# My Notes", "========\n", true)
        .replace("fun", "blazingly fast")
        .save()?;                              // explicit flush
    Ok(())
}
```

## Feature table

| Verb | Method | Notes |
|------|--------|-------|
| Create / open             | `Editor::create`, `Editor::open` |
| Rename                    | `rename` |
| Prepend / append          | `prepend`, `append` |
| Insert <br>before / after | `insert_before`, `insert_after`<br>`same_indent` flag keeps indentation |
| Replace one marker        | `replace_marker` |
| Search pattern            | `find_lines` → 1-based line numbers |
| Erase, replace, mask      | `erase`, `replace`, `mask` |
| Save to disk              | `save` |

Road-map → *regex* feature, streaming mode, companion CLI.

## Install

```bash
cargo add file-editor          # latest on crates.io
```

Requires **Rust 1.85** (edition 2024) or newer.

## Workflow

| Task | Command |
|------|---------|
| Build | `cargo build` |
| Run **all** tests & doctests | `cargo test` |
| Format | `cargo fmt --all` |
| Lint (deny warnings) | `cargo clippy --all-targets -- -D warnings` |
| Coverage (HTML) | `cargo llvm-cov --workspace --open`<br/>*(one-time `cargo install cargo-llvm-cov`)* |
| Generate docs | `cargo doc --no-deps --open` |

CI executes the same steps (see `.github/workflows/ci.yml`).

## Runnable examples

All live in **[`examples/`](examples/)** and write their output to
`examples/sandbox/` (ignored by git):

| Example | Demonstrates |
|---------|--------------|
| `basic.rs`               | End-to-end mini workflow |
| `create.rs`              | `create` + `append` |
| `open_rename.rs`         | `open`, `rename` |
| `prepend.rs`, `append.rs`| header / footer insertion |
| `insert_before.rs`       | block insertion above a marker |
| `insert_after.rs`        | block insertion below a marker |
| `replace_marker.rs`      | in-place marker replacement |
| `find_lines.rs`          | pattern search |
| `erase.rs`               | deleting fragments |
| `replace.rs`, `mask.rs`  | global replacements / masking |

Run any of them with:

```bash
cargo run --example insert_after
```

## Contributing

1. Fork & clone  
2. `cargo fmt --check && cargo clippy --all-targets -- -D warnings`  
3. Add or update tests in `tests/` (use the `tempfile` crate)  
4. Open a PR describing **what** and **why**

All contributions are released under the **MIT** licence.

## Licence

Copyright © 2025  

Licensed under the **MIT License**. See [`LICENSE`](LICENSE).