Crate ergo_fs 

Methods and types for making working with the filesystem ergonomic, therefore fun.

Purpose

This crate provides a minimal set of common types and methods for working with the filesystem. These types aim to provide:

• Descriptive error messages
• Good performance, but not necessarily at all costs.
• As much type safety as is possible when dealing with the filesystem

The crates it wraps/rexports are:

• glob: Support for matching file paths against Unix shell style patterns.
• path_abs: Ergonomic paths and files in rust.
• shellexpand: A library for shell-like expansions of variables in strings.
• tar-rs: A library for reading and writing TAR archives.
• tempdir: Temporary directories of files.
• walkdir: Provides an efficient and cross platform implementation of recursive directory traversal.

Consider supporting their development individually and starring them on github.

How to Use

ergo_fs is intended to be a “standard library” of filesystem types. Therefore you should use like so:

extern crate ergo_fs;
use ergo_fs::*;

Types

This library provides several kinds of types which improve and expand on std::fs and std::path, as well as provide new functionality like temporary files and tar archives.

Path, Dir and File Types

These types provide improved error messages and type safety when working with paths and files.

• PathArc: a reference counted PathBuf with methods reimplemented with better error messages. Use this for a generic serializable path that may or may not exist.
• PathAbs: a reference counted absolute (canonicalized) path that is guaranteed (on initialization) to exist.
• PathFile: a PathAbs that is guaranteed to be a file, with associated methods.
• PathDir: a PathAbs that is guaranteed to be a directory, with associated methods.
• PathType: an enum containing either a PathFile or a PathDir. Returned by [PathDir::list][dir_list]
• PathTmp: a PathDir that is deleted when it goes out of scope. This is a wrapper around the crate tempdir::TempDir with methods that mimick the Path types in this crate.
• FileRead: a read-only file handle with path() attached and improved error messages. Contains only the methods and trait implementations which are allowed by a read-only file.
• FileWrite: a write-only file handle with path() attached and improved error messages. Contains only the methods and trait implementations which are allowed by a write-only file.
• FileEdit: a read/write file handle with path() attached and improved error messages. Contains methods and trait implements for both readable and writeable files.
• WalkDir: used for recursively walking directories quickly. See the Walkdir section below.

In addition, it exports the following from std_prelude

• traits: Read, IoWrite
• types: Path, PathBuf

Methods

The following methods are exported.

• expand: does shell expansion on both tilde (~ = home dir) and environment variables with the user’s home directory + env variables. Also see the exported shellexpand crate itself. Consider using with glob (see below).
• glob: a lightweight wrapper around glob::glob that returns PathType objects.
• glob_with: a lightweight wrapper around glob::glob_with that returns PathType objects.

Details

Bellow are some additional details about imported types.

Walkdir

Use PathDir::walk to walk a directory. This returns the Walkdir iterator, which is a direct export from the walkdir crate. The crate already has excellent error messages, and although it returns the regular std::path::PathBuf type, you can convert to a PathType using PathType::from_entry.

TODO: although the WalkDir error can be auto-converted to std::io::Error, it does not preserve the pretty output. See this ticket

Examples

use ergo_fs::*;

let dir = PathDir::new("src")?;
for entry in dir.walk().max_depth(1) {
    match PathType::from_entry(entry?)? {
        PathType::File(file) => println!("got file {}", file.display()),
        PathType::Dir(dir) => println!("got dir {}", dir.display()),
    }
}

Tar Files

Similarly to walkdir, this is a direct export of the tar crate. It is recommended that you use the FileWrite and FileRead types when interacting with this crate so that reading/writing have context. This library already has pretty errors for every other operation.

use ergo_fs::*;
use ergo_fs::tar::Builder;

// We are going to tar the source code of this library

let tmp = PathTmp::create("tmp")?;
let mut tarfile = FileWrite::create(tmp.join("src.tar"))?;

// tar the source directory
let mut tar = Builder::new(tarfile);
tar.append_dir_all("src", ".")?;
tar.finish();
let tarfile = tar.into_inner()?;

// A tarfile now exists, do whatever you would like with it.

Re-exports

pub extern crate glob as glob_crate;

pub extern crate path_abs;

pub extern crate shellexpand;

pub extern crate std_prelude;

pub extern crate tar;

pub extern crate tempdir;

pub extern crate walkdir;

Structs

FileEdit

A read/write file handle with path() attached and improved error messages. Contains methods and trait implements for both readable and writeable files.

FileRead

A read-only file handle with path() attached and improved error messages. Contains only the methods and trait implementations which are allowed by a read-only file.

FileWrite

A write-only file handle with path() attached and improved error messages. Contains only the methods and trait implementations which are allowed by a write-only file.

GlobPathDirs

Returns an iterator of only PathDirss, any files that matched the glob are ignored.

GlobPathFiles

Returns an iterator of only PathFiles, any directories that matched the glob are ignored.

GlobPathTypes

An iterator that yields PathTypes from the filesystem that match a particular pattern.

Path

A slice of a path (akin to str).

PathAbs

An absolute (not necessarily canonicalized) path that may or may not exist.

PathArc

A PathBuf that is atomically reference counted and reimplements the PathBuf methods to display the action and path when there is an error.

PathBuf

An owned, mutable path (akin to String).

PathDir

A PathAbs that is guaranteed to be a directory, with associated methods.

PathFile

a PathAbs that was a file at the time of initialization, with associated methods.

PathTmp

A PathDir that is automatically deleted when it goes out of scope.

WalkDir

A builder to create an iterator for recursively walking a directory.

WalkError

An error produced by recursively walking a directory.

Enums

PathType

An an enum containing either a file or a directory.

Traits

IoWrite

A trait for objects which are byte-oriented sinks.

PathDirExt

Extension method on the Path type.

PathTypeExt

Extended methods for PathType

Read

The Read trait allows for reading bytes from a source.

Functions

expand

Performs both tilde and environment shell expansions in the default system context. This is the same as shellexpand::full and is the “typical use case” for expanding strings.

glob

Return an iterator that produces all the PathTypes that match the given pattern, which may be absolute or relative to the current working directory.

glob_with

The same as glob but with additional options.

Type Aliases

ExpandError

Renamed shellexpand::LookupError for better ergonomics.

GlobOptions

Renamed glob::MatchOptions

GlobPatternError

Renamed glob::PatternError