find_in_path/
lib.rs

1//! This crate allows you to find a file in the PATH
2//!
3//! # Quickstart
4//! Using this crate is very simple.
5//! All you need to do is ```use find_in_path::prelude::*;``` or ```use find_in_path::FindInPath;``` to be able to find a ```String```, ```&str```, ```PathBuf```, ```&Path``` in the user's PATH.
6//! ```
7//! use find_in_path::prelude::*;
8//! use std::path::PathBuf;
9//!
10//! let s: String = "sysctl".to_string();
11//! let s_in_path: Option<PathBuf> = s.find_in_path();
12//!
13//! // The resultant path will be os and distribution specific
14//! #[cfg(unix)]
15//! assert_eq!(s_in_path, Some(PathBuf::from("/usr/sbin/sysctl")));
16//! 
17//! #[cfg(windows)]
18//! assert_eq!(s_in_path, None);
19//! ```
20//! 
21//! # Non-unicode files
22//! find_in_path will support non-unicode paths through the OsString and &OsStr methods, however this remains unimplemented until a future release.
23//!
24//! # Security
25//! By default ```FindInPath``` delays looking in relative directories found in the PATH until the end, because this may lead to unwanted executables being run.
26//! You can stop FindInPath from checking relative directories altogether by setting the "skip_relative_directories" cargo feature.
27//! Additionally, if the path to the file found in a relative path, the returned ```PathBuf``` will always be relative.
28//!
29//! # Other behavers
30//! By default this crate assumes you are looking for an executable, which means that it will skip anything that is not an executable.
31//! 
32//! # Windows
33//! On Windows you can activate the non-default ```add_exe_ext``` cargo feature in order to automatically add .exe to the end of filenames if there isn't one there already.
34//! The feature will also not append ```.exe``` if the filename ends in ```.dll```.
35//! ```toml
36//! find_in_path = { version = "VERSION_NUMBER", features = ["add_exe_ext"] }
37//! ```
38//! Setting this feature on unix does nothing.
39//!
40
41pub mod prelude;
42
43mod str;
44mod string;
45mod path;
46mod pathbuf;
47
48/// Allows finding in the PATH
49///
50/// Any type that implements this trait can be turned into a PathBuf to a valid executable found with the PATH environment variable.
51pub trait FindInPath {
52    fn find_in_path(&self) -> Option<std::path::PathBuf>;
53}
find_in_path/lib.rs

find_in_path/
lib.rs
