123 lines
4.8 KiB
Markdown
123 lines
4.8 KiB
Markdown
[](https://crates.io/crates/tree-fs)
|
|
[](https://docs.rs/tree-fs)
|
|
|
|
# tree-fs
|
|
|
|
`tree-fs` is a Rust library designed to simplify the creation and management of **temporary file system structures**. Its core feature is creating directories and files programmatically, which are **automatically cleaned up** when the managing object goes out of scope. This makes it ideal for scenarios where you need a predictable, temporary workspace, such as testing, build processes, or data generation tasks.
|
|
|
|
## Why `tree-fs`?
|
|
|
|
Manually creating and cleaning up temporary file structures can be cumbersome and error-prone. You might need to:
|
|
|
|
- Create specific directory layouts.
|
|
- Populate files with predefined content.
|
|
- Ensure files have particular permissions (e.g., a config file that should be read-only).
|
|
- Reliably clean up all temporary files and directories afterwards.
|
|
|
|
`tree-fs` automates these tasks, making your code cleaner and more reliable. Consider these use cases:
|
|
|
|
- **Testing**: Set up fixtures for tests that interact with the file system, ensuring a clean state for each test run.
|
|
- **Configuration Management**: Applications that load settings from files (e.g., `config/app.json`) can use `tree-fs` to generate temporary config files for specific runs.
|
|
- **Temporary Workspaces**: Create a temporary space for data processing, intermediate file generation, or running external tools that expect a certain directory structure.
|
|
- **Build Scripts & Scaffolding**: Generate temporary project structures or configuration files needed during a build process or for code generation tasks.
|
|
- **Permissions Handling**: Create files with specific permissions (like read-only) to test or simulate real-world scenarios.
|
|
|
|
## Features
|
|
|
|
- **Fluent Builder API**: Programmatically define your file tree.
|
|
- **YAML Configuration**: Define trees using YAML files or strings (requires the `yaml` feature).
|
|
- **Temporary Directories**: Trees are typically created in a system temporary folder.
|
|
- **Automatic Cleanup**: Temporary trees are automatically deleted when the `Tree` instance goes out of scope (this can be disabled).
|
|
- **File Contents**: Easily specify text content for files.
|
|
- **Empty Files & Directories**: Create empty files or entire directory structures.
|
|
- **File Settings**: Set file attributes, such as read-only permissions.
|
|
|
|
## Installation
|
|
|
|
Add `tree-fs` to your `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
tree-fs = "0.3" # Replace with the latest version
|
|
```
|
|
|
|
## Usage
|
|
|
|
### 1. Using the Builder API
|
|
|
|
The `TreeBuilder` provides a fluent interface to construct your desired file system structure.
|
|
|
|
```rust
|
|
use tree_fs::{TreeBuilder, Settings};
|
|
let tree = TreeBuilder::default()
|
|
.add_file("config/app.conf", "host = localhost")
|
|
.add_empty_file("logs/app.log")
|
|
.add_directory("data/raw")
|
|
.add_file_with_settings(
|
|
"secrets/api.key",
|
|
"supersecretkey",
|
|
Settings::new().readonly(true)
|
|
)
|
|
.create()
|
|
.expect("create tree fs");
|
|
println!("Created a complex tree in: {}", tree.root.display());
|
|
|
|
// You can verify the readonly status (this requires std::fs)
|
|
// let key_path = tree.root.join("secrets/api.key");
|
|
// let metadata = std::fs::metadata(key_path).unwrap();
|
|
// assert!(metadata.permissions().readonly());
|
|
```
|
|
|
|
For a more comprehensive example covering custom root directories, overriding files, and various file types, see `examples/builder.rs`.
|
|
|
|
You can disable this behavior using `.drop(false)` on the builder if you need the files to persist.
|
|
|
|
### 2. Using YAML (requires the `yaml` feature)
|
|
|
|
To use YAML, enable the `yaml` feature for `tree-fs` in your `Cargo.toml`.
|
|
|
|
#### From a YAML File
|
|
|
|
You can define your file tree in a YAML file. This is useful for complex or reusable structures.
|
|
|
|
**Example `tests/fixtures/tree.yaml`:**
|
|
|
|
```yaml
|
|
override_file: false
|
|
entries:
|
|
- path: foo.json
|
|
type: text_file
|
|
content: |
|
|
{ "foo": "bar" }
|
|
- path: folder/bar.yaml
|
|
type: text_file
|
|
content: |
|
|
foo: bar
|
|
- path: readonly_config.ini
|
|
type: text_file
|
|
content: |
|
|
; Sample read-only INI file
|
|
[general]
|
|
setting = value
|
|
settings:
|
|
readonly: true
|
|
```
|
|
|
|
**Rust code to load the YAML file:**
|
|
|
|
See the example file `examples/yaml-file.rs` for how to load this structure using `tree_fs::from_yaml_file`.
|
|
|
|
#### From a YAML String
|
|
|
|
For simpler or inline definitions, you can provide the YAML structure as a string.
|
|
|
|
See the example file `examples/yaml-str.rs` for how to load a structure from a YAML string using `tree_fs::from_yaml_str`, including defining settings like `readonly`.
|
|
|
|
## Contributing
|
|
|
|
Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/kaplanelad/tree-fs/issues).
|
|
|
|
## License
|
|
|
|
This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
|