Module: Tins::Find

Defined in:
lib/tins/find.rb

Overview

This module provides file system traversal functionality with support for filtering by file type, handling of hidden files, and error management.

The Find module implements a depth-first search algorithm that traverses directory trees, yielding each path to the provided block. It handles various edge cases including symbolic links, permission errors, and circular references.

Examples:

Basic usage

Tins::Find.find('/path/to/directory') do |path|
  puts path
end

Find files with specific extension

Tins::Find.find('/path/to/directory', suffix: 'rb') do |path|
  puts path
end

Skip directories and files

Tins::Find.find('/path/to/directory') do |path|
  if File.directory?(path)
    Tins::Find.prune  # Skip this directory and its contents
  else
    puts path
  end
end

Defined Under Namespace

Classes: Finder

Constant Summary collapse

EXPECTED_STANDARD_ERRORS =

Standard errors that are expected during file system operations and will be silently handled unless raise_errors is enabled

ModuleGroup[
  Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP,
  Errno::ENAMETOOLONG
]

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.find(*paths, **opts) {|String| ... } ⇒ Enumerator

Performs a depth-first search of the specified paths, yielding each matching path to the block

Examples:

Basic usage

Tins::Find.find('/path/to/directory') do |path|
  puts path
end

Find only Ruby files

Tins::Find.find('/path/to/directory', suffix: 'rb') do |path|
  puts path
end

Parameters:

  • paths (Array<String>) —

    The root paths to search

  • opts (Hash) —

    Configuration options

Options Hash (**opts):

  • :show_hidden (Boolean) — default: true —

    Whether to include hidden files/directories

  • :raise_errors (Boolean) — default: false —

    Whether to raise exceptions on errors

  • :follow_symlinks (Boolean) — default: true —

    Whether to follow symbolic links

  • :suffix (Array<String, Symbol>) — default: nil —

    Filter by file extension(s)

  • :visit (Proc) — default: nil —

    Custom filter predicate

Yields:

  • (String) —

    Each path that matches the criteria

Returns:

  • (Enumerator) —

    If no block is given, returns an enumerator



231
232
233
 
# File 'lib/tins/find.rb', line 231

def find(*paths, **opts, &block)
  Finder.new(opts).find(*paths, &block)
end

.prune ⇒ Object

Skips the current path or directory, restarting the loop with the next entry. Meaningful only within the block associated with Find.find.

Examples:

Skip directories

Tins::Find.find('/path/to/directory') do |path|
  if path.count(?/) < 3
    Tins::Find.prune  # Skip all paths deeper than 2
  else
    puts path
  end
end


246
247
248
 
# File 'lib/tins/find.rb', line 246

def prune
  throw :prune
end

Instance Method Details

#find(*paths, **opts) {|String| ... } ⇒ Enumerator (private)

Performs a depth-first search of the specified paths, yielding each matching path to the block

Examples:

Basic usage

Tins::Find.find('/path/to/directory') do |path|
  puts path
end

Find only Ruby files

Tins::Find.find('/path/to/directory', suffix: 'rb') do |path|
  puts path
end

Parameters:

  • paths (Array<String>) —

    The root paths to search

  • opts (Hash) —

    Configuration options

Options Hash (**opts):

  • :show_hidden (Boolean) — default: true —

    Whether to include hidden files/directories

  • :raise_errors (Boolean) — default: false —

    Whether to raise exceptions on errors

  • :follow_symlinks (Boolean) — default: true —

    Whether to follow symbolic links

  • :suffix (Array<String, Symbol>) — default: nil —

    Filter by file extension(s)

  • :visit (Proc) — default: nil —

    Custom filter predicate

Yields:

  • (String) —

    Each path that matches the criteria

Returns:

  • (Enumerator) —

    If no block is given, returns an enumerator



231
232
233
 
# File 'lib/tins/find.rb', line 231

def find(*paths, **opts, &block)
  Finder.new(opts).find(*paths, &block)
end

#prune ⇒ Object (private)

Skips the current path or directory, restarting the loop with the next entry. Meaningful only within the block associated with Find.find.

Examples:

Skip directories

Tins::Find.find('/path/to/directory') do |path|
  if path.count(?/) < 3
    Tins::Find.prune  # Skip all paths deeper than 2
  else
    puts path
  end
end


246
247
248
 
# File 'lib/tins/find.rb', line 246

def prune
  throw :prune
end