superwhich 3.0.1

//! # superwhich
//!
//! Smart `which` alternative that uses [Jaro-Winkler distance](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance) to calculate the similarity between the provided pattern and the executable filenames.
//!
//! ## MSRV
//!
//! | Version | Edition | MSRV |
//! | --- | --- | --- |
//! | 3.x.y | 2024 | 1.85 |
//! | 2.x.y | 2021 | 1.80 |
//! | 1.x.y | 2021 | N/A |
//!
//! ## Installation
//!
//! ```bash
//! cargo add superwhich
//! ```
//!
//! Or add this to your `Cargo.toml` file:
//!
//! ```toml
//! [dependencies]
//! superwhich = "3.0.1"
//! ```
//!
//! ## Usage
//!
//! ```rust,no_run
//! use rayon::iter::{ParallelBridge, ParallelIterator};
//! use std::{
//!     env::{split_paths, var_os},
//!     path::Path,
//!     sync::Arc,
//! };
//! use superwhich::{
//!     SearchCtx, colored::Color, crossbeam::channel::unbounded, find_files, par_find_files,
//! };
//!
//! // construct the context needed for the search
//! let ctx = Arc::new(
//!     SearchCtx::new("GURE".to_string())
//!         .threshold(0.7)
//!         .color(Color::Red),
//! );
//! let (tx, rx) = unbounded(); // channel to send found paths in
//!
//! // run the search directly with a singular path
//! let path = Path::new("path/to/search");
//! par_find_files(path, &ctx, &tx);
//!
//! // or run the search inside a parallel iterator
//! split_paths(&var_os("PATH").expect("PATH is not set"))
//!     .par_bridge()
//!     .for_each(|path| {
//!         find_files(&path, &ctx, &tx);
//!     });
//!
//! // DO NOT run the parallel function inside a parallel iterator, it actually slows down the search considerably
//!
//! // print the found paths (they're String)
//! while let Ok(path) = rx.try_recv() {
//!     println!("{}", path);
//! }
//! ```
//!
//! ## Benchmarks
//!
//! ```text
//! Timer precision: 100 ns
//! str                fastest       │ slowest       │ median        │ mean          │ samples │ iters
//! ├─ fast lowercase  2.554 ms      │ 3.497 ms      │ 2.666 ms      │ 2.74 ms       │ 100     │ 100
//! │                  39.14 Mitem/s │ 28.59 Mitem/s │ 37.5 Mitem/s  │ 36.49 Mitem/s │         │
//! │                  max alloc:    │               │               │               │         │
//! │                    1           │ 1             │ 1             │ 1             │         │
//! │                    2.4 MB      │ 2.4 MB        │ 2.4 MB        │ 2.4 MB        │         │
//! │                  alloc:        │               │               │               │         │
//! │                    1           │ 1             │ 1             │ 1             │         │
//! │                    2.4 MB      │ 2.4 MB        │ 2.4 MB        │ 2.4 MB        │         │
//! ╰─ std lowercase   4.877 ms      │ 7.723 ms      │ 5.288 ms      │ 5.456 ms      │ 100     │ 100
//!                    20.5 Mitem/s  │ 12.94 Mitem/s │ 18.91 Mitem/s │ 18.32 Mitem/s │         │
//!                    max alloc:    │               │               │               │         │
//!                      100001      │ 100001        │ 100001        │ 100001        │         │
//!                      4.9 MB      │ 4.9 MB        │ 4.9 MB        │ 4.9 MB        │         │
//!                    alloc:        │               │               │               │         │
//!                      100001      │ 100001        │ 100001        │ 100001        │         │
//!                      4.9 MB      │ 4.9 MB        │ 4.9 MB        │ 4.9 MB        │         │
//! ```
//!
//! ```text
//! Timer precision: 100 ns
//! swhich                          fastest       │ slowest       │ median        │ mean          │ samples │ iters
//! ├─ find_files (1000 files)      505.7 µs      │ 1.263 ms      │ 514.7 µs      │ 548.2 µs      │ 100     │ 100
//! │                               1.977 Mitem/s │ 791.4 Kitem/s │ 1.942 Mitem/s │ 1.824 Mitem/s │         │
//! │                               max alloc:    │               │               │               │         │
//! │                                 4           │ 4             │ 4             │ 4             │         │
//! │                                 289 B       │ 289 B         │ 289 B         │ 289 B         │         │
//! │                               alloc:        │               │               │               │         │
//! │                                 1004        │ 1004          │ 1004          │ 1004          │         │
//! │                                 12.13 KB    │ 12.13 KB      │ 12.13 KB      │ 12.13 KB      │         │
//! │                               dealloc:      │               │               │               │         │
//! │                                 1004        │ 1004          │ 1004          │ 1004          │         │
//! │                                 12.18 KB    │ 12.18 KB      │ 12.18 KB      │ 12.18 KB      │         │
//! │                               grow:         │               │               │               │         │
//! │                                 1           │ 1             │ 1             │ 1             │         │
//! │                                 47 B        │ 47 B          │ 47 B          │ 47 B          │         │
//! ╰─ par_find_files (1000 files)  1.007 ms      │ 2.26 ms       │ 1.266 ms      │ 1.321 ms      │ 100     │ 100
//!                                 992.1 Kitem/s │ 442.4 Kitem/s │ 789.6 Kitem/s │ 756.6 Kitem/s │         │
//!                                 max alloc:    │               │               │               │         │
//!                                   4           │ 4             │ 4             │ 5.49          │         │
//!                                   289 B       │ 289 B         │ 289 B         │ 852 B         │         │
//!                                 alloc:        │               │               │               │         │
//!                                   5           │ 5             │ 5             │ 6.56          │         │
//!                                   258 B       │ 258 B         │ 258 B         │ 828.3 B       │         │
//!                                 dealloc:      │               │               │               │         │
//!                                   3           │ 3             │ 3             │ 3.06          │         │
//!                                   210 B       │ 210 B         │ 210 B         │ 221.2 B       │         │
//!                                 grow:         │               │               │               │         │
//!                                   1           │ 1             │ 1             │ 1             │         │
//!                                   47 B        │ 47 B          │ 47 B          │ 47 B          │         │
//! ```

