class Rake::FileList

######################################################################### A FileList is essentially an array with a few helper methods defined to make file manipulation a bit easier.

FileLists are lazy. When given a list of glob patterns for possible files to be included in the file list, instead of searching the file structures to find the files, a FileList holds the pattern for latter use.

This allows us to define a number of FileList to match any number of files, but only search out the actual files when then FileList itself is actually used. The key is that the first time an element of the FileList/Array is requested, the pending patterns are resolved into a real list of file names.

Constants

ARRAY_METHODS

List of array methods (that are not in Object) that need to be delegated.

DEFAULT_IGNORE_PATTERNS
DEFAULT_IGNORE_PROCS
DELEGATING_METHODS
MUST_DEFINE

List of additional methods that must be delegated.

MUST_NOT_DEFINE

List of methods that should not be delegated here (we define special versions of them explicitly below).

SPECIAL_RETURN

List of delegated methods that return new array values which need wrapping.

Public Class Methods

[](*args) click to toggle source

Create a new file list including the files listed. Similar to:

FileList.new(*args)
    # File lib/rake/file_list.rb
383 def [](*args)
384   new(*args)
385 end
new(*patterns) { |self| ... } click to toggle source

Create a file list from the globbable patterns given. If you wish to perform multiple includes or excludes at object build time, use the “yield self” pattern.

Example:

file_list = FileList.new('lib/**/*.rb', 'test/test*.rb')

pkg_files = FileList.new('lib/**/*') do |fl|
  fl.exclude(/\bCVS\b/)
end
    # File lib/rake/file_list.rb
 97 def initialize(*patterns)
 98   @pending_add = []
 99   @pending = false
100   @exclude_patterns = DEFAULT_IGNORE_PATTERNS.dup
101   @exclude_procs = DEFAULT_IGNORE_PROCS.dup
102   @items = []
103   patterns.each { |pattern| include(pattern) }
104   yield self if block_given?
105 end

Public Instance Methods

*(other) click to toggle source

Redefine * to return either a string or a new file list.

    # File lib/rake/file_list.rb
190 def *(other)
191   result = @items * other
192   case result
193   when Array
194     FileList.new.import(result)
195   else
196     result
197   end
198 end
==(array) click to toggle source

Define equality.

    # File lib/rake/file_list.rb
168 def ==(array)
169   to_ary == array
170 end
add(*filenames)
Alias for: include
clear_exclude() click to toggle source

Clear all the exclude patterns so that we exclude nothing.

    # File lib/rake/file_list.rb
161 def clear_exclude
162   @exclude_patterns = []
163   @exclude_procs = []
164   self
165 end
egrep(pattern, *options) { |fn, count, line| ... } click to toggle source

Grep each of the files in the filelist using the given pattern. If a block is given, call the block on each matching line, passing the file name, line number, and the matching line of text. If no block is given, a standard emacs style file:linenumber:line message will be printed to standard out. Returns the number of matched items.

    # File lib/rake/file_list.rb
285 def egrep(pattern, *options)
286   matched = 0
287   each do |fn|
288     begin
289       open(fn, "rb", *options) do |inf|
290         count = 0
291         inf.each do |line|
292           count += 1
293           if pattern.match(line)
294             matched += 1
295             if block_given?
296               yield fn, count, line
297             else
298               puts "#{fn}:#{count}:#{line}"
299             end
300           end
301         end
302       end
303     rescue StandardError => ex
304       $stderr.puts "Error while processing '#{fn}': #{ex}"
305     end
306   end
307   matched
308 end
exclude(*patterns, &block) click to toggle source

Register a list of file name patterns that should be excluded from the list. Patterns may be regular expressions, glob patterns or regular strings. In addition, a block given to exclude will remove entries that return true when given to the block.

Note that glob patterns are expanded against the file system. If a file is explicitly added to a file list, but does not exist in the file system, then an glob pattern in the exclude list will not exclude the file.

Examples:

FileList['a.c', 'b.c'].exclude("a.c") => ['b.c']
FileList['a.c', 'b.c'].exclude(/^a/)  => ['b.c']

If “a.c” is a file, then …

FileList['a.c', 'b.c'].exclude("a.*") => ['b.c']

If “a.c” is not a file, then …

FileList['a.c', 'b.c'].exclude("a.*") => ['a.c', 'b.c']
    # File lib/rake/file_list.rb
148 def exclude(*patterns, &block)
149   patterns.each do |pat|
150     @exclude_patterns << pat
151   end
152   if block_given?
153     @exclude_procs << block
154   end
155   resolve_exclude if ! @pending
156   self
157 end
exclude?(fn) click to toggle source

Should the given file name be excluded?

    # File lib/rake/file_list.rb
350 def exclude?(fn)
351   return true if @exclude_patterns.any? do |pat|
352     case pat
353     when Regexp
354       fn =~ pat
355     when /[*?]/
356       File.fnmatch?(pat, fn, File::FNM_PATHNAME)
357     else
358       fn == pat
359     end
360   end
361   @exclude_procs.any? { |p| p.call(fn) }
362 end
existing() click to toggle source

