check_please 0.4.1 → 0.5.0

data/lib/check_please/comparison.rb

@@ -42,23 +42,84 @@ module CheckPlease
       end
 
       def compare_arrays(ref_array, can_array, path)
-        max_len = [ ref_array, can_array ].map(&:length).max
-        (0...max_len).each do |i|
-          n = i + 1 # count in human pls
-          new_path = path + n
-
-          ref = ref_array[i]
-          can = can_array[i]
-
-          case
-          when ref_array.length < n ; record_diff ref, can, new_path, :extra
-          when can_array.length < n ; record_diff ref, can, new_path, :missing
-          else
-            compare ref, can, new_path
-          end
+        if ( key = path.key_for_compare(flags) )
+          compare_arrays_by_key ref_array, can_array, path, key
+        else
+          compare_arrays_by_index ref_array, can_array, path
         end
       end
 
+        def compare_arrays_by_key(ref_array, can_array, path, key_name)
+          refs_by_key = index_array!(ref_array, path, key_name, "reference")
+          cans_by_key = index_array!(can_array, path, key_name, "candidate")
+          key_values = (refs_by_key.keys | cans_by_key.keys)
+
+          key_values.compact! # NOTE: will break if nil is ever used as a key (but WHO WOULD DO THAT?!)
+          key_values.sort!
+
+          key_values.each do |key_value|
+            new_path = path + "#{key_name}=#{key_value}"
+            ref = refs_by_key[key_value]
+            can = cans_by_key[key_value]
+            case
+            when ref.nil? ; record_diff ref, can, new_path, :extra
+            when can.nil? ; record_diff ref, can, new_path, :missing
+            else          ; compare ref, can, new_path
+            end
+          end
+        end
+
+          def index_array!(array_of_hashes, path, key_name, ref_or_can)
+            elements_by_key = {}
+
+            array_of_hashes.each.with_index do |h, i|
+              # make sure we have a hash
+              unless h.is_a?(Hash)
+                raise CheckPlease::TypeMismatchError, \
+                  "The element at position #{i} in the #{ref_or_can} array is not a hash."
+              end
+
+              # try to get the value of the attribute identified by key_name
+              key_value = h.fetch(key_name) {
+                raise CheckPlease::NoSuchKeyError, \
+                  <<~EOF
+                    The #{ref_or_can} hash at position #{i} has no #{key_name.inspect} key.
+                    Keys it does have: #{h.keys.inspect}
+                  EOF
+              }
+
+              # complain about dupes
+              if elements_by_key.has_key?(key_value)
+                key_val_expr = "#{key_name}=#{key_value}"
+                raise CheckPlease::DuplicateKeyError, \
+                  "Duplicate #{ref_or_can} element found at path '#{path + key_val_expr}'."
+              end
+
+              # ok, now we can proceed
+              elements_by_key[key_value] = h
+            end
+
+            elements_by_key
+          end
+
+        def compare_arrays_by_index(ref_array, can_array, path)
+          max_len = [ ref_array, can_array ].map(&:length).max
+          (0...max_len).each do |i|
+            n = i + 1 # count in human pls
+            new_path = path + n
+
+            ref = ref_array[i]
+            can = can_array[i]
+
+            case
+            when ref_array.length < n ; record_diff ref, can, new_path, :extra
+            when can_array.length < n ; record_diff ref, can, new_path, :missing
+            else
+              compare ref, can, new_path
+            end
+          end
+        end
+
       def compare_hashes(ref_hash, can_hash, path)
         record_missing_keys ref_hash, can_hash, path
         compare_common_keys ref_hash, can_hash, path

data/lib/check_please/diffs.rb

@@ -47,6 +47,10 @@ module CheckPlease
       @list.map(&:attributes)
     end
 
