Class: Rake::FileList

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 1568
    1568:       def [](*args)
    1569:         new(*args)
    1570:       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 1274
    1274:     def initialize(*patterns)
    1275:       @pending_add = []
    1276:       @pending = false
    1277:       @exclude_patterns = DEFAULT_IGNORE_PATTERNS.dup
    1278:       @exclude_procs = DEFAULT_IGNORE_PROCS.dup
    1279:       @exclude_re = nil
    1280:       @items = []
    1281:       patterns.each { |pattern| include(pattern) }
    1282:       yield self if block_given?
    1283:     end

### Public Instance methods

*(other)

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

[Source]

          # File lib/rake.rb, line 1369
    1369:     def *(other)
    1370:       result = @items * other
    1371:       case result
    1372:       when Array
    1373:         FileList.new.import(result)
    1374:       else
    1375:         result
    1376:       end
    1377:     end

==(array)

Define equality.

[Source]

          # File lib/rake.rb, line 1347
    1347:     def ==(array)
    1348:       to_ary == array
    1349:     end

add(*filenames)

Alias for include

calculate_exclude_regexp()

[Source]

          # File lib/rake.rb, line 1390
    1390:     def calculate_exclude_regexp
    1391:       ignores = []
    1392:       @exclude_patterns.each do |pat|
    1393:         case pat
    1394:         when Regexp
    1395:           ignores << pat
    1396:         when /[*?]/
    1397:           Dir[pat].each do |p| ignores << p end
    1398:         else
    1399:           ignores << Regexp.quote(pat)
    1400:         end
    1401:       end
    1402:       if ignores.empty?
    1403:         @exclude_re = /^$/
    1404:       else
    1405:         re_str = ignores.collect { |p| "(" + p.to_s + ")" }.join("|")
    1406:         @exclude_re = Regexp.new(re_str)
    1407:       end
    1408:     end

clear_exclude()

Clear all the exclude patterns so that we exclude nothing.

[Source]

          # File lib/rake.rb, line 1339
    1339:     def clear_exclude
    1340:       @exclude_patterns = []
    1341:       @exclude_procs = []
    1342:       calculate_exclude_regexp if ! @pending
    1343:       self
    1344:     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 1485
    1485:     def egrep(pattern)
    1486:       each do |fn|
    1487:         open(fn) do |inf|
    1488:           count = 0
    1489:           inf.each do |line|
    1490:             count += 1
    1491:             if pattern.match(line)
    1492:               if block_given?
    1493:                 yield fn, count, line
    1494:               else
    1495:                 puts "#{fn}:#{count}:#{line}"
    1496:               end
    1497:             end
    1498:           end
    1499:         end
    1500:       end
    1501:     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 1326
    1326:     def exclude(*patterns, &block)
    1327:       patterns.each do |pat|
    1328:         @exclude_patterns << pat
    1329:       end
    1330:       if block_given?
    1331:         @exclude_procs << block
    1332:       end
    1333:       resolve_exclude if ! @pending
    1334:       self
    1335:     end

exclude?(fn)

Should the given file name be excluded?

[Source]

          # File lib/rake.rb, line 1543
    1543:     def exclude?(fn)
    1544:       calculate_exclude_regexp unless @exclude_re
    1545:       fn =~ @exclude_re || @exclude_procs.any? { |p| p.call(fn) }
    1546:     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 1505
    1505:     def existing
    1506:       select { |fn| File.exist?(fn) }
    1507:     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 1511
    1511:     def existing!
    1512:       resolve
    1513:       @items = @items.select { |fn| File.exist?(fn) }
    1514:       self
    1515:     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 1475
    1475:     def ext(newext='')
    1476:       collect { |fn| fn.ext(newext) }
    1477:     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 1444
    1444:     def gsub(pat, rep)
    1445:       inject(FileList.new) { |res, fn| res << fn.gsub(pat,rep) }
    1446:     end

gsub!(pat, rep)

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

[Source]

          # File lib/rake.rb, line 1455
    1455:     def gsub!(pat, rep)
    1456:       each_with_index { |fn, i| self[i] = fn.gsub(pat,rep) }
    1457:       self
    1458:     end

import(array)

@exclude_patterns = DEFAULT_IGNORE_PATTERNS.dup

[Source]

          # File lib/rake.rb, line 1559
    1559:     def import(array)
    1560:       @items = array
    1561:       self
    1562:     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 1292
    1292:     def include(*filenames)
    1293:       # TODO: check for pending
    1294:       filenames.each do |fn|
    1295:         if fn.respond_to? :to_ary
    1296:           include(*fn.to_ary)
    1297:         else
    1298:           @pending_add << fn
    1299:         end
    1300:       end
    1301:       @pending = true
    1302:       self
    1303:     end

is_a?(klass)

Lie about our class.

[Source]

          # File lib/rake.rb, line 1363
    1363:     def is_a?(klass)
    1364:       klass == Array || super(klass)
    1365:     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 1463
    1463:     def pathmap(spec=nil)
    1464:       collect { |fn| fn.pathmap(spec) }
    1465:     end

resolve()

Resolve all the pending adds now.

[Source]

          # File lib/rake.rb, line 1380
    1380:     def resolve
    1381:       if @pending
    1382:         @pending = false
    1383:         @pending_add.each do |fn| resolve_add(fn) end
    1384:         @pending_add = []
    1385:         resolve_exclude
    1386:       end
    1387:       self
    1388:     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 1433
    1433:     def sub(pat, rep)
    1434:       inject(FileList.new) { |res, fn| res << fn.sub(pat,rep) }
    1435:     end

sub!(pat, rep)

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

[Source]

          # File lib/rake.rb, line 1449
    1449:     def sub!(pat, rep)
    1450:       each_with_index { |fn, i| self[i] = fn.sub(pat,rep) }
    1451:       self
    1452:     end

to_a()

Return the internal array object.

[Source]

          # File lib/rake.rb, line 1352
    1352:     def to_a
    1353:       resolve
    1354:       @items
    1355:     end

to_ary()

Return the internal array object.

[Source]

          # File lib/rake.rb, line 1358
    1358:     def to_ary
    1359:       to_a
    1360:     end

to_s()

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

[Source]

          # File lib/rake.rb, line 1529
    1529:     def to_s
    1530:       resolve
    1531:       self.join(' ')
    1532:     end

[Validate]