Crate ergo_fs [−] [src]
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 countedPathBuf
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
: aPathAbs
that is guaranteed to be a file, with associated methods.PathDir
: aPathAbs
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
: aPathDir
that is deleted when it goes out of scope. This is a wrapper around the cratetempdir::TempDir
with methods that mimick thePath
types in this crate.FileRead
: a read-only file handle withpath()
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 withpath()
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 withpath()
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 exportedshellexpand
crate itself. Consider using withglob
(see below).glob
: a lightweight wrapper aroundglob::glob
that returnsPathType
objects.glob_with
: a lightweight wrapper aroundglob::glob_with
that returnsPathType
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 |
FileRead |
A read-only file handle with |
FileWrite |
A write-only file handle with |
GlobPathDirs |
Returns an iterator of only |
GlobPathFiles |
Returns an iterator of only |
GlobPathTypes |
An iterator that yields |
Path |
A slice of a path (akin to |
PathAbs |
An absolute (not necessarily canonicalized) path that may or may not exist. |
PathArc |
A |
PathBuf |
An owned, mutable path (akin to |
PathDir |
A |
PathFile |
a |
PathTmp |
A |
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 |
PathTypeExt |
Extended methods for |
Read |
The |
Functions
expand |
Performs both tilde and environment shell expansions in the default system context. This is
the same as |
glob |
Return an iterator that produces all the |
glob_with |
The same as |
Type Definitions
ExpandError |
Renamed |
GlobOptions |
Renamed |
GlobPatternError |
Renamed |