+    def to_s(flags = {})
+      CheckPlease::Printers.render(self, flags)
+    end
+
     extend Forwardable
     def_delegators :@list, *%i[
       each

data/lib/check_please/error.rb

@@ -6,8 +6,28 @@ module CheckPlease
     # instead....
   end
 
+  class DuplicateKeyError < ::IndexError
+    include CheckPlease::Error
+  end
+
   class InvalidFlag < ArgumentError
     include CheckPlease::Error
   end
 
+  class InvalidPath < ArgumentError
+    include CheckPlease::Error
+  end
+
+  class InvalidPathSegment < ArgumentError
+    include CheckPlease::Error
+  end
+
+  class NoSuchKeyError < ::KeyError
+    include CheckPlease::Error
+  end
+
+  class TypeMismatchError < ::TypeError
+    include CheckPlease::Error
+  end
+
 end

data/lib/check_please/flag.rb

@@ -29,12 +29,22 @@ module CheckPlease
       @coercer = block
     end
 
+    def description=(value)
+      if value.is_a?(String) && value =~ /\n/m
+        lines = value.lines
+      else
+        lines = Array(value).map(&:to_s)
+      end
+
+      @description = lines.map(&:rstrip)
+    end
+
     def mutually_exclusive_to(flag_name)
       @validators << ->(flags, _) { flags.send(flag_name).empty? }
     end
 
-    def reentrant
-      @reentrant = true
+    def repeatable
+      @repeatable = true
       self.default_proc = ->{ Array.new }
     end
 
@@ -47,7 +57,7 @@ module CheckPlease
     def __set__(value, on:, flags:)
       val = _coerce(value)
       _validate(flags, val)
-      if @reentrant
+      if @repeatable
         on[name] ||= []
         on[name].concat(Array(val))
       else

data/lib/check_please/path.rb

@@ -1,29 +1,74 @@
 module CheckPlease
 
+  # TODO: this class is getting a bit large; maybe split out some of the stuff that uses flags?
   class Path
+    include CheckPlease::Reification
+    can_reify String, Symbol, Numeric, nil
+
     SEPARATOR = "/"
 
     def self.root
-      new
+      new('/')
     end
 
-    attr_reader :to_s
-    def initialize(segments = [])
+
+
+    attr_reader :to_s, :segments
+    def initialize(name_or_segments = [])
+      case name_or_segments
+      when String, Symbol, Numeric, nil
+        names = name_or_segments.to_s.split(SEPARATOR)
+        names.shift until names.empty? || names.first =~ /\S/
+        segments = PathSegment.reify(names)
+      when Array
+        segments = PathSegment.reify(name_or_segments)
+      else
+        raise InvalidPath, "not sure what to do with #{name_or_segments.inspect}"
+      end
+
+      if segments.any?(&:empty?)
+        raise InvalidPath, "#{self.class.name} cannot contain empty segments"
+      end
+
       @segments = Array(segments)
+
       @to_s = SEPARATOR + @segments.join(SEPARATOR)
       freeze
+    rescue InvalidPathSegment => e
+      raise InvalidPath, e.message
     end
 
     def +(new_basename)
-      self.class.new( Array(@segments) + Array(new_basename.to_s) )
+      new_segments = self.segments.dup
+      new_segments << new_basename # don't reify here; it'll get done on Path#initialize
+      self.class.new(new_segments)
+    end
+
+    def ==(other)
+      self.to_s == other.to_s
+    end
+
+    def ancestors
+      list = []
+      p = self
+      loop do
+        break if p.root?
+        p = p.parent
+        list.unshift p
+      end
+      list.reverse
+    end
+
+    def basename
+      segments.last.to_s
     end
 
     def depth
-      1 + @segments.length
+      1 + segments.length
     end
 
     def excluded?(flags)
-      return false if root?
+      return false if root? # that would just be silly
 
       return true if too_deep?(flags)
       return true if explicitly_excluded?(flags)
@@ -33,33 +78,95 @@ module CheckPlease
     end
 
     def inspect
-      "<CheckPlease::Path '#{to_s}'>"
+      "<#{self.class.name} '#{to_s}'>"
+    end
+
+		# TODO: Naming Things
+    def key_for_compare(flags)
+      mbk_exprs = unpack_mbk_exprs(flags)
+      matches = mbk_exprs.select { |mbk_expr|
+        # NOTE: matching on parent because MBK '/foo/:id' should return 'id' for path '/foo'
+        mbk_expr.parent.match?(self)
+      }
+
+      case matches.length
+      when 0 ; nil
+      when 1 ; matches.first.segments.last.key
+      else   ; raise "More than one match_by_key expression for path '#{self}': #{matches.map(&:to_s).inspect}"
+      end
+    end
+
+    def match?(path_or_string)
+      # If the strings are literally equal, we're good..
+      return true if self == path_or_string
+
+      # Otherwise, compare segments: do we have the same number, and do they all #match?
+      other = reify(path_or_string)
+      return false if other.depth != self.depth
+
+      seg_pairs = self.segments.zip(other.segments)
+      seg_pairs.all? { |a, b| a.match?(b) }
+    end
+
+    def parent
+      return nil if root? # TODO: consider the Null Object pattern
+      self.class.new(segments[0..-2])
     end
 
     def root?
-      to_s == SEPARATOR
+      @segments.empty?
     end
 
     private
 
+    # O(n^2) check to see if any of the path's ancestors are on a list
+    # (as of this writing, this should never actually happen, but I'm being thorough)
+    def ancestor_on_list?(paths)
+      paths.any? { |path|
+        ancestors.any? { |ancestor| ancestor == path }
+      }
+    end
+
     def explicitly_excluded?(flags)
-      flags.reject_paths.any?( &method(:match?) )
+      return false if flags.reject_paths.empty?
+      return true if self_on_list?(flags.reject_paths)
+      return true if ancestor_on_list?(flags.reject_paths)
+      false
     end
 
     def implicitly_excluded?(flags)
       return false if flags.select_paths.empty?
-      flags.select_paths.none?( &method(:match?) )
+      return false if self_on_list?(flags.select_paths)
+      return false if ancestor_on_list?(flags.select_paths)
+      true
+    end
+
+    # A path of "/foo/:id/bar/:name" has two key expressions:
+    # - "/foo/:id"
+    # - "/foo/:id/bar/:name"
+    def key_exprs
+      ( [self] + ancestors )
+        .reject { |path| path.root? }
+        .select { |path| path.segments.last&.key_expr? }
     end
 
-    # leaving this here for a while in case it needs to grow into a public method
-    def match?(path_expr)
-      to_s.include?(path_expr)
+    # O(n) check to see if the path itself is on a list
+    def self_on_list?(paths)
+      paths.any? { |path| self == path }
     end
 
     def too_deep?(flags)
       return false if flags.max_depth.nil?
-      flags.max_depth + 1 < depth
+      depth > flags.max_depth
     end
+
+    def unpack_mbk_exprs(flags)
+      flags.match_by_key
+        .map { |path| path.send(:key_exprs) }
+        .flatten
+        .uniq { |e| e.to_s } # use the block form so we don't have to implement #hash and #eql? in horrible ways
+    end
+
   end
 
 end

data/lib/check_please/path_segment.rb

@@ -0,0 +1,88 @@
+module CheckPlease
+
+  class PathSegment
+    include CheckPlease::Reification
+    can_reify String, Symbol, Numeric, nil
+
+    KEY_EXPR = %r{
+      ^
+      \:       # a literal colon
+      (        # capture key
+        [^\:]+ # followed by one or more things that aren't colons
+      )        # end capture key
+      $
+    }x
+
+    KEY_VAL_EXPR = %r{
+      ^
+      (       # capture key
+        [^=]+ # stuff (just not an equal sign)
+      )       # end capture key
+      \=      # an equal sign
+      (       # capture key value
+        [^=]+ # stuff (just not an equal sign)
+      )       # end capture key value
+      $
+    }x
+
+    attr_reader :name, :key, :key_value
+    alias_method :to_s, :name
+
+    def initialize(name = nil)
+      @name = name.to_s.strip
+      if @name =~ %r(\s) # has any whitespace
+        raise InvalidPathSegment, <<~EOF
+          #{name.inspect} is not a valid #{self.class} name
+        EOF
+      end
+      parse_key_and_value
+      freeze
+    end
+
+    def empty?
+      name.empty?
+    end
+
+    def key_expr?
+      name.match?(KEY_EXPR)
+    end
+
+    def key_val_expr?
+      name.match?(KEY_VAL_EXPR)
+    end
+
+    def match?(other_segment_or_string)
+      other = self.class.reify(other_segment_or_string)
+
+      match_types = [ self.match_type, other.match_type ]
+      case match_types
+      when [ :plain,     :plain     ] ; self.name == other.name
+      when [ :key,       :key_value ] ; self.key  == other.key
+      when [ :key_value, :key       ] ; self.key  == other.key
+      else                            ; false
+      end
+    end
+
+    protected
+
+    def match_type
+      return :key       if key_expr?
+      return :key_value if key_val_expr?
+      :plain
+    end
+
+    private
+
+    def parse_key_and_value
+      case name
+      when KEY_EXPR
+        @key = $1
+      when KEY_VAL_EXPR
+        @key, @key_value = $1, $2
+      else
+        # :nothingtodohere:
+      end
+    end
+  end
+
+end

data/lib/check_please/reification.rb

@@ -0,0 +1,50 @@
+module CheckPlease
+
+  module Reification
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+      receiver.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      def reifiable
+        @_reifiable ||= []
+      end
+
+      def can_reify(*klasses)
+        klasses.flatten!
+
+        unless ( klasses - [nil] ).all? { |e| e.is_a?(Class) }
+          raise ArgumentError, "classes (or nil) only, please"
+        end
+
+        reifiable.concat klasses
+        reifiable.uniq!
+        nil
+      end
+
+      def reify(primitive_or_object)
+        case primitive_or_object
+        when self       ; return primitive_or_object
+        when Array      ; return primitive_or_object.map { |e| reify(e) }
+        when *reifiable ; return new(primitive_or_object)
+        end
+        # note early return ^^^
+
+        # that didn't work? complain!
+        acceptable = reifiable.map { |e| Class === e ? e.name : e.inspect }
+        raise ArgumentError, <<~EOF
+          #{self}.reify was given: #{primitive_or_object.inspect}
+          but only accepts: #{acceptable.join(", ")}
+        EOF
+      end
+    end
+
+    module InstanceMethods
+      def reify(x)
+        self.class.reify(x)
+      end
+    end
+  end
+
+end