#json-toml #toml #json #io #system-api #file-io

simple-fs

Simple and convenient API for File System access

28 releases (6 breaking)

Uses new Rust 2024

new 0.6.0-rc.3 Mar 10, 2025
0.5.4 Feb 28, 2025
0.3.1 Nov 24, 2024
0.1.3 Mar 9, 2024
0.0.4 Dec 31, 2023

#228 in Filesystem

Download history 178/week @ 2024-11-20 35/week @ 2024-11-27 99/week @ 2024-12-04 142/week @ 2024-12-11 15/week @ 2024-12-18 44/week @ 2024-12-25 15/week @ 2025-01-08 140/week @ 2025-01-15 37/week @ 2025-01-22 6/week @ 2025-01-29 26/week @ 2025-02-05 107/week @ 2025-02-12 164/week @ 2025-02-19 699/week @ 2025-02-26 377/week @ 2025-03-05

1,347 downloads per month
Used in 5 crates (4 directly)

MIT/Apache

70KB
1.5K SLoC

simple-fs

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

Cargo Features

Feature Functions Included
with-json load_json, save_json, save_json_pretty
with-toml load_toml, save_toml
bin-nums save_be_f64, load_be_f64, save_le_f64, ...
full All the above.
default None of the above. See below.

API Changes

  • 0.6.x (rc for now)
    • Now use Utf8 by default, std path moved to ..std_path.. naming.
  • 0.5.0
    • Internal use 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 - changes 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.

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 two constructs that follow this assumption are (both are just wrappers of PathBuf with some guarantees):

  • SPath, which ensures that the contained path is a valid UTF-8 path and includes a file name.
  • SFile, which carries the same guarantees as SPath but also checks if the file is_file(), confirming the file's existence at the time of SFile construction.

By establishing these rules, APIs such as .file_name(), .file_stem(), and .to_str() are much simpler, as they all return &str.

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.
  • iter_files(dir, include_globs: &[&str], exclude_globs: &[&str]) -> Result<impl Iter SFile>
  • list_files(..same as iter_files..) -> Result<Vec<SFile>>
  • ensure_dir(dir_path), ensure_file_dir(file_path)
  • With features, see above.

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!

Dependencies

~4–13MB
~148K SLoC