Crate ergo_fs [−] [src]

ergo_fs: 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, which can change at any time.

The crates it wraps/rexports are:

path_abs: Ergonomic paths and files in rust.
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.
std_prelude: prelude that the rust stdlib should have always had.

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::*;

This will also export the std_prelude crate into your namespace, giving you automatic access to the io::{Read, Write} traits, path::{Path, PathBuf} types and more.

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.

The following types are exported from [path_abs][path_abs]. These types provide improved error messages and type safety when working with paths and files. See the [crate documentation] [path_abs] for more details.

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.

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.

Temporary Directories

There is one type exported which mimicks the above Path* objects.

Walkdir

The Walkdir type 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, it is easy to convert to a file if you would like to.

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 types like PathDir and FileWrite when interacting with this crate.

TODO: improve tar error messages. See this issue

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.

Reexports

pub extern crate path_abs;

pub extern crate glob as glob_crate;

pub extern crate shellexpand;

pub extern crate std_prelude;

pub extern crate tar;

pub extern crate tempdir;

pub extern crate walkdir;

pub use std_prelude::*;

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 `PathDirs`s, any files that matched the glob are ignored.
GlobPathFiles	Returns an iterator of only `PathFile`s, any directories that matched the glob are ignored.
GlobPathTypes	An iterator that yields `PathType`s from the filesystem that match a particular pattern.
PathAbs	An absolute (canonicalized) path that is guaranteed (when created) to 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.
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

PathDirExt	Extension method on the `Path` type.
PathTypeExt	Extended methods for `PathType`

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 `PathType`s 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 Definitions

ExpandError	Renamed `shellexpand::LookupError` for better ergonomics.
GlobOptions	Renamed `glob::MatchOptions`
GlobPatternError	Renamed `glob::PatternError`