Class | Rake::FileList
In: | lib/rake.rb
Parent: | Object

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

### Methods

* == [] add calculate_exclude_regexp clear_exclude egrep exclude exclude? existing existing! ext gsub gsub! import include is_a? kind_of? new pathmap resolve sub sub! to_a to_ary to_s

### Included Modules

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

### Public Class methods

[](*args)

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

      FileList.new(*args)

[Source]

          # File lib/rake.rb, line 1496
    1496:       def [](*args)
    1497:         new(*args)
    1498:       end

new(*patterns) {|self if block_given?| ...}

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

[Source]

          # File lib/rake.rb, line 1202
    1202:     def initialize(*patterns)
    1203:       @pending_add = []
    1204:       @pending = false
    1205:       @exclude_patterns = DEFAULT_IGNORE_PATTERNS.dup
    1206:       @exclude_procs = DEFAULT_IGNORE_PROCS.dup
    1207:       @exclude_re = nil
    1208:       @items = []
    1209:       patterns.each { |pattern| include(pattern) }
    1210:       yield self if block_given?
    1211:     end

### Public Instance methods

*(other)

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

[Source]

          # File lib/rake.rb, line 1297
    1297:     def *(other)
    1298:       result = @items * other
    1299:       case result
    1300:       when Array
    1301:         FileList.new.import(result)
    1302:       else
    1303:         result
    1304:       end
    1305:     end

==(array)

Define equality.

[Source]

          # File lib/rake.rb, line 1275
    1275:     def ==(array)
    1276:       to_ary == array
    1277:     end

add(*filenames)

Alias for include

calculate_exclude_regexp()

[Source]

          # File lib/rake.rb, line 1318
    1318:     def calculate_exclude_regexp
    1319:       ignores = []
    1320:       @exclude_patterns.each do |pat|
    1321:         case pat
    1322:         when Regexp
    1323:           ignores << pat
    1324:         when /[*?]/
    1325:           Dir[pat].each do |p| ignores << p end
    1326:         else
    1327:           ignores << Regexp.quote(pat)
    1328:         end
    1329:       end
    1330:       if ignores.empty?
    1331:         @exclude_re = /^$/
    1332:       else
    1333:         re_str = ignores.collect { |p| "(" + p.to_s + ")" }.join("|")
    1334:         @exclude_re = Regexp.new(re_str)
    1335:       end
    1336:     end

clear_exclude()

Clear all the exclude patterns so that we exclude nothing.

[Source]

          # File lib/rake.rb, line 1267
    1267:     def clear_exclude
    1268:       @exclude_patterns = []
    1269:       @exclude_procs = []
    1270:       calculate_exclude_regexp if ! @pending
    1271:       self
    1272:     end

egrep(pattern) {|fn, count, line| ...}

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 emac style file:linenumber:line message will be printed to standard out.

[Source]

          # File lib/rake.rb, line 1413
    1413:     def egrep(pattern)
    1414:       each do |fn|
    1415:         open(fn) do |inf|
    1416:           count = 0
    1417:           inf.each do |line|
    1418:             count += 1
    1419:             if pattern.match(line)
    1420:               if block_given?
    1421:                 yield fn, count, line
    1422:               else
    1423:                 puts "#{fn}:#{count}:#{line}"
    1424:               end
    1425:             end
    1426:           end
    1427:         end
    1428:       end
    1429:     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']

[Source]

          # File lib/rake.rb, line 1254
    1254:     def exclude(*patterns, &block)
    1255:       patterns.each do |pat|
    1256:         @exclude_patterns << pat
    1257:       end
    1258:       if block_given?
    1259:         @exclude_procs << block
    1260:       end
    1261:       resolve_exclude if ! @pending
    1262:       self
    1263:     end

exclude?(fn)

Should the given file name be excluded?

