Class: Tins::Find::Finder

Inherits:
Object show all
Defined in:
lib/tins/find.rb

Overview

The Finder class implements the core file system traversal logic. It handles path processing, error management, and directory traversal.

Defined Under Namespace

Modules: PathExtension

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Finder

Initializes a new Finder instance with specified options

Parameters:

  • opts (Hash) (defaults to: {}) —

    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



116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/tins/find.rb', line 116

def initialize(opts = {})
  @show_hidden     = opts.fetch(:show_hidden)     { true }
  @raise_errors    = opts.fetch(:raise_errors)    { false }
  @follow_symlinks = opts.fetch(:follow_symlinks) { true }
  if opts.key?(:visit) && opts.key?(:suffix)
    raise ArgumentError, 'either use visit or suffix argument'
  elsif opts.key?(:visit)
    @visit = opts.fetch(:visit) { -> path { true } }
  elsif opts.key?(:suffix)
    @suffix = Array(opts[:suffix])
    @visit = -> path { @suffix.nil? || @suffix.empty? || @suffix.include?(path.suffix) }
  end
end

Instance Attribute Details

Controls whether symbolic links should be followed during traversal

Returns:

  • (Boolean) 


140
141
142
 
# File 'lib/tins/find.rb', line 140

def follow_symlinks
  @follow_symlinks
end

#raise_errors ⇒ Boolean

Controls whether errors during file system operations should be raised

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/tins/find.rb', line 136

def raise_errors
  @raise_errors
end

#show_hidden ⇒ Boolean

Controls whether hidden files and directories are included in the search

Returns:

  • (Boolean) 


132
133
134
 
# File 'lib/tins/find.rb', line 132

def show_hidden
  @show_hidden
end

#suffix ⇒ Array<String>

The file suffix filter, if specified

Returns:



144
145
146
 
# File 'lib/tins/find.rb', line 144

def suffix
  @suffix
end

Instance Method Details

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

Performs a depth-first search of the specified paths

Parameters:

Yields:

  • (String) —

    Each path that matches the criteria

Returns:

  • (Enumerator) —

    If no block is given, returns an enumerator



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/tins/find.rb', line 163

def find(*paths)
  block_given? or return enum_for(__method__, *paths)
  paths.collect! { |d| d.dup }
  while path = paths.shift
    path = prepare_path(path)
    catch(:prune) do
      stat = path.finder_stat or next
      visit_path?(path) and yield path
      if stat.directory?
        ps = protect_from_errors { Dir.entries(path) } or next
        ps.sort!
        ps.reverse_each do |p|
          next if p == "." or p == ".."
          next if !@show_hidden && p.start_with?('.')
          p = File.join(path, p)
          paths.unshift p
        end
      end
    end
  end
end

#prepare_path(path) ⇒ String

Prepares a path for processing by extending it with PathExtension

Parameters:

  • path (String) —

    The path to prepare

Returns:

  • (String) —

    The prepared path object



189
190
191
192
193
194
 
# File 'lib/tins/find.rb', line 189

def prepare_path(path)
  path = path.dup
  path.extend PathExtension
  path.finder = self
  path
end

#protect_from_errors(errors = Find::EXPECTED_STANDARD_ERRORS) { ... } ⇒ Object?

Executes a block while protecting against expected standard errors

Parameters:

  • errors (Array<Class>) (defaults to: Find::EXPECTED_STANDARD_ERRORS) —

    Array of error classes to catch

Yields:

  • the block to be protected

Returns:

  • (Object, nil) —

    The result of the block or nil on error



201
202
203
204
205
206
 
# File 'lib/tins/find.rb', line 201

def protect_from_errors(errors = Find::EXPECTED_STANDARD_ERRORS)
  yield
rescue errors
  raise_errors and raise
  return
end

#visit_path?(path) ⇒ Boolean

Determines if a path should be visited based on the configured filters

Parameters:

  • path (String) —

    The path to check

Returns:

  • (Boolean) —

    true if the path should be visited



150
151
152
153
154
155
156
 
# File 'lib/tins/find.rb', line 150

def visit_path?(path)
  if !defined?(@visit) || @visit.nil?
    true
  else
    @visit.(path)
  end
end