Class: Rake::FileList (Ruby 2.7.5)
Description: Class : Rake::FileList - Ruby 2.7.5

### Home Classes Methods

### In Files

- rake-13.0.1/lib/rake/file_list.rb

### Parent

Object

### Methods

- ::[]
- ::glob
- ::new
- #*
- #<<
- #==
- #add
- #clear_exclude
- #egrep
- #exclude
- #excluded_from_list?
- #existing
- #existing!
- #ext
- #gsub
- #gsub!
- #include
- #is_a?
- #kind_of?
- #pathmap
- #resolve
- #sub
- #sub!
- #to_a
- #to_ary
- #to_s

### Files

- CONTRIBUTING.rdoc
- History.rdoc
- README.rdoc
- command_line_usage.rdoc
- glossary.rdoc
- proto_rake.rdoc
- rakefile.rdoc
- rational.rdoc

### Class/Module Index

Quicksearch

- FileUtils
- Module
- Object
- RDoc
- RDoc::Page
- Rake::Application
- Rake::DSL
- Rake::DefaultLoader
- Rake::EarlyTime
- Rake::FileCreationTask
- Rake::FileList
- Rake::FileTask
- Rake::FileUtilsExt
- Rake::InvocationChain
- Rake::InvocationChain::EmptyInvocationChain
- Rake::InvocationExceptionMixin
- Rake::LateTime
- Rake::LinkedList
- Rake::LinkedList::EmptyLinkedList
- Rake::MakefileLoader
- Rake::MultiTask
- Rake::NameSpace
- Rake::PackageTask
- Rake::PrivateReader
- Rake::RakeFileUtils
- Rake::RuleRecursionOverflowError
- Rake::Scope
- Rake::Task
- Rake::TaskArgumentError
- Rake::TaskArguments
- Rake::TaskLib
- Rake::TaskManager
- Rake::TestTask
- Rake::Win32
- String

No matching classes.

# 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
GLOB_PATTERN
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 rake-13.0.1/lib/rake/file_list.rb, line 400
    def [](*args)
      new(*args)
    end

glob(pattern, *args) click to toggle source

Get a sorted list of files matching the pattern. This method should be preferred to Dir and Dir.glob(pattern) because the files returned are guaranteed to be sorted.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 407
    def glob(pattern, *args)
      Dir.glob(pattern, *args).sort
    end

new(*patterns) 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 rake-13.0.1/lib/rake/file_list.rb, line 99
    def initialize(*patterns)
      @pending_add = []
      @pending = false
      @exclude_patterns = DEFAULT_IGNORE_PATTERNS.dup
      @exclude_procs = DEFAULT_IGNORE_PROCS.dup
      @items = []
      patterns.each { |pattern| include(pattern) }
      yield self if block_given?
    end

### Public Instance Methods

*(other) click to toggle source

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

                   # File rake-13.0.1/lib/rake/file_list.rb, line 193
    def *(other)
      result = @items * other
      case result
      when Array
        self.class.new.import(result)
      else
        result
      end
    end

<<(obj) click to toggle source

                   # File rake-13.0.1/lib/rake/file_list.rb, line 203
    def <<(obj)
      resolve
      @items << Rake.from_pathname(obj)
      self
    end

==(array) click to toggle source

A `FileList` is equal through array equality.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 171
    def ==(array)
      to_ary == array
    end

add(*filenames) click to toggle source
Alias for: include
clear_exclude() click to toggle source

Clear all the exclude patterns so that we exclude nothing.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 164
    def clear_exclude
      @exclude_patterns = []
      @exclude_procs = []
      self
    end

egrep(pattern, *options) 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 rake-13.0.1/lib/rake/file_list.rb, line 293
    def egrep(pattern, *options)
      matched = 0
      each do |fn|
        begin
          File.open(fn, "r", *options) do |inf|
            count = 0
            inf.each do |line|
              count += 1
              if pattern.match(line)
                matched += 1
                if block_given?
                  yield fn, count, line
                else
                  puts "#{fn}:#{count}:#{line}"
                end
              end
            end
          end
        rescue StandardError => ex
          $stderr.puts "Error while processing '#{fn}': #{ex}"
        end
      end
      matched
    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 rake-13.0.1/lib/rake/file_list.rb, line 150
    def exclude(*patterns, &block)
      patterns.each do |pat|
        if pat.respond_to? :to_ary
          exclude(*pat.to_ary)
        else
          @exclude_patterns << Rake.from_pathname(pat)
        end
      end
      @exclude_procs << block if block_given?
      resolve_exclude unless @pending
      self
    end