#![forbid(unsafe_code)]
#![warn(clippy::pedantic, missing_docs, missing_debug_implementations)]

/*
 * superwhich: smart which alternative
 * Copyright (C) 2024 `DarkCeptor44`
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

pub use colored;
pub use crossbeam;

use colored::{Color, Colorize};
use crossbeam::channel::Sender;
use jaro_winkler::jaro_winkler;
use rayon::iter::{ParallelBridge, ParallelIterator};
use std::borrow::Cow;
use std::{
    path::{MAIN_SEPARATOR, Path},
    sync::Arc,
};

/// Search context. This holds the search pattern, threshold needed for the search, and the color for the highlighted text.
/// Must be wrapped in an [Arc] to be shared between threads
#[derive(Debug, Clone)]
pub struct SearchCtx {
    color: Option<Color>,
    pattern: String,
    threshold: f64,
}

impl SearchCtx {
    /// Create a new search context
    ///
    /// ## Arguments
    ///
    /// * `pattern` - Search pattern
    ///
    /// ## Returns
    ///
    /// A new search context
    #[must_use]
    pub fn new<S>(pattern: S) -> Self
    where
        S: Into<String>,
    {
        Self {
            color: None,
            pattern: pattern.into().to_lowercase(),
            threshold: 0.7,
        }
    }

    /// Set the color for the highlighted text
    ///
    /// ## Arguments
    ///
    /// * `color` - Color
    ///
    /// ## Returns
    ///
    /// A new search context
    #[must_use]
    pub fn color<C>(mut self, color: C) -> Self
    where
        C: Into<Option<Color>>,
    {
        let color = color.into();
        self.color = if color.is_some_and(|c| c == Color::White) {
            None
        } else {
            color
        };
        self
    }

    /// Set the search pattern
    ///
    /// ## Arguments
    ///
    /// * `pattern` - Search pattern
    ///
    /// ## Returns
    ///
    /// A new search context
    #[must_use]
    pub fn pattern<S>(mut self, pattern: S) -> Self
    where
        S: Into<String>,
    {
        self.pattern = pattern.into().to_lowercase();
        self
    }

    /// Set the threshold for the Jaro-Winkler distance
    ///
    /// ## Arguments
    ///
    /// * `threshold` - Threshold
    ///
    /// ## Returns
    ///
    /// A new search context
    #[must_use]
    pub fn threshold(mut self, threshold: f64) -> Self {
        self.threshold = threshold;
        self
    }
}

/// Trait providing fast lowercase conversion
pub trait FastLowercase {
    /// Convert to lowercase fast
    ///
    /// Only converts strings that contain at least one uppercase character,
    /// otherwise it doesn't touch it and just returns a borrowed string
    ///
    /// ## Returns
    ///
    /// A lowercase string as [Cow]
    ///
    /// ## Examples
    ///
    /// ```rust,no_run
    /// use std::borrow::Cow;
    /// use superwhich::FastLowercase;
    ///
    /// let a = "abc";
    /// let b = "aBc";
    ///
    /// let a_l = a.to_lowercase_fast(); // Borrowed("abc")
    /// let b_l = b.to_lowercase_fast(); // Owned("abc")
    /// ```
    fn to_lowercase_fast(&self) -> Cow<'_, str>;
}

impl<T> FastLowercase for T
where
    T: AsRef<str>,
{
    fn to_lowercase_fast(&self) -> Cow<'_, str> {
        let s = self.as_ref();
        if s.chars().all(|c| !c.is_uppercase()) {
            Cow::Borrowed(s)
        } else {
            Cow::Owned(s.to_lowercase())
        }
    }
}

/// Find files within the specified path that match the pattern in the context
///
/// It just looks at the filename, it doesn't check for file permissions, types or anything
///
/// ## Arguments
///
/// * `path` - Path to search
/// * `ctx` - Search context
/// * `tx` - Channel to send found paths
///
/// ## Examples
///
/// ```rust,no_run
/// use rayon::iter::{ParallelBridge, ParallelIterator};
/// use std::{
///     env::{split_paths, var_os},
///     path::PathBuf,
///     sync::Arc,
/// };
/// use superwhich::{SearchCtx, colored::Color, crossbeam::channel::unbounded, find_files};
///
/// let ctx = Arc::new(
///     SearchCtx::new("GURE".to_string())
///         .threshold(0.7)
///         .color(Color::Red),
/// );
/// let (tx, rx) = unbounded();
///
/// split_paths(&var_os("PATH").expect("PATH is not set"))
///     .par_bridge()
///     .for_each(|path: PathBuf| {
///         find_files(&path, &ctx, &tx);
///     });
///
/// while let Ok(path) = rx.try_recv() {
///     println!("{}", path);
/// }
/// ```
pub fn find_files(path: &Path, ctx: &Arc<SearchCtx>, tx: &Sender<String>) {
    let Ok(read_dir) = std::fs::read_dir(path) else {
        return;
    };

    let parent_str = path.to_string_lossy();
    for entry in read_dir.flatten() {
        let Ok(ft) = entry.file_type() else {
            continue;
        };

        if !ft.is_file() {
            continue;
        }

        if let Some(fname) = entry.file_name().to_str() {
            let fname_lower = fname.to_lowercase_fast();

            if jaro_winkler(&fname_lower, &ctx.pattern) >= ctx.threshold {
                let result = if let Some(color) = ctx.color {
                    format!("{parent_str}{}{}", MAIN_SEPARATOR, fname.color(color))
                } else {
                    entry.path().to_string_lossy().into_owned()
                };
                let _ = tx.send(result);
            }
        }
    }
}

/// Find files within the specified path that match the pattern in the context, in parallel
///
/// It just looks at the filename, it doesn't check for file permissions, types or anything
///
/// ## Arguments
///
/// * `path` - Path to search
/// * `ctx` - Search context
/// * `tx` - Channel to send found paths
///
/// ## Examples
///
/// ```rust,no_run
/// use std::{path::Path, sync::Arc};
/// use superwhich::{SearchCtx, colored::Color, crossbeam::channel::unbounded, par_find_files};
///
/// let ctx = Arc::new(
///     SearchCtx::new("GURE".to_string())
///         .threshold(0.7)
///         .color(Color::Red),
/// );
/// let (tx, rx) = unbounded();
/// let path = Path::new("path/to/search");
///
/// par_find_files(path, &ctx, &tx);
///
/// while let Ok(path) = rx.try_recv() {
///     println!("{}", path);
/// }
/// ```
pub fn par_find_files(path: &Path, ctx: &Arc<SearchCtx>, tx: &Sender<String>) {
    let Ok(read_dir) = std::fs::read_dir(path) else {
        return;
    };

    let parent_str = path.to_string_lossy();
    read_dir.par_bridge().flatten().for_each(|entry| {
        let Ok(ft) = entry.file_type() else {
            return;
        };

        if !ft.is_file() {
            return;
        }

        if let Some(fname) = entry.file_name().to_str() {
            let fname_lower = fname.to_lowercase_fast();

            if jaro_winkler(&fname_lower, &ctx.pattern) >= ctx.threshold {
                let result = if let Some(color) = ctx.color {
                    format!("{parent_str}{}{}", MAIN_SEPARATOR, fname.color(color))
                } else {
                    entry.path().to_string_lossy().into_owned()
                };
                let _ = tx.send(result);
            }
        }
    });
}