[Source]

          # File lib/rake.rb, line 1471
    1471:     def exclude?(fn)
    1472:       calculate_exclude_regexp unless @exclude_re
    1473:       fn =~ @exclude_re || @exclude_procs.any? { |p| p.call(fn) }
    1474:     end

existing()

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

[Source]

          # File lib/rake.rb, line 1433
    1433:     def existing
    1434:       select { |fn| File.exist?(fn) }
    1435:     end

existing!()

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

[Source]

          # File lib/rake.rb, line 1439
    1439:     def existing!
    1440:       resolve
    1441:       @items = @items.select { |fn| File.exist?(fn) }
    1442:       self
    1443:     end

ext(newext='')

Return a new array 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.

[Source]

          # File lib/rake.rb, line 1403
    1403:     def ext(newext='')
    1404:       collect { |fn| fn.ext(newext) }
    1405:     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']

[Source]

          # File lib/rake.rb, line 1372
    1372:     def gsub(pat, rep)
    1373:       inject(FileList.new) { |res, fn| res << fn.gsub(pat,rep) }
    1374:     end

gsub!(pat, rep)

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

[Source]

          # File lib/rake.rb, line 1383
    1383:     def gsub!(pat, rep)
    1384:       each_with_index { |fn, i| self[i] = fn.gsub(pat,rep) }
    1385:       self
    1386:     end

import(array)

@exclude_patterns = DEFAULT_IGNORE_PATTERNS.dup

[Source]

          # File lib/rake.rb, line 1487
    1487:     def import(array)
    1488:       @items = array
    1489:       self
    1490:     end

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 )

[Source]

          # File lib/rake.rb, line 1220
    1220:     def include(*filenames)
    1221:       # TODO: check for pending
    1222:       filenames.each do |fn|
    1223:         if fn.respond_to? :to_ary
    1224:           include(*fn.to_ary)
    1225:         else
    1226:           @pending_add << fn
    1227:         end
    1228:       end
    1229:       @pending = true
    1230:       self
    1231:     end

is_a?(klass)

Lie about our class.

[Source]

          # File lib/rake.rb, line 1291
    1291:     def is_a?(klass)
    1292:       klass == Array || super(klass)
    1293:     end

kind_of?(klass)

Alias for is_a?

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

[Source]

          # File lib/rake.rb, line 1391
    1391:     def pathmap(spec=nil)
    1392:       collect { |fn| fn.pathmap(spec) }
    1393:     end

resolve()

Resolve all the pending adds now.

[Source]

          # File lib/rake.rb, line 1308
    1308:     def resolve
    1309:       if @pending
    1310:         @pending = false
    1311:         @pending_add.each do |fn| resolve_add(fn) end
    1312:         @pending_add = []
    1313:         resolve_exclude
    1314:       end
    1315:       self
    1316:     end

sub(pat, rep)

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

Example:

      FileList['a.c', 'b.c'].sub(/\.c$/, '.o')  => ['a.o', 'b.o']

[Source]

          # File lib/rake.rb, line 1361
    1361:     def sub(pat, rep)
    1362:       inject(FileList.new) { |res, fn| res << fn.sub(pat,rep) }
    1363:     end

sub!(pat, rep)

Same as `sub` except that the oringal file list is modified.

[Source]

          # File lib/rake.rb, line 1377
    1377:     def sub!(pat, rep)
    1378:       each_with_index { |fn, i| self[i] = fn.sub(pat,rep) }
    1379:       self
    1380:     end

to_a()

Return the internal array object.

[Source]

          # File lib/rake.rb, line 1280
    1280:     def to_a
    1281:       resolve
    1282:       @items
    1283:     end

to_ary()

Return the internal array object.

[Source]

          # File lib/rake.rb, line 1286
    1286:     def to_ary
    1287:       to_a
    1288:     end

to_s()

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

[Source]

          # File lib/rake.rb, line 1457
    1457:     def to_s
    1458:       resolve
    1459:       self.join(' ')
    1460:     end

[Validate]