fast-fs 0.2.1

// <FILE>src/functions/fnc_is_ignored.rs</FILE> - <DESC>Helper function to check if a path is ignored by gitignore</DESC>
// <VERS>VERSION: 1.0.1</VERS>
// <WCTX>Fixing doc tests to use no_run instead of ignore</WCTX>
// <CLOG>Changed doc example from ignore to no_run</CLOG>

use crate::{GitignoreMatcher, TraversalOptions};
use std::path::Path;

/// Check if a path would be ignored by gitignore patterns at the given root
///
/// This is a convenience wrapper that creates a GitignoreMatcher for the root
/// and checks if the given path is ignored according to the traversal options.
///
/// # Arguments
///
/// * `path` - The path to check (relative or absolute)
/// * `root` - The root directory to use for gitignore matching
/// * `options` - TraversalOptions controlling whether gitignore is enabled
///
/// # Returns
///
/// Returns `true` if the path matches ignore patterns, `false` otherwise.
/// If `options.gitignore` is `false`, always returns `false`.
/// If no `.gitignore` exists at the root, returns `false`.
/// Returns `false` on any I/O error (e.g., root is not a directory).
///
/// # Examples
///
/// ```no_run
/// use fast_fs::{is_ignored, TraversalOptions};
/// use std::path::Path;
///
/// let root = Path::new("/project");
/// let options = TraversalOptions::default();
/// let path = root.join("target/debug");
///
/// if is_ignored(&path, root, &options) {
///     println!("Path is ignored");
/// }
/// ```
pub fn is_ignored(path: &Path, root: &Path, options: &TraversalOptions) -> bool {
    // If gitignore filtering is disabled, nothing is ignored
    if !options.gitignore {
        return false;
    }

    // Try to create a gitignore matcher for the root
    let matcher = match GitignoreMatcher::from_path(root) {
        Ok(m) => m,
        Err(_) => {
            // If we can't create a matcher (e.g., root is not a directory or I/O error),
            // return false (not ignored)
            return false;
        }
    };

    // Determine if the path is a directory
    // We check if it exists and is a directory; if it doesn't exist, we assume it's not a directory
    let is_dir = path.is_dir();

    // Check if the path matches ignore patterns
    matcher.is_ignored(path, is_dir)
}

// <FILE>src/functions/fnc_is_ignored.rs</FILE>
// <VERS>END OF VERSION: 1.0.0</VERS>