simple-fs

simple-fs is a crate that provides a set of convenient and common file APIs built on std::fs, walkdir, and globset.

Concept

simple-fs operates under the assumption that paths that are not utf8 are not visible to the API, simplifying many of the path-related APIs.

The main construct of simple-fs is the SPath structure, which contains a Utf8PathBuf and ensures the following:

• It is UTF-8 by contract.
• Posix normalizes the path, meaning only / (no \), and redundant // or /./ are collapsed to a single ./.
• It does not have any \\?\ on Windows.

By applying the above rules, path/file APIs can be drastically simplified, and SPath offers many Path functions, with &str as the return type.

This crate also offers a simple and scalable way to list or iterate on files, given a glob:

• iter_files(dir, include_globs: Option<&[&str]>, list_options: Option<ListOptions>) -> Result<impl Iterator<Item = SPath>>
• list_files(dir, include_globs: Option<&[&str]>, list_options: Option<ListOptions>) -> Result<Vec<SPath>>
• ensure_dir(dir_path) makes sure all the directory paths are created.
• ensure_file_dir(file_path) makes sure the file directory exists.

The crate also includes other convenient, common APIs:

• read_to_string, which reports the file path if not found.
• get_buf_reader, which also reports the file path if not found or in case of an error.

For more control, it is recommended to use std::fs, walkdir, globset, and other crates directly.

This is a very early implementation, with more to come.

Happy coding!

Cargo Features

Notable Changes

• 0.10.0 No more SFile (SPath for all, SFile was a left-over from early design. Did not provide real value, just code/API duplication)
• 0.9.0-alpha.x Same API (for now), but new optimized list_files(...) (hence the large version jump)
• 0.8.x Removed 'target/' and 'node_modules/' from the default excludes (too presumptive)
• 0.7.x SMeta.size is now u64 (changed from i64), new APIs
• 0.6.x
  • Now uses Utf8 by default; std path moved to ..std_path.. naming.
  • Now normalizes all SPath to be Posix based (i.e., / and removes redundant // and /./).
  • SPath/SFile.
  • ! Deprecated '.to_str()', now '.as_str()'
  • ! .diff(..) - Now takes AsRef Utf8Path, returns Option (use try_diff(..) for Result)
  • + Add collapse, into_collapsed, is_collapsed, try_collapse
  • ! .clean(..) is replaced by .collapse()
  • + list/iter files/dirs - Added support for negative glob patterns in include_globs (convenience).
  • ! API CHANGE - Now all default to Utf8Path (from camino crate). Use std_path...() for the standard path.
  • ^ sfile/spath - Added is_absolute/is_relative passthrough.
• 0.5.0
  • Internally uses camino, utf8path.
  • Reimplementation of the iter_files iterator, supporting absolute path globs out of the base directory.
• 0.4.0
  • Update to notify 8 (should not have any API changes)
  • API CHANGE - SPath - Now SPath::from(&str/&String,String) (no need for try_from)
• 0.3.1 from 0.3.0
  • This is a fix; however, it can change behavior on list/iter files.
    • Previously, the glob * was traversing into subfolders /, which was not the intended behavior.
    • Now, in 0.3.1, it uses the glob literal_separator = true, so it won't descend further.
    • You can now use *.rs to list direct descendants and **/*.rs for nested files.
    • The glob also needs to include the dir given in the list; otherwise, set ListOptions.relative_glob = true to make it relative.
• 0.3.x from 0.2.x
  • API CHANGE - watch - Changed the rx to be flume based (works on both sync/async).
• 0.2.0 from 0.1.x
  • API CHANGE - Now .file_name() and .file_stem() return Option<&str>; use .name() or .stem() to get &str.