Skip to content

Detect cyclic file handles with ease.

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

niklasmohrin/clircle

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

64 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Clircle

CI crates.io version MSRV

Clircle provides a cross-platform API to detect read / write cycles from your user-supplied arguments. You can get the important identifiers of a file (from a path) and for all three stdio streams, if they are piped from or to a file as well.

Why?

Imagine you want to read data from a couple of files and output something according to the contents of these files. If the user redirects the output of your program to one of the input files, you might end up in an infinite circle of reading and writing.

The crate provides the struct Identifier which is a platform dependent type alias, so that you can use it on all platforms and do not need to introduce any conditional compilation yourself. On both Unix and Windows systems, Identifier holds information to identify a file on a disk.

The Clircle trait is implemented on both of these structs and requires TryFrom for the clircle::Stdio enum and for &Path, so that all possible inputs can be represented as an Identifier. Finally, Clircle is a subtrait of Eq, so that the identifiers can be conveniently compared and circles can be detected. The clircle crate also provides some convenience functions around the comparison of Clircle implementors.

Why should I use this and not just fs::Metadata?

The clircle crate seamlessly works on Linux and Windows through a single API, so no conditional compilation is needed at all. Furthermore, MetadataExt is not stable on Windows yet, meaning you would have to dig into the Windows APIs yourself to get the information needed to identify a file.

Where did this crate come from?

This crate originated in a pull request to the bat project. The bat tool strives to be a drop-in replacement for the unix tool cat. Since cat detects these cycles, bat has to do so too, which is where most of this code came into play. However, it was decided, that the new logic was

  • useful for other projects and
  • too platform specific for bats scope.

So now, you can use clircle too!

About

Detect cyclic file handles with ease.

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Stars

Watchers

Forks

Languages