Return a new file list that only contains file names from the current file list that exist on the file system.

    # File lib/rake/file_list.rb
312 def existing
313   select { |fn| File.exist?(fn) }
314 end
existing!() click to toggle source

Modify the current file list so that it contains only file name that exist on the file system.

    # File lib/rake/file_list.rb
318 def existing!
319   resolve
320   @items = @items.select { |fn| File.exist?(fn) }
321   self
322 end
ext(newext='') click to toggle source

Return a new FileList with String#ext method applied to each member of the array.

This method is a shortcut for:

array.collect { |item| item.ext(newext) }

ext is a user added method for the Array class.

    # File lib/rake/file_list.rb
275 def ext(newext='')
276   collect { |fn| fn.ext(newext) }
277 end
gsub(pat, rep) click to toggle source

Return a new FileList with the results of running gsub against each element of the original list.

Example:

FileList['lib/test/file', 'x/y'].gsub(/\//, "\\")
   => ['lib\\test\\file', 'x\\y']
    # File lib/rake/file_list.rb
244 def gsub(pat, rep)
245   inject(FileList.new) { |res, fn| res << fn.gsub(pat,rep) }
246 end
gsub!(pat, rep) click to toggle source

Same as gsub except that the original file list is modified.

    # File lib/rake/file_list.rb
255 def gsub!(pat, rep)
256   each_with_index { |fn, i| self[i] = fn.gsub(pat,rep) }
257   self
258 end
import(array) click to toggle source
    # File lib/rake/file_list.rb
374 def import(array)
375   @items = array
376   self
377 end
include(*filenames) click to toggle source

Add file names defined by glob patterns to the file list. If an array is given, add each element of the array.

Example:

file_list.include("*.java", "*.cfg")
file_list.include %w( math.c lib.h *.o )
    # File lib/rake/file_list.rb
114 def include(*filenames)
115   # TODO: check for pending
116   filenames.each do |fn|
117     if fn.respond_to? :to_ary
118       include(*fn.to_ary)
119     else
120       @pending_add << fn
121     end
122   end
123   @pending = true
124   self
125 end
Also aliased as: add
is_a?(klass) click to toggle source

Lie about our class.

Calls superclass method
    # File lib/rake/file_list.rb
184 def is_a?(klass)
185   klass == Array || super(klass)
186 end
Also aliased as: kind_of?
kind_of?(klass)
Alias for: is_a?
pathmap(spec=nil) click to toggle source

Apply the pathmap spec to each of the included file names, returning a new file list with the modified paths. (See String#pathmap for details.)

    # File lib/rake/file_list.rb
263 def pathmap(spec=nil)
264   collect { |fn| fn.pathmap(spec) }
265 end
resolve() click to toggle source

Resolve all the pending adds now.

    # File lib/rake/file_list.rb
201 def resolve
202   if @pending
203     @pending = false
204     @pending_add.each do |fn| resolve_add(fn) end
205     @pending_add = []
206     resolve_exclude
207   end
208   self
209 end
sub(pat, rep) click to toggle source

Return a new FileList with the results of running sub against each element of the original list.

Example:

FileList['a.c', 'b.c'].sub(/\.c$/, '.o')  => ['a.o', 'b.o']
    # File lib/rake/file_list.rb
233 def sub(pat, rep)
234   inject(FileList.new) { |res, fn| res << fn.sub(pat,rep) }
235 end
sub!(pat, rep) click to toggle source

Same as sub except that the original file list is modified.

    # File lib/rake/file_list.rb
249 def sub!(pat, rep)
250   each_with_index { |fn, i| self[i] = fn.sub(pat,rep) }
251   self
252 end
to_a() click to toggle source

Return the internal array object.

    # File lib/rake/file_list.rb
173 def to_a
174   resolve
175   @items
176 end
to_ary() click to toggle source

Return the internal array object.

    # File lib/rake/file_list.rb
179 def to_ary
180   to_a
181 end
to_s() click to toggle source

Convert a FileList to a string by joining all elements with a space.

    # File lib/rake/file_list.rb
336 def to_s
337   resolve
338   self.join(' ')
339 end

Private Instance Methods

add_matching(pattern) click to toggle source

Add matching glob patterns.

    # File lib/rake/file_list.rb
342 def add_matching(pattern)
343   Dir[pattern].each do |fn|
344     self << fn unless exclude?(fn)
345   end
346 end
resolve_add(fn) click to toggle source
    # File lib/rake/file_list.rb
211 def resolve_add(fn)
212   case fn
213   when %r{[*?\[\{]}
214     add_matching(fn)
215   else
216     self << fn
217   end
218 end
resolve_exclude() click to toggle source
    # File lib/rake/file_list.rb
221 def resolve_exclude
222   reject! { |fn| exclude?(fn) }
223   self
224 end