excluded_from_list?(fn) click to toggle source

Should the given file name be excluded from the list?

NOTE: This method was formerly named “exclude?”, but Rails introduced an exclude? method as an array method and setup a conflict with file list. We renamed the method to avoid confusion. If you were using “FileList#exclude?” in your user code, you will need to update.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 364
    def excluded_from_list?(fn)
      return true if @exclude_patterns.any? do |pat|
        case pat
        when Regexp
          fn =~ pat
        when GLOB_PATTERN
          flags = File::FNM_PATHNAME
          # Ruby <= 1.9.3 does not support File::FNM_EXTGLOB
          flags |= File::FNM_EXTGLOB if defined? File::FNM_EXTGLOB
          File.fnmatch?(pat, fn, flags)
        else
          fn == pat
        end
      end
      @exclude_procs.any? { |p| p.call(fn) }
    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 rake-13.0.1/lib/rake/file_list.rb, line 320
    def existing
      select { |fn| File.exist?(fn) }.uniq
    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 rake-13.0.1/lib/rake/file_list.rb, line 326
    def existing!
      resolve
      @items = @items.select { |fn| File.exist?(fn) }.uniq
      self
    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 rake-13.0.1/lib/rake/file_list.rb, line 284
    def ext(newext="")
      collect { |fn| fn.ext(newext) }
    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 rake-13.0.1/lib/rake/file_list.rb, line 253
    def gsub(pat, rep)
      inject(self.class.new) { |res, fn| res << fn.gsub(pat, rep) }
    end

gsub!(pat, rep) click to toggle source

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

                   # File rake-13.0.1/lib/rake/file_list.rb, line 264
    def gsub!(pat, rep)
      each_with_index { |fn, i| self[i] = fn.gsub(pat, rep) }
      self
    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 rake-13.0.1/lib/rake/file_list.rb, line 116
    def include(*filenames)
      # TODO: check for pending
      filenames.each do |fn|
        if fn.respond_to? :to_ary
          include(*fn.to_ary)
        else
          @pending_add << Rake.from_pathname(fn)
        end
      end
      @pending = true
      self
    end

Also aliased as: add
is_a?(klass) click to toggle source

Lie about our class.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 187
    def is_a?(klass)
      klass == Array || super(klass)
    end

Also aliased as: kind_of?
kind_of?(klass) click to toggle source
Alias for: is_a?
pathmap(spec=nil, &block) 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 rake-13.0.1/lib/rake/file_list.rb, line 272
    def pathmap(spec=nil, &block)
      collect { |fn| fn.pathmap(spec, &block) }
    end

resolve() click to toggle source

Resolve all the pending adds now.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 210
    def resolve
      if @pending
        @pending = false
        @pending_add.each do |fn| resolve_add(fn) end
        @pending_add = []
        resolve_exclude
      end
      self
    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 rake-13.0.1/lib/rake/file_list.rb, line 242
    def sub(pat, rep)
      inject(self.class.new) { |res, fn| res << fn.sub(pat, rep) }
    end

sub!(pat, rep) click to toggle source

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

                   # File rake-13.0.1/lib/rake/file_list.rb, line 258
    def sub!(pat, rep)
      each_with_index { |fn, i| self[i] = fn.sub(pat, rep) }
      self
    end

to_a() click to toggle source

Return the internal array object.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 176
    def to_a
      resolve
      @items
    end

to_ary() click to toggle source

Return the internal array object.

                   # File rake-13.0.1/lib/rake/file_list.rb, line 182
    def to_ary
      to_a
    end

to_s() click to toggle source

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

                   # File rake-13.0.1/lib/rake/file_list.rb, line 344
    def to_s
      resolve
      self.join(" ")
    end