super_diff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a67c51aa528c0539aca579800b31aafc363fb85f532ba9a07723e073a2efb050
+  data.tar.gz: 593449f1083f6a121b51bc74b30c78682f48b9f55e28335613b0babdbde0d4b0
+SHA512:
+  metadata.gz: 867861728306a60b4ce417ac81836b933f6e5a6f36c27aa8dbe1735c3fd269a240c3901c2fa8cbec4158a65196053e0243da82d2c83567c8c5db12d6cb1b8627
+  data.tar.gz: 9148ff70d4edc39116fcd00100e5ab7cd3579c13f17eb6920ab6ba047df1e0dc02389b4600bfadd6ea7f73f686dc4881ff05d994c9574f4a97d04c13556eef09

data/README.md

@@ -0,0 +1,174 @@
+# SuperDiff [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge] [![Hound][hound-badge]][hound]
+
+[version-badge]: http://img.shields.io/gem/v/super_diff.svg
+[rubygems]: http://rubygems.org/gems/super_diff
+[travis-badge]: http://img.shields.io/travis/mcmire/super_diff/master.svg
+[travis]: http://travis-ci.org/mcmire/super_diff
+[downloads-badge]: http://img.shields.io/gem/dtv/super_diff.svg
+[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
+[hound]: https://houndci.com
+
+## Concept
+
+SuperDiff is a utility that helps you diff two complex data structures in Ruby
+and gives you helpful output to show you exactly how the two data structures
+differ.
+
+Let's say you have two hashes and you want to compare them. Perhaps your first
+hash looks like this:
+
+``` ruby
+expected = {
+  customer: {
+    name: "Marty McFly",
+    shipping_address: {
+      line_1: "123 Main St.",
+      city: "Hill Valley",
+      state: "CA",
+      zip: "90382",
+    },
+  },
+  items: [
+    {
+      name: "Fender Stratocaster",
+      cost: 100_000,
+      options: ["red", "blue", "green"],
+    },
+    { name: "Chevy 4x4" },
+  ],
+}
+```
+
+and your second hash looks like this:
+
+``` ruby
+actual = {
+  customer: {
+    name: "Marty McFly, Jr.",
+    shipping_address: {
+      line_1: "456 Ponderosa Ct.",
+      city: "Hill Valley",
+      state: "CA",
+      zip: "90382",
+    },
+  },
+  items: [
+    {
+      name: "Fender Stratocaster",
+      cost: 100_000,
+      options: ["red", "blue", "green"],
+    },
+    { name: "Mattel Hoverboard" },
+  ],
+}
+```
+
+If you want to know what the difference between them is, you could say:
+
+``` ruby
+SuperDiff::EqualityMatcher.call(expected, actual)
+```
+
+This will give you the following string:
+
+```
+Differing hashes.
+
+Expected: { customer: { name: "Marty McFly", shipping_address: { line_1: "123 Main St.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Chevy 4x4" }] }
+Got: { customer: { name: "Marty McFly, Jr.", shipping_address: { line_1: "456 Ponderosa Ct.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Mattel Hoverboard" }] }
+
+Diff:
+
+  {
+    customer: {
+-     name: "Marty McFly",
++     name: "Marty McFly, Jr.",
+      shipping_address: {
+-       line_1: "123 Main St.",
++       line_1: "456 Ponderosa Ct.",
+        city: "Hill Valley",
+        state: "CA",
+        zip: "90382"
+      }
+    },
+    items: [
+      {
+        name: "Fender Stratocaster",
+        cost: 100000,
+        options: ["red", "blue", "green"]
+      },
+      {
+-       name: "Chevy 4x4"
++       name: "Mattel Hoverboard"
+      }
+    ]
+  }
+```
+
+When printed to a terminal, this will display in color, so the "expected" value
+in the summary and deleted lines in the diff will appear in red, while the
+"actual" value in the summary and inserted lines in the diff will appear in
+green.
+
+By the way, SuperDiff doesn't just work with hashes, but arrays as well as other
+objects, too!
+
+## Usage
+
+There are two ways to use this gem. One way is to use the API methods that this
+gem provides, such as the method presented above.
+
+However, this gem was really designed for use specifically with RSpec. In recent
+years, RSpec has added a feature where if you're comparing two objects in a test
+and your test fails, you will see a diff between those objects (provided the
+objects are large enough). However, this diff is not always the most helpful.
+It's very common when writing tests for API endpoints to work with giant JSON
+hashes, and RSpec's diffs are not sufficient in highlighting changes between
+such structures. Therefore, this gem provides an integration layer where you can
+replace RSpec's differ with SuperDiff.
+
+To get started, add the gem to your Gemfile under the `test` group:
+
+``` ruby
+gem "super_diff"
+```
+
+Then, open up `spec_helper` and add this line somewhere:
+
+``` ruby
+require "super_diff/rspec"
+```
+
+Now try writing a test using `eq` to compare two large data structures, and you
+should see a diff similar to the one given above.
+
+## Contributing
+
+If you encounter a bug or have an idea for how this could be better, I'm all
+ears! Feel free to create an issue.
+
+If you'd like to submit a PR instead, here's how to get started. First, fork
+this repo and then run:
+
+```
+bundle install
+```
+
+This will install dependencies. From here you can run all of the tests:
+
+```
+bundle exec rake
+```
+
+Or a single test:
+
+```
+bundle exec rspec spec/acceptance/...
+bundle exec rspec spec/unit/...
+```
+
+Finally, submit your PR and I'll take a look at it when I get a chance.
+
+## Copyright/License
+
+© 2018 Elliot Winkler, released under the [MIT license](LICENSE).

data/lib/super_diff/csi/color_helper.rb

@@ -0,0 +1,52 @@
+module SuperDiff
+  module Csi
+    module ColorHelper
+      BLACK = Csi::FourBitColor.new(:white)
+      # LIGHT_RED = Csi::TwentyFourBitColor.new(r: 63, g: 32, b: 32)
+      LIGHT_RED = Csi::TwentyFourBitColor.new(r: 73, g: 62, b: 71)
+      # RED = Csi::TwentyFourBitColor.new(r: 110, g: 56, b: 56)
+      # RED = Csi::TwentyFourBitColor.new(r: 116, g: 78, b: 84)
+      RED = Csi::FourBitColor.new(:red)
+      # LIGHT_GREEN = Csi::TwentyFourBitColor.new(r: 40, g: 48, b: 39)
+      LIGHT_GREEN = Csi::TwentyFourBitColor.new(r: 51, g: 81, b: 81)
+      # GREEN = Csi::TwentyFourBitColor.new(r: 73, g: 87, b: 71)
+      # GREEN = Csi::TwentyFourBitColor.new(r: 81, g: 115, b: 105)
+      GREEN = Csi::FourBitColor.new(:green)
+      DARK_GREY = Csi::TwentyFourBitColor.new(r: 134, g: 147, b: 149)
+
+      def self.plain(text)
+        text
+      end
+
+      def self.line(given_text = "")
+        if block_given?
+          text = ""
+          yield text
+          text + "\n"
+        else
+          given_text + "\n"
+        end
+      end
+
+      def self.light_red_bg(text)
+        Csi.colorize(text, fg: BLACK, bg: LIGHT_RED)
+      end
+
+      def self.red(text)
+        Csi.colorize(text, fg: RED)
+      end
+
+      def self.light_green_bg(text)
+        Csi.colorize(text, fg: BLACK, bg: LIGHT_GREEN)
+      end
+
+      def self.green(text)
+        Csi.colorize(text, fg: GREEN)
+      end
+
+      def self.dark_grey(text)
+        Csi.colorize(text, fg: BLACK, bg: DARK_GREY)
+      end
+    end
+  end
+end

data/lib/super_diff/csi/eight_bit_color.rb

@@ -0,0 +1,131 @@
+module SuperDiff
+  module Csi
+    class EightBitColor
+      VALID_COMPONENT_RANGE = 0..6
+      VALID_CODE_RANGE = 0..255
+      VALID_CODES_BY_NAME = {
+        black: 0,
+        red: 1,
+        green: 2,
+        yellow: 3,
+        blue: 4,
+        magenta: 5,
+        cyan: 6,
+        white: 7,
+        bright_black: 8,
+        bright_red: 9,
+        bright_green: 10,
+        bright_yellow: 11,
+        bright_blue: 12,
+        bright_magenta: 13,
+        bright_cyan: 14,
+        bright_white: 15,
+      }.freeze
+      STARTING_INDICES = {
+        standard: 0,
+        high_intensity: 8,
+        grayscale: 232,
+      }.freeze
+      VALID_PAIR_TYPES = STARTING_INDICES.keys
+      VALID_PAIR_INDEX_RANGES = {
+        standard: 0..7,
+        high_intensity: 0..7,
+        grayscale: 0..23,
+      }.freeze
+      LEADING_CODES_BY_LAYER = { fg: 38, bg: 48 }.freeze
+      SERIAL_CODE = 5
+
+      def initialize(value)
+        @code =
+          case value
+          when Hash
+            interpret_triplet!(value)
+          when Symbol
+            interpret_color_name!(value)
+          when Array
+            interpret_pair!(value)
+          else
+            interpret_code!(value)
+          end
+      end
+
+      def sequence_for(layer)
+        leading_code = LEADING_CODES_BY_LAYER.fetch(layer)
+        "\e[#{leading_code};#{SERIAL_CODE};#{code}m"
+      end
+
+      private
+
+      attr_reader :code
+
+      def interpret_triplet!(spec)
+        unless spec.include?(:r) && spec.include?(:g) && spec.include?(:b)
+          raise ArgumentError.new(
+            "#{spec.inspect} is not a valid color specification. " +
+            "Please provide a hash with :r, :g, and :b keys.",
+          )
+        end
+
+        if spec.values.none? { |component| VALID_COMPONENT_RANGE.cover?(component) }
+          raise ArgumentError.new(
+            "(#{spec[:r]},#{spec[:g]},#{spec[:b]}) is not a valid color " +
+            "specification. All components must be between " +
+            "#{VALID_COMPONENT_RANGE.begin} and #{VALID_COMPONENT_RANGE.end}.",
+          )
+        end
+
+        16 + 36 * spec[:r] + 6 * spec[:g] + spec[:b]
+      end
+
+      def interpret_color_name!(name)
+        if !VALID_CODES_BY_NAME.include?(name)
+          message =
+            "#{name.inspect} is not a valid color name.\n" +
+            "Valid names are:\n"
+
+          VALID_CODES_BY_NAME.keys.each do |valid_name|
+            message << "- #{valid_name}\n"
+          end
+
+          raise ArgumentError.new(message)
+        end
+
+        VALID_CODES_BY_NAME[name]
+      end
+
+      def interpret_pair!(pair)
+        type, index = pair
+
+        if !VALID_PAIR_TYPES.include?(type)
+          raise ArgumentError.new(
+            "Given pair did not have a valid type. " +
+            "Type must be one of: #{VALID_PAIR_TYPES}",
+          )
+        end
+
+        valid_range = VALID_PAIR_INDEX_RANGES[type]
+
+        if !valid_range.cover?(index)
+          raise ArgumentError.new(
+            "Given pair did not have a valid index. " +
+            "For #{type}, index must be between #{valid_range.begin} and " +
+            "#{valid_range.end}.",
+          )
+        end
+
+        STARTING_INDICES[type] + index
+      end
+
+      def interpret_code!(code)
+        if !VALID_CODE_RANGE.cover?(code)
+          raise ArgumentError.new(
+            "#{code.inspect} is not a valid color code " +
+            "(must be between 0 and 255).",
+          )
+        end
+
+        code
+      end
+    end
+  end
+end

data/lib/super_diff/csi/eight_bit_sequence.rb

@@ -0,0 +1,27 @@
+module SuperDiff
+  module Csi
+    class EightBitSequence
+      LEADING_CODES = { fg: 38, bg: 48 }.freeze
+      SERIAL_CODE = 5
+
+      def initialize(fg: nil, bg: nil)
+        @fg = fg
+        @bg = bg
+      end
+
+      def to_s
+        [sequence_for(:fg, fg), sequence_for(:bg, bg)].compact.join
+      end
+
+      private
+
+      attr_reader :fg, :bg
+
+      def sequence_for(type, color)
+        if color
+          "\e[#{LEADING_CODES.fetch(type)};#{SERIAL_CODE};#{color.code}m"
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/csi/four_bit_color.rb

@@ -0,0 +1,80 @@
+module SuperDiff
+  module Csi
+    class FourBitColor
+      VALID_TYPES = [:fg, :bg].freeze
+      VALID_CODES_BY_NAME = {
+        black: { fg: 30, bg: 40 },
+        red: { fg: 31, bg: 41 },
+        green: { fg: 32, bg: 42 },
+        yellow: { fg: 33, bg: 43 },
+        blue: { fg: 34, bg: 44 },
+        magenta: { fg: 35, bg: 45 },
+        cyan: { fg: 36, bg: 46 },
+        white: { fg: 37, bg: 47 },
+        bright_black: { fg: 90, bg: 100 },
+        bright_red: { fg: 91, bg: 101 },
+        bright_green: { fg: 92, bg: 102 },
+        bright_yellow: { fg: 93, bg: 103 },
+        bright_blue: { fg: 94, bg: 104 },
+        bright_magenta: { fg: 95, bg: 105 },
+        bright_cyan: { fg: 96, bg: 106 },
+        bright_white: { fg: 97, bg: 107 },
+      }.freeze
+      NAMES_BY_CODE = VALID_CODES_BY_NAME.reduce({}) do |hash, (key, value)|
+        hash.merge(value[:fg] => key, value[:bg] => key)
+      end
+      VALID_NAMES = VALID_CODES_BY_NAME.keys
+      VALID_CODE_RANGES = [30..37, 40..47, 90..97, 100..107].freeze
+
+      def initialize(value)
+        @name =
+          if value.is_a?(Symbol)
+            interpret_name!(value)
+          else
+            interpret_code!(value)
+          end
+      end
+
+      def sequence_for(layer)
+        code = VALID_CODES_BY_NAME.fetch(name).fetch(layer)
+        "\e[#{code}m"
+      end
+
+      private
+
+      attr_reader :name
+
+      def interpret_name!(name)
+        if !VALID_NAMES.include?(name)
+          message =
+            "#{name.inspect} is not a valid color name.\n" +
+            "Valid names are:\n"
+
+          VALID_NAMES.each do |valid_name|
+            message << "- #{valid_name}"
+          end
+
+          raise ArgumentError.new(message)
+        end
+
+        name
+      end
+
+      def interpret_code!(code)
+        if VALID_CODE_RANGES.none? { |range| range.cover?(code) }
+          message =
+            "#{code.inspect} is not a valid color code.\n" +
+            "Valid codes are:\n"
+
+          VALID_CODE_RANGES.each do |range|
+            message << "- #{range.begin} through #{range.end}\n"
+          end
+
+          raise ArgumentError.new(message)
+        end
+
+        NAMES_BY_CODE.fetch(code)
+      end
+    end
+  end
+end

data/lib/super_diff/csi/four_bit_sequence.rb

@@ -0,0 +1,24 @@
+module SuperDiff
+  module Csi
+    class FourBitSequence
+      def initialize(fg: nil, bg: nil)
+        @fg = fg
+        @bg = bg
+      end
+
+      def to_s
+        [sequence_for(fg), sequence_for(bg)].compact.join
+      end
+
+      private
+
+      attr_reader :fg, :bg
+
+      def sequence_for(color)
+        if color
+          "\e[#{color.code}m"
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/csi/reset_sequence.rb

@@ -0,0 +1,9 @@
+module SuperDiff
+  module Csi
+    class ResetSequence
+      def to_s
+        "\e[0m"
+      end
+    end
+  end
+end

data/lib/super_diff/csi/sequence.rb

@@ -0,0 +1,22 @@
+module SuperDiff
+  module Csi
+    module Sequence
+      def self.for(color)
+        case color
+        when :reset
+          Csi::ResetSequence.new
+        when FourBitColor
+          Csi::FourBitSequence.new(color)
+        when EightBitColor
+          Csi::EightBitSequence.new(color)
+        when TwentyFourBitColor
+          Csi::TwentyFourBitSequence.new(color)
+        else
+          raise ArgumentError.new(
+            "Don't know how to interpret color: #{color.inspect}",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/csi/twenty_four_bit_color.rb

@@ -0,0 +1,41 @@
+module SuperDiff
+  module Csi
+    class TwentyFourBitColor
+      VALID_COMPONENT_RANGE = 0..255
+      LEADING_CODES_BY_LAYER = { fg: 38, bg: 48 }.freeze
+      SERIAL_CODE = 2
+
+      def initialize(value)
+        @code = interpret_triplet!(value)
+      end
+
+      def sequence_for(layer)
+        leading_code = LEADING_CODES_BY_LAYER.fetch(layer)
+        "\e[#{leading_code};#{SERIAL_CODE};#{code}m"
+      end
+
+      private
+
+      attr_reader :code
+
+      def interpret_triplet!(spec)
+        if !spec.include?(:r) || !spec.include?(:g) || !spec.include?(:b)
+          raise ArgumentError.new(
+            "#{spec.inspect} is not a valid color specification. " +
+            "Please provide a hash with :r, :g, and :b keys.",
+          )
+        end
+
+        if spec.values.any? { |component| !VALID_COMPONENT_RANGE.cover?(component) }
+          raise ArgumentError.new(
+            "(#{spec[:r]},#{spec[:g]},#{spec[:b]}) is not a valid color " +
+            "specification. All components must be between " +
+            "#{VALID_COMPONENT_RANGE.begin} and #{VALID_COMPONENT_RANGE.end}.",
+          )
+        end
+
+        "#{spec[:r]};#{spec[:g]};#{spec[:b]}"
+      end
+    end
+  end
+end

data/lib/super_diff/csi/twenty_four_bit_sequence.rb

@@ -0,0 +1,27 @@
+module SuperDiff
+  module Csi
+    class TwentyFourBitSequence
+      LEADING_CODES = { fg: 38, bg: 48 }.freeze
+      SERIAL_CODE = 2
+
+      def initialize(fg: nil, bg: nil)
+        @fg = fg
+        @bg = bg
+      end
+
+      def to_s
+        [sequence_for(:fg, fg), sequence_for(:bg, bg)].compact.join
+      end
+
+      private
+
+      attr_reader :fg, :bg
+
+      def sequence_for(type, color)
+        if color
+          "\e[#{LEADING_CODES.fetch(type)};#{SERIAL_CODE};#{color.code}m"
+        end
+      end
+    end
+  end
+end

data/lib/super_diff/csi.rb

@@ -0,0 +1,29 @@
+require_relative "csi/reset_sequence"
+
+# Source: <https://en.wikipedia.org/wiki/ANSI_escape_code>
+module SuperDiff
+  module Csi
+    def self.reset_sequence
+      ResetSequence.new
+    end
+
+    def self.colorize(text, fg: nil, bg: nil)
+      parts = []
+
+      if fg
+        parts << fg.sequence_for(:fg)
+      end
+
+      if bg
+        parts << bg.sequence_for(:bg)
+      end
+
+      (parts + [text, reset_sequence]).join
+    end
+  end
+end
+
+require_relative "csi/four_bit_color"
+require_relative "csi/eight_bit_color"
+require_relative "csi/twenty_four_bit_color"
+require_relative "csi/color_helper"

data/lib/super_diff/diff_formatter.rb

@@ -0,0 +1,37 @@
+module SuperDiff
+  class DiffFormatter
+    def self.call(*args)
+      new(*args).call
+    end
+
+    def initialize(
+      operations,
+      indent_level:,
+      add_comma: false,
+      extra_classes: []
+    )
+      @operations = operations
+      @indent_level = indent_level
+      @add_comma = add_comma
+      @extra_classes = extra_classes
+    end
+
+    def call
+      resolved_class.call(
+        operations,
+        indent_level: indent_level,
+        add_comma: add_comma,
+      )
+    end
+
+    private
+
+    attr_reader :operations, :indent_level, :add_comma, :extra_classes
+
+    def resolved_class
+      (DiffFormatters::DEFAULTS + extra_classes).find do |klass|
+        klass.applies_to?(operations)
+      end
+    end
+  end
+end

data/lib/super_diff/diff_formatters/array.rb

@@ -0,0 +1,21 @@
+module SuperDiff
+  module DiffFormatters
+    class Array < Base
+      def self.applies_to?(operations)
+        operations.is_a?(OperationSequences::Array)
+      end
+
+      def call
+        Collection.call(
+          open_token: "[",
+          close_token: "]",
+          collection_prefix: collection_prefix,
+          build_item_prefix: proc { "" },
+          operations: operations,
+          indent_level: indent_level,
+          add_comma: add_comma?,
+        )
+      end
+    end
+  end
+end