13 releases

0.7.1	Aug 17, 2024
0.6.0	Jun 11, 2023
0.4.1	Oct 25, 2022
0.3.0	Jun 1, 2021

#206 in Filesystem

3,698 downloads per month
Used in 7 crates (4 directly)

MIT license

36KB
486 lines

build-fs-tree

Generate a filesystem tree from a macro or a YAML tree.

Description

When I write integration tests, I often find myself needing to create temporary files and directories. Therefore, I created this crate which provides both a library to use in a Rust code and a CLI program that generates a filesystem tree according to a YAML structure.

Usage Examples

The Library

Go to docs.rs for the full API reference.

`FileSystemTree`

FileSystemTree::build is faster than MergeableFileSystemTree::build but it does not write over an existing directory and it does not create parent directories when they don't exist.

use build_fs_tree::{FileSystemTree, Build, dir, file};
let tree: FileSystemTree<&str, &str> = dir! {
    "index.html" => file!(r#"
        <!DOCTYPE html>
        <link rel="stylesheet" href="styles/style.css" />
        <script src="scripts/main.js"></script>
    "#)
    "scripts" => dir! {
        "main.js" => file!(r#"document.write('Hello World')"#)
    }
    "styles" => dir! {
        "style.css" => file!(r#":root { color: red; }"#)
    }
};
tree.build("public").unwrap();

`MergeableFileSystemTree`

Unlike FileSystemTree::build, MergeableFileSystemTree::build can write over an existing directory and create parent directories that were not exist before at the cost of performance.

You can convert a FileSystemTree into a MergeableFileSystemTree via From::from/Into::into and vice versa.

use build_fs_tree::{MergeableFileSystemTree, Build, dir, file};
let tree = MergeableFileSystemTree::<&str, &str>::from(dir! {
    "public" => dir! {
        "index.html" => file!(r#"
            <!DOCTYPE html>
            <link rel="stylesheet" href="styles/style.css" />
            <script src="scripts/main.js"></script>
        "#)
        "scripts/main.js" => file!(r#"document.write('Hello World')"#)
        "scripts/style.css" => file!(r#":root { color: red; }"#)
    }
});
tree.build(".").unwrap();

Serialization and Deserialization

Both FileSystemTree and MergeableFileSystemTree implement serde::Deserialize and serde::Serialize.

The Program

The name of the command is build-fs-tree. It has 2 subcommands: create and populate.

`create`

This command reads YAML from stdin and creates a new filesystem tree. It is the CLI equivalent of FileSystemTree.

Create two text files in a new directory:

echo '{ foo.txt: HELLO, bar.txt: WORLD }' | build-fs-tree create foo-and-bar

Create a text file and its parent directories:

echo '{ text-files: { foo.txt: HELLO } }' | build-fs-tree create files

Create a new filesystem tree from a YAML file:

build-fs-tree create root < fs-tree.yaml

`populate`

This command reads YAML from stdin and either creates a new filesystem tree or add files and directories to an already existing directories. It is the CLI equivalent of MergeableFileSystemTree.

Create two text files in the current directory:

echo '{ foo.txt: HELLO, bar.txt: WORLD }' | build-fs-tree populate .

Create a text file and its parent directories:

echo '{ files/text-files/foo.txt: HELLO }' | build-fs-tree populate .

Populate the current directory with filesystem tree as described in a YAML file:

build-fs-tree populate . < fs-tree.yaml

Packaging Status

Frequently Asked Questions

Why YAML?

It has the features I desired: Easy to read and write, multiline strings done right.

What about this cool configuration format?

According to the UNIX philosophy, you may pipe your cool configuration format to a program that converts it to JSON (YAML is a superset of JSON) and then pipe the JSON output to build-fs-tree.

License

Dependencies

~2–3MB
~62K SLoC