File Layout

Container for laying out files in a single container for writing to disk. Notes:

1. Polymorphic over the representation of the file contents. For rendering, writeFiles requires the file content representation satisfy Writeable.
2. Only permits writing files/directories relative to a base path provided. Does not permit `..`, ., nor ~ as directory names.
3. System-local path separator is forbidden from use in directory names.
4. Assumes host file system is case-sensitive (i.e., recognizes txt and `a.txt` as different paths).

Get the top-level name (a PathSegment) of a FileLayout.

Create a file FileLayout. When written, this file will have a /trailing newline always added/. Use exactFile for building raw files. This is primarily for synthetic files/generated ones.

Create a file FileLayout containing the exact file contents.

Create a directory FileLayout, optionally containing any number of nested files.

When writing files or creating directories, is overwriting allowed?

Write a FileLayout to disk about a base path.

If the given OverwritePolicy is NeverOverwrite, this will fail if the top-level target path already exists. If it is OverwriteAllowed, it will overwrite existing files.

Disclaimer: For case-insensitive file systems where different paths in the layout might reference the same on-disk path, this code will fail.