class Rake::FileList

  1. lib/rake/file_list.rb
Parent: Rake

######################################################################### 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.

Included modules

  1. Cloneable

Constants

ARRAY_METHODS = (Array.instance_methods - Object.instance_methods).map { |n| n.to_s }  

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

MUST_DEFINE = %w[to_a inspect <=>]  

List of additional methods that must be delegated.

MUST_NOT_DEFINE = %w[to_a to_ary partition *]  

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

SPECIAL_RETURN = %w[ map collect sort sort_by select find_all reject grep compact flatten uniq values_at + - & | ]  

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

DELEGATING_METHODS = (ARRAY_METHODS + MUST_DEFINE - MUST_NOT_DEFINE).collect{ |s| s.to_s }.sort.uniq  
DEFAULT_IGNORE_PATTERNS = [ /(^|[\/\\])CVS([\/\\]|$)/, /(^|[\/\\])\.svn([\/\\]|$)/, /\.bak$/, /~$/ ]  
DEFAULT_IGNORE_PROCS = [ proc { |fn| fn =~ /(^|[\/\\])core$/ && ! File.directory?(fn) }  

External Aliases

add -> include
kind_of? -> is_a?

Public Class methods

new (*patterns)

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
[show source]
     # File lib/rake/file_list.rb, line 97
 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
[] (*args)

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

FileList.new(*args)
[show source]
     # File lib/rake/file_list.rb, line 383
383:       def [](*args)
384:         new(*args)
385:       end

Public Instance methods

include (*filenames)

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 )
[show source]
     # File lib/rake/file_list.rb, line 114
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
exclude (*patterns, &block)

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']
[show source]
     # File lib/rake/file_list.rb, line 148
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
clear_exclude ()

Clear all the exclude patterns so that we exclude nothing.

[show source]
     # File lib/rake/file_list.rb, line 161
161:     def clear_exclude
162:       @exclude_patterns = []
163:       @exclude_procs = []
164:       self
165:     end
== (array)

Define equality.

[show source]
     # File lib/rake/file_list.rb, line 168
168:     def ==(array)
169:       to_ary == array
170:     end
to_a ()

Return the internal array object.

[show source]
     # File lib/rake/file_list.rb, line 173
173:     def to_a
174:       resolve
175:       @items
176:     end
to_ary ()

Return the internal array object.

[show source]
     # File lib/rake/file_list.rb, line 179
179:     def to_ary
180:       to_a
181:     end
is_a? (klass)

Lie about our class.

[show source]
     # File lib/rake/file_list.rb, line 184
184:     def is_a?(klass)
185:       klass == Array || super(klass)
186:     end
* (other)

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

[show source]
     # File lib/rake/file_list.rb, line 190
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
resolve ()

Resolve all the pending adds now.

[show source]
     # File lib/rake/file_list.rb, line 201
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)

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']
[show source]
     # File lib/rake/file_list.rb, line 233
233:     def sub(pat, rep)
234:       inject(FileList.new) { |res, fn| res << fn.sub(pat,rep) }
235:     end
gsub (pat, rep)

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']
[show source]
     # File lib/rake/file_list.rb, line 244
244:     def gsub(pat, rep)
245:       inject(FileList.new) { |res, fn| res << fn.gsub(pat,rep) }
246:     end
sub! (pat, rep)

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

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

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

[show source]
     # File lib/rake/file_list.rb, line 255
255:     def gsub!(pat, rep)
256:       each_with_index { |fn, i| self[i] = fn.gsub(pat,rep) }
257:       self
258:     end
pathmap (spec=nil)

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.)

[show source]
     # File lib/rake/file_list.rb, line 263
263:     def pathmap(spec=nil)
264:       collect { |fn| fn.pathmap(spec) }
265:     end
ext (newext='')

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.

[show source]
     # File lib/rake/file_list.rb, line 275
275:     def ext(newext='')
276:       collect { |fn| fn.ext(newext) }
277:     end
egrep (pattern, *options)

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.

[show source]
     # File lib/rake/file_list.rb, line 285
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
existing ()

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

[show source]
     # File lib/rake/file_list.rb, line 312
312:     def existing
313:       select { |fn| File.exist?(fn) }
314:     end
existing! ()

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

[show source]
     # File lib/rake/file_list.rb, line 318
318:     def existing!
319:       resolve
320:       @items = @items.select { |fn| File.exist?(fn) }
321:       self
322:     end
to_s ()

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

[show source]
     # File lib/rake/file_list.rb, line 336
336:     def to_s
337:       resolve
338:       self.join(' ')
339:     end
exclude? (fn)

Should the given file name be excluded?

[show source]
     # File lib/rake/file_list.rb, line 350
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
import (array)
[show source]
     # File lib/rake/file_list.rb, line 374
374:     def import(array)
375:       @items = array
376:       self
377:     end

Private Instance methods

resolve_add (fn)
[show source]
     # File lib/rake/file_list.rb, line 211
211:     def resolve_add(fn)
212:       case fn
213:       when %{[*?\[\{]}
214:         add_matching(fn)
215:       else
216:         self << fn
217:       end
218:     end
resolve_exclude ()
[show source]
     # File lib/rake/file_list.rb, line 221
221:     def resolve_exclude
222:       reject! { |fn| exclude?(fn) }
223:       self
224:     end
add_matching (pattern)

Add matching glob patterns.

[show source]
     # File lib/rake/file_list.rb, line 342
342:     def add_matching(pattern)
343:       Dir[pattern].each do |fn|
344:         self << fn unless exclude?(fn)
345:       end
346:     end