duck_test 0.1.4

data/lib/duck_test/frame_work/filter_set.rb

@@ -0,0 +1,233 @@
+module DuckTest
+  module FrameWork
+
+    # Data and methods that are used to filter directories and files.
+    class FilterSet
+      include LoggerHelper
+
+      attr_accessor :included
+      attr_accessor :included_dirs
+      attr_accessor :excluded
+      attr_accessor :excluded_dirs
+      attr_accessor :non_loadable
+
+      ##################################################################################
+      # Initialize a new FilterSet
+      # @return [FilterSet]
+      def initialize(options = {})
+        super()
+
+        self.included = options[:included]
+        self.included_dirs = options[:included_dirs]
+        self.excluded = options[:excluded]
+        self.excluded_dirs = options[:excluded_dirs]
+        self.non_loadable = options[:non_loadable]
+
+        return self
+      end
+
+      ##################################################################################
+      # @note You can pass a Symbol named :all instead of a Regexp and the method will always return true.  This provides the ability to specify "all" files as part of a filter.
+      # Compares a file_spec against an array of {http://www.ruby-doc.org/core-1.9.3/Regexp.html Regexp's} (filters).
+      #
+      #     match_filters?("test.rb", /^book/)               # => false
+      #
+      #     match_filters?("test.rb", [/^book/])             # => false
+      #
+      #     match_filters?("test.rb", [/^book/, /^test/])    # => true
+      #
+      #     match_filters?("test.rb", :all)                  # => true
+      #
+      #     match_filters?("test.rb", [:all])                # => true
+      #
+      # @param [String] file_spec    A file name that adheres to {http://ruby-doc.org/core-1.9.3/File.html#method-c-basename File.basename}.
+      # @param [Array] filters       An Array of {http://www.ruby-doc.org/core-1.9.3/Regexp.html Regexp's}.  Each Regexp is compared against file_spec.
+      #                              The first Regexp that matches file_spec wins and returns true, otherwise, this method returns false.
+      #                              Also, you can pass an Array with a single Symbol named :all and match_filters? will always return true.
+      # @param [String] subdirectory If file_spec is a directory, then, subdirectory will be used during the evaluations instead of file_spec.
+      # @return [Boolean] Returns true if a match is found, otherwise, false
+      def match_filters?(file_spec = nil, filters = nil, subdirectory = nil)
+
+        begin
+
+          unless file_spec.blank? || filters.blank?
+
+            ducklog.system %(FilterSet.match_filters?(#{file_spec}, #{filters}, #{subdirectory}))
+
+            filters = filters.kind_of?(Array) ? filters : [filters]
+            subdirectory = subdirectory.blank? ? "" : subdirectory
+
+            filters.each do |expression|
+
+              if expression.kind_of?(Symbol) && expression.eql?(:all)
+                ducklog.system "returning true due to :all flag"
+                return true
+
+              elsif expression.kind_of?(Regexp)
+
+                if File.directory?(file_spec)
+
+                  # blank subdirectory is allowed, because, we might be comparing against a
+                  # watch root directory.
+                  if subdirectory.blank?
+                    return true
+
+                  elsif subdirectory.match(expression)
+                    ducklog.system "returning true due to Regexp MATCH !!!!"
+                    return true
+
+                  end
+
+                elsif File.basename(file_spec).match(expression)
+                  ducklog.system "returning true due to Regexp MATCH !!!!"
+                  return true
+
+                end
+              end
+            end
+          end
+
+        rescue Exception => e
+          ducklog.exception e
+        end
+
+        ducklog.system "FilterSet.match_filters?() returning false"
+
+        return false
+      end
+
+      ##################################################################################
+      # Conveinence method that calls {FilterSet#match_filters? match_filters?} with the current value of {FilterSet#included included}
+      # - In this context, file_spec cannot be blank.
+      # - Will return true if self.included array is nil or empty.
+      # @param [String] file_spec See {FilterSet#match_filters? match_filters?}
+      # @return [Boolean] Returns true if a match is found, otherwise, false
+      def included?(file_spec)
+        ducklog.system %(FilterSet.included?(#{file_spec}, #{self.included}))
+        if file_spec.blank?
+          return false
+
+        elsif self.has_included?
+          return self.match_filters?(file_spec, self.included)
+
+        else
+          return true
+
+        end
+      end
+
+      ##################################################################################
+      # Conveinence method that determines if an {FilterSet#included included} filter exists.
+      # @return [Boolean] Returns true if the {FilterSet#included included} filters exists, otherwise, false.
+      def has_included?
+        return self.included.blank? ? false : true
+      end
+
+      ##################################################################################
+      # Conveinence method that calls {FilterSet#match_filters? match_filters?} with the current value of {FilterSet#included_dirs included_dirs}
+      # - In this context, file_spec cannot be blank.
+      # - In this context, subdirectory CAN BE blank.
+      # - Will return true if self.included_dirs array is nil or empty.
+      # @param [String] file_spec    See {FilterSet#match_filters? match_filters?}
+      # @param [String] subdirectory Subdirectory is any directory directly off of the watch root directory.  Subdirectory CAN BE blank.
+      # @return [Boolean] Returns true if a match is found, otherwise, false
+      def included_dirs?(file_spec, subdirectory)
+        ducklog.system %(FilterSet.included?(#{file_spec}, #{self.included}, #{subdirectory}))
+        if file_spec.blank?
+          return false
+
+        elsif self.has_included_dirs?
+          return self.match_filters?(file_spec, self.included_dirs, subdirectory)
+
+        else
+          return true
+
+        end
+      end
+
+      ##################################################################################
+      # Conveinence method that determines if an {FilterSet#included_dirs included_dirs} filter exists.
+      # @return [Boolean] Returns true if the {FilterSet#included_dirs included_dirs} filters exists, otherwise, false.
+      def has_included_dirs?
+        return self.included_dirs.blank? ? false : true
+      end
+
+      ##################################################################################
+      # Conveinence method that calls {FilterSet#match_filters? match_filters?} with the current value of {FilterSet#excluded excluded}
+      # - In this context, file_spec cannot be blank.
+      # - Will return true if self.excluded array is nil or empty.
+      # @param [String] file_spec See {FilterSet#match_filters? match_filters?}
+      # @return [Boolean] Returns true if a match is found, otherwise, false
+      def excluded?(file_spec)
+        ducklog.system %(FilterSet.excluded?(#{file_spec}, #{self.excluded}))
+        if file_spec.blank?
+          return false
+
+        else
+          return self.match_filters?(file_spec, self.excluded)
+
+        end
+      end
+
+      ##################################################################################
+      # Conveinence method that determines if an {FilterSet#excluded excluded} filter exists.
+      # @return [Boolean] Returns true if the {FilterSet#excluded excluded} filters exists, otherwise, false.
+      def has_excluded?
+        return self.excluded.blank? ? false : true
+      end
+
+      ##################################################################################
+      # Conveinence method that calls {FilterSet#match_filters? match_filters?} with the current value of {FilterSet#excluded_dirs excluded_dirs}
+      # - In this context, file_spec cannot be blank.
+      # - In this context, subdirectory CAN BE blank.
+      # - Will return true if self.excluded_dirs array is nil or empty.
+      # @param [String] file_spec    See {FilterSet#match_filters? match_filters?}
+      # @param [String] subdirectory Subdirectory is any directory directly off of the watch root directory.  Subdirectory CAN BE blank.
+      # @return [Boolean] Returns true if a match is found, otherwise, false
+      def excluded_dirs?(file_spec, subdirectory)
+        ducklog.system %(FilterSet.excluded_dirs?(#{file_spec}, #{self.excluded_dirs}, #{subdirectory}))
+        if file_spec.blank?
+          return false
+
+        else
+          return self.match_filters?(file_spec, self.excluded_dirs, subdirectory)
+
+        end
+      end
+
+      ##################################################################################
+      # Conveinence method that determines if an {FilterSet#excluded_dirs excluded_dirs} filter exists.
+      # @return [Boolean] Returns true if the {FilterSet#excluded_dirs excluded_dirs} filters exists, otherwise, false.
+      def has_excluded_dirs?
+        return self.excluded_dirs.blank? ? false : true
+      end
+
+      ##################################################################################
+      # Conveinence method that calls {FilterSet#match_filters? match_filters?} with the current value of {FilterSet#non_loadable non_loadable}
+      # - In this context, file_spec cannot be blank.
+      # - In this context, subdirectory CAN BE blank.
+      # - Will return true if self.non_loadable array is nil or empty.
+      # @param [String] file_spec    See {FilterSet#match_filters? match_filters?}
+      # @param [String] subdirectory Subdirectory is any directory directly off of the watch root directory.  Subdirectory CAN BE blank.
+      # @return [Boolean] Returns true if a match is found, otherwise, false
+      def non_loadable?(file_spec, subdirectory)
+        ducklog.system %(FilterSet.non_loadable?(#{file_spec}, #{self.non_loadable}, #{subdirectory}))
+        if file_spec.blank?
+          return false
+
+        else
+          return self.match_filters?(file_spec, self.non_loadable, subdirectory)
+
+        end
+      end
+
+      ##################################################################################
+      # Conveinence method that determines if an {FilterSet#non_loadable non_loadable} filter exists.
+      # @return [Boolean] Returns true if the {FilterSet#non_loadable non_loadable} filters exists, otherwise, false.
+      def has_non_loadable?
+        return self.non_loadable.blank? ? false : true
+      end
+
+    end
+  end
+end

data/lib/duck_test/frame_work/map.rb

@@ -0,0 +1,331 @@
+module DuckTest
+  # ...
+  module FrameWork
+
+    ##################################################################################
+    # {include:file:MAPS.md}
+    class Map
+      include DuckTest::ConfigHelper
+
+      # An Array of {Map} objects representing target runnables tests.
+      attr_accessor :maps
+
+      ##################################################################################
+      # Initialize a new Map.  A Map can be initialized in multiple variations.
+      # sub_directory and file_name are defaulted to nil, therefore, those values are optional.  However, the
+      # gotcha is that you cannot specify file_name without first specifying sub_directory which make the order of
+      # the arguments important.  If you omit file_name or sub_directory and file_name initialize will recognize
+      # it by checking the sub_directory and file_name arguments.  If either of them are a Hash, then, it assumes
+      # that value is the options Hash.
+      #
+      #   # normal form
+      #   Map.new(/models/, /bike/, watch_basedir: :app, runnable_basedir: :test)
+      #
+      #   # specify sub_directory and options
+      #   Map.new(/models/, watch_basedir: :app, runnable_basedir: :test)
+      #
+      #   # options only
+      #   Map.new(watch_basedir: :app, runnable_basedir: :test)
+      #
+      # Any value passed as part of the options Hash will override the preceding sub_directory or file_name value set by a normal argument.
+      # 
+      #   # specify all arguments as part of the options Hash
+      #   Map.new(sub_directory: /models/, file_name: /bike/, watch_basedir: :app, runnable_basedir: :test)
+      #
+      # Since {DuckTest::Config} uses the Map class directly for creating Map objects this feature
+      # should allow developer to create maps in the config file like the following:
+      # 
+      #   DuckTest.config do
+      #     watch "**/*" do
+      #       map /models/, /bike/
+      #     end
+      #   end
+      # 
+      # If a block is passed, it is executed against self.  Therefore, all of the instance methods are available to be called within the block.
+      #
+      #   Map.new(/^models/, /[a-z]_store/, watch_basedir: :app) do
+      #     target /^unit/, /[a-z]_spec.rb/, watch_basedir: :spec
+      #     target /^functional/, /[a-z]_controller_[a-z]/, watch_basedir: :test
+      #   end
+      # 
+      # @param [Proc, Regexp, Symbol, String] sub_directory     See {#sub_directory}
+      # @param [Proc, Regexp, Symbol, String] file_name         See {#file_name}
+      # @param [Hash] options                                   An options Hash containing values used to initialize the object.
+      # @option options [String] :file_name                     See {#file_name}
+      # @option options [String] :runnable_basedir              See {DuckTest::ConfigHelper#runnable_basedir}
+      # @option options [String] :sub_directory                 See {#sub_directory}
+      # @option options [String] :watch_basedir                 See {DuckTest::ConfigHelper#watch_basedir}
+      # @param [Block] &block                                   A standard Ruby code block.
+      # @return [Map]
+      def initialize(sub_directory = nil, file_name = nil, options = {}, &block)
+        super()
+
+        options = sub_directory.kind_of?(Hash) ? sub_directory : options
+        options = file_name.kind_of?(Hash) ? file_name : options
+
+        self.watch_basedir = options[:watch_basedir]
+
+        self.file_name file_name unless file_name.blank? || file_name.kind_of?(Hash)
+        self.file_name options[:file_name] unless options[:file_name].blank?
+
+        self.maps = [] # don't accept a maps array as a parameter
+
+        self.sub_directory sub_directory unless sub_directory.blank? || sub_directory.kind_of?(Hash)
+        self.sub_directory options[:sub_directory] unless options[:sub_directory].blank?
+
+        self.runnable_basedir = options[:runnable_basedir]
+
+        self.instance_exec(&block) if block_given?
+        return self
+      end
+
+      ##################################################################################
+      # Creates a new Map object based on options and adds it to self.  Must be called within a {#initialize} block.
+      #
+      #   # in block form
+      #   Map.new(/^models/, /[a-z]_store/, watch_basedir: :app).build do
+      #     target /^functional/, /[a-z]_controller_[a-z]/              # runnable_basedir trickles down to watch_basedir
+      #     target /^unit/, /[a-z]_spec.rb/, watch_basedir: :spec       # overrides tickled runnable_basedir
+      #   end
+      #
+      # It is important to note that the runnable_basedir is passed to the target block as watch_basedir.  This allows
+      # you to specify a runnable_basedir to the Map object and have it trickle down to all of the targets eliminating the
+      # need to specify it for every target block.  Also, {DuckTest::Config} will use this feature by allowing you to specify
+      # watch_basedir and runnable_basedir at the top of a config file and have those values be used for all mappings.
+      #
+      # @param [Hash] options  See {#initialize}
+      # @param [Block] &block  A standard Ruby code block.
+      # @return [Map] The recently created Map object.
+      def target(sub_directory = nil, file_name = nil, options = {}, &block)
+        options = sub_directory.kind_of?(Hash) ? sub_directory : options
+        options = file_name.kind_of?(Hash) ? file_name : options
+        config = {watch_basedir: self.runnable_basedir}.merge(options)
+        self.maps.push(Map.new(sub_directory, file_name, config, &block))
+        return self.maps.last
+      end
+
+      ##################################################################################
+      # @note See {Map} overview for details on how Regexp, String, Symbols are evaluated and a general understanding of mappings.
+      # Sets the current value of the file name expression.
+      # See {#file_name_match?}
+      # @param [Array, Proc, Regexp, String, Symbol] value      An expression to compare against file names.
+      #                                                         If the value is an Array, then, file_name expects the Array to contain
+      #                                                         Procs, Regexps, Strings, or Symbols and not sub-arrays.
+      # @return [Array, Proc, Regexp, String, Symbol] value     Returns the current value of the file_name expression.
+      def file_name(value = nil, &block)
+        @file_name ||= "all"
+        value = value.kind_of?(Symbol) ? value.to_s : value
+        if value.kind_of?(Array)
+          value.each_with_index {|item, index| value[index] = item.to_s if item.kind_of?(Symbol)}
+        end
+        @file_name = value unless value.blank?
+        @file_name = block if block_given?
+        return @file_name
+      end
+
+      ##################################################################################
+      # @note See {Map} overview for details on how Regexp, String, Symbols are evaluated and a general understanding of mappings.
+      # The current {#file_name} value should be an expression Proc, Regexp, or String.  This value is compared against file names
+      # retrieved from the file system based on the pattern option of {DuckTest::Config#watch}.
+      #
+      #   map = Map.new
+      #   map.file_name(/^bike/)
+      #   map.file_name_match?("bike_spec.rb")          # => true
+      #   map.file_name_match?("truck_spec.rb")         # => false
+      #
+      # @param [String] value  The file name being evaluated.  Typically, this is the source or target file name.
+      # @param [String] cargo   A value that is passed to the block if {#file_name} is a block.
+      # @return [Boolean] True if match, otherwise, false.
+      def file_name_match?(value, cargo = nil)
+        result = false
+        expressions = self.file_name.blank? ? "all" : self.file_name
+        expressions = expressions.kind_of?(Array) ? self.file_name : [self.file_name]
+
+        expressions.each do |expression|
+
+          if expression.kind_of?(Regexp)
+            result = value =~ expression
+
+          elsif expression.kind_of?(String)
+            result = value =~ /^#{expression}/ || expression.eql?("all")
+
+          elsif expression.kind_of?(Proc)
+            result = expression.call value, cargo
+
+          end
+
+          break if result
+        end
+
+        return result
+      end
+
+      ##################################################################################
+      # @note See {Map} overview for details on how Regexp, String, Symbols are evaluated and a general understanding of mappings.
+      # Sets the current value of the sub-directory expression.
+      # See {#sub_directory_match?}
+      # @param [Array, Proc, Regexp, String, Symbol] value      An expression to compare against directory names.
+      #                                                         If the value is an Array, then, sub_directory expects the Array to contain
+      #                                                         Procs, Regexps, Strings, or Symbols and not sub-arrays.
+      # @return [Array, Proc, Regexp, String, Symbol] value     Returns the current value of the sub_directory expression.
+      def sub_directory(value = nil, &block)
+        @sub_directory ||= "all"
+        value = value.kind_of?(Symbol) ? value.to_s : value
+        if value.kind_of?(Array)
+          value.each_with_index {|item, index| value[index] = item.to_s if item.kind_of?(Symbol)}
+        end
+        @sub_directory = value unless value.blank?
+        @sub_directory = block if block_given?
+        return @sub_directory
+      end
+
+      ##################################################################################
+      def match?(target)
+        value = false
+        
+        if self.match.kind_of?(Proc)
+          value = self.match.call target
+        else
+          value = self.sub_directory_match?(target[:sub_directory]) && self.file_name_match?(target[:file_name]) ? true : value
+        end
+        
+        return value
+      end
+
+      ##################################################################################
+      def match_target?(target, source)
+        value = false
+
+        if self.match.kind_of?(Proc)
+          value = self.match.call target, source
+        else
+          value = self.sub_directory_match?(target[:sub_directory]) && self.file_name_match?(target[:file_name], source[:file_name])
+        end
+
+        return value
+      end
+
+      ##################################################################################
+      def match(&block)
+        @match ||= nil
+        @match = block if block_given?
+        return @match
+      end
+
+      ##################################################################################
+      # @note See {Map} overview for details on how Regexp, String, Symbols are evaluated and a general understanding of mappings.
+      # The current {#sub_directory} value should be an expression Proc, Regexp, or String.  This value is compared against directory paths
+      # retrieved from the file system based on the pattern option of {DuckTest::Config#watch}.
+      # 
+      # Examples:
+      #
+      #   map = Map.new sub_directory: :models
+      #   map.sub_directory_match?("models")                     # => true
+      #   map.sub_directory_match?("controllers")                # => false
+      #
+      #   map = Map.new sub_directory: "models"
+      #   map.sub_directory_match?("models")                     # => true
+      #   map.sub_directory_match?("controllers")                # => false
+      #
+      #   map = Map.new sub_directory: /models/
+      #   map.sub_directory_match?("models")                     # => true
+      #   map.sub_directory_match?("controllers")                # => false
+      #
+      #   map = Map.new sub_directory: :models, watch_basedir: :app
+      #   map.sub_directory_match?("app/models")                 # => true
+      #   map.sub_directory_match?("app/models/sec")             # => true
+      #   map.sub_directory_match?("my_app/models")              # => false
+      #   map.sub_directory_match?("my_app/models/sec")          # => false
+      #   map.sub_directory_match?("app/controllers")            # => false
+      #
+      #   map = Map.new sub_directory: "models", watch_basedir: :app
+      #   map.sub_directory_match?("app/models")                 # => true
+      #   map.sub_directory_match?("app/models/sec")             # => true
+      #   map.sub_directory_match?("my_app/models")              # => false
+      #   map.sub_directory_match?("my_app/models/sec")          # => false
+      #   map.sub_directory_match?("app/controllers")            # => false
+      #
+      #   map = Map.new sub_directory: /^models/, watch_basedir: :app
+      #   map.sub_directory_match?("app/models")                 # => true
+      #   map.sub_directory_match?("app/models/sec")             # => true
+      #   map.sub_directory_match?("my_app/models")              # => false
+      #   map.sub_directory_match?("my_app/models/sec")          # => false
+      #   map.sub_directory_match?("app/controllers")            # => false
+      #
+      #   map = Map.new sub_directory: /models/, watch_basedir: :app
+      #   map.sub_directory_match?("app/models")                 # => true
+      #   map.sub_directory_match?("app/models/sec")             # => true
+      #   map.sub_directory_match?("my_app/models")              # => true
+      #   map.sub_directory_match?("my_app/models/sec")          # => true
+      #   map.sub_directory_match?("app/controllers")            # => false
+      #
+      # @param [String] value  The file name being evaluated.  Typically, this is the source or target file name.
+      # @param [String] cargo   A value that is passed to the block if {#sub_directory} is a block.
+      # @return [Boolean] True if match, otherwise, false.
+      def sub_directory_match?(value, cargo = nil)
+        result = false
+        expressions = self.sub_directory.blank? ? "all" : self.sub_directory
+        expressions = expressions.kind_of?(Array) ? self.sub_directory : [self.sub_directory]
+
+        # the value being compared via this method is expecting to be a directory
+        # possibly containing path separators.  The following expressions interrogate
+        # value for the existence of the current value of self.watch_basedir.  If it exists, then,
+        # it is removed, otherwise, value is left in tact.
+        # The reason for this is that runnable and watch definitions require a pattern
+        # to retrieve files.  The self.watch_basedir provides the developer with the conveience
+        # of not having to include the watch_basedir directory in all of the mappings.
+        # see the description and examples under the watch_basedir method.
+
+        # first look for watch_basedir with SEPARATOR appended to it: "models/"
+        unless self.watch_basedir.blank?
+          if value =~ /^#{%(#{self.watch_basedir}#{File::SEPARATOR})}/
+            value = value.gsub(%(#{self.watch_basedir}#{File::SEPARATOR}), "")
+
+          elsif value =~ /^#{self.watch_basedir}/
+            value = value.gsub(self.watch_basedir, "")
+
+          end
+        end
+
+        expressions.each do |expression|
+
+          if expression.kind_of?(Regexp)
+            result = value =~ expression
+
+          elsif expression.kind_of?(String)
+            result = value =~ /^#{expression}/ || expression.eql?("all")
+
+          elsif expression.kind_of?(Proc)
+            result = expression.call value, cargo
+
+          end
+
+          break if result
+        end
+
+        return result
+      end
+
+      ##################################################################################
+      # Determines if the current {Map} object is valid by examining the sub_directory and file_name values.
+      # Both value must not be nil to be valid.
+      # @return [Boolean] Returns true if valid, otherwise, false
+      def valid?
+        return !self.sub_directory.blank? && !self.file_name.blank?
+      end
+
+      ##################################################################################
+      # ...
+      def to_s(margin = "")
+        buffer = ""
+        self.maps.each do |item|
+          buffer = "\r\n#{margin}  maps:" if buffer.blank?
+          buffer += "\r\n#{margin}#{item.to_s('  ')}"
+        end
+        buffer_basedir = self.watch_basedir.blank? ? "" : self.watch_basedir.ljust(15)
+        return "\r\n#{margin}watch_basedir: #{buffer_basedir} runnable_basedir: #{self.runnable_basedir}\r\n#{margin}sub_directory: #{self.sub_directory} file_name: #{self.file_name}#{buffer}"
+      end
+
+    end
+  end
+end