super_diff 0.1.0 → 0.2.0

checksums.yaml

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

data/README.md

@@ -3,158 +3,161 @@
 [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 Ruby gem that intelligently displays the differences between two
+data structures of any type.
+
+📢 **[See what's changed in the latest version (0.2.0)][changelog].**
+
+[changelog]: CHANGELOG.md
 
-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.
+## Introduction
 
-Let's say you have two hashes and you want to compare them. Perhaps your first
-hash looks like this:
+The primary motivation behind this gem is to replace RSpec's built-in diffing
+capabilities. Sometimes, whenever you use a matcher such as `eq`, `match`,
+`include`, or `have_attributes`, you will get a diff of the two data structures
+you are trying to match against. This is really helpful for strings, but not so
+helpful for other, more "real world" kinds of values, such as arrays, hashes,
+and full-scale objects. The reason this doesn't work is because [all RSpec does
+is run your `expected` and `actual` values through Ruby's PrettyPrinter
+library][rspec-differ-fail] and then perform a diff of these strings.
+
+For instance, let's say you wanted to compare these two hashes:
 
 ``` ruby
-expected = {
+actual = {
   customer: {
-    name: "Marty McFly",
+    person: SuperDiff::Test::Person.new(name: "Marty McFly, Jr.", age: 17),
     shipping_address: {
-      line_1: "123 Main St.",
+      line_1: "456 Ponderosa Ct.",
       city: "Hill Valley",
       state: "CA",
-      zip: "90382",
-    },
+      zip: "90382"
+    }
   },
   items: [
     {
       name: "Fender Stratocaster",
       cost: 100_000,
-      options: ["red", "blue", "green"],
+      options: ["red", "blue", "green"]
     },
-    { name: "Chevy 4x4" },
-  ],
+    { name: "Mattel Hoverboard" }
+  ]
 }
-```
-
-and your second hash looks like this:
 
-``` ruby
-actual = {
+expected = {
   customer: {
-    name: "Marty McFly, Jr.",
+    person: SuperDiff::Test::Person.new(name: "Marty McFly", age: 17),
     shipping_address: {
-      line_1: "456 Ponderosa Ct.",
+      line_1: "123 Main St.",
       city: "Hill Valley",
       state: "CA",
-      zip: "90382",
-    },
+      zip: "90382"
+    }
   },
   items: [
     {
       name: "Fender Stratocaster",
       cost: 100_000,
-      options: ["red", "blue", "green"],
+      options: ["red", "blue", "green"]
     },
-    { name: "Mattel Hoverboard" },
-  ],
+    { name: "Chevy 4x4" }
+  ]
 }
 ```
 
-If you want to know what the difference between them is, you could say:
+If, somewhere in a test, you were to say:
 
 ``` ruby
-SuperDiff::EqualityMatcher.call(expected, actual)
+expect(actual).to eq(expected)
 ```
 
-This will give you the following string:
+You would get output that looks like:
 
-```
-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"
-      }
-    ]
-  }
-```
+![Before super_diff](doc/before_super_diff.png)
+
+Not great.
 
-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.
+This library provides a diff engine that knows how to figure out the differences
+between any two data structures and display them in a sensible way. Using the
+example above, you'd get this instead:
 
-By the way, SuperDiff doesn't just work with hashes, but arrays as well as other
-objects, too!
+![After super_diff](doc/after_super_diff.png)
 
-## Usage
+[rspec-differ-fail]: https://github.com/rspec/rspec-support/blob/c69a231d7369dd165ad7ce4742e1a2e21e3462b5/lib/rspec/support/differ.rb#L178
 
-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.
+## Installation
 
-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.
+Want to try out this gem for yourself? As with most development-related gems,
+there are a couple ways depending on your type of project:
 
-To get started, add the gem to your Gemfile under the `test` group:
+### Rails apps
+
+If you're developing a Rails app, add the following to your Gemfile:
 
 ``` ruby
 gem "super_diff"
 ```
 
-Then, open up `spec_helper` and add this line somewhere:
+After running `bundle install`, add the following to your `rails_helper`:
+
+``` ruby
+require "super_diff/rspec-rails"
+```
+
+You're done!
+
+### Libraries
+
+If you're developing a library, add the following to your gemspec:
+
+``` ruby
+spec.add_development_dependency "super_diff"
+```
+
+Now add the following to your `spec_helper`:
 
 ``` 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.
+You're done!
+
+## Configuration
+
+As capable as this library is, it doesn't know how to deal with every kind of
+object out there. You might find it necessary to instruct the gem on how to diff
+your object. To do this, you can use a configuration block. Simply add this to
+your test helper file (either `rails_helper` or `spec_helper`):
+
+``` ruby
+SuperDiff::RSpec.configure do |config|
+  config.add_extra_differ_class(YourDiffer)
+  config.add_extra_operational_sequencer_class(YourOperationalSequencer)
+  config.add_extra_diff_formatter_class(YourDiffFormatter)
+end
+```
+
+*(More info here in the future on adding a custom differ, operational sequencer,
+and diff formatter. Also explanations on what these are.)*
 
 ## 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 encounter a bug or have an idea for how this could be better, feel free
+to [create an issue](https://github.com/mcmire/super_diff/issues).
 
 If you'd like to submit a PR instead, here's how to get started. First, fork
-this repo and then run:
+this repo. Then, when you've cloned your fork, run:
 
 ```
 bundle install
 ```
 
-This will install dependencies. From here you can run all of the tests:
+This will install various dependencies. After this, you can run all of the
+tests: 
 
 ```
 bundle exec rake
@@ -169,6 +172,31 @@ bundle exec rspec spec/unit/...
 
 Finally, submit your PR and I'll take a look at it when I get a chance.
 
+## Compatibility
+
+`super_diff` is [tested][travis] to work with Ruby >= 2.4.x, RSpec 3.x, and
+Rails >= 5.x.
+
+[travis]: http://travis-ci.org/mcmire/super_diff
+
+## Inspiration/Thanks
+
+In developing this gem I made use of or was heavily inspired by these libraries:
+
+* [Diff::LCS][diff-lcs], the library I started with in the [original version of
+  this gem][original-version] (made in 2011!)
+* The pretty-printing algorithms and API within [PrettyPrinter][pretty-printer]
+  and [AwesomePrint][awesome-print], from which I borrowed ideas to develop
+  the [inspectors][inspection-tree].
+
+Thank you so much!
+
+[original-version]: https://github.com/mcmire/super_diff/tree/old-master
+[diff-lcs]: https://github.com/halostatue/diff-lcs
+[pretty-printer]: https://github.com/ruby/ruby/tree/master/lib/prettyprint.rb
+[awesome-print]: https://github.com/awesome-print/awesome_print
+[inspection-tree]: https://github.com/mcmire/super_diff/blob/master/lib/super_diff/object_inspection/inspection_tree.rb
+
 ## Copyright/License
 
-© 2018 Elliot Winkler, released under the [MIT license](LICENSE).
+© 2018-2019 Elliot Winkler, released under the [MIT license](LICENSE).

data/lib/super_diff.rb

@@ -1,50 +1,36 @@
-require "patience_diff"
+require "attr_extras/explicit"
 require "diff-lcs"
+require "patience_diff"
 
-require_relative "super_diff/csi"
-require_relative "super_diff/errors"
-require_relative "super_diff/helpers"
-require_relative "super_diff/value_inspection"
-
-require_relative "super_diff/equality_matchers/base"
-require_relative "super_diff/equality_matchers/array"
-require_relative "super_diff/equality_matchers/hash"
-require_relative "super_diff/equality_matchers/multi_line_string"
-require_relative "super_diff/equality_matchers/single_line_string"
-require_relative "super_diff/equality_matchers/object"
-require_relative "super_diff/equality_matchers"
-require_relative "super_diff/equality_matcher"
-
-require_relative "super_diff/operations/unary_operation"
-require_relative "super_diff/operations/binary_operation"
-
-require_relative "super_diff/operation_sequences/base"
-require_relative "super_diff/operation_sequences/array"
-require_relative "super_diff/operation_sequences/hash"
-require_relative "super_diff/operation_sequences/object"
-
-require_relative "super_diff/operational_sequencers/base"
-require_relative "super_diff/operational_sequencers/array"
-require_relative "super_diff/operational_sequencers/hash"
-require_relative "super_diff/operational_sequencers/multi_line_string"
-require_relative "super_diff/operational_sequencers/object"
-require_relative "super_diff/operational_sequencers"
-require_relative "super_diff/operational_sequencer"
-
-require_relative "super_diff/diff_formatters/collection"
-require_relative "super_diff/diff_formatters/base"
-require_relative "super_diff/diff_formatters/array"
-require_relative "super_diff/diff_formatters/hash"
-require_relative "super_diff/diff_formatters/multi_line_string"
-require_relative "super_diff/diff_formatters/object"
-require_relative "super_diff/diff_formatters"
-require_relative "super_diff/diff_formatter"
+module SuperDiff
+  autoload(
+    :ColorizedDocumentExtensions,
+    "super_diff/colorized_document_extensions",
+  )
+  autoload :Csi, "super_diff/csi"
+  autoload :DiffFormatter, "super_diff/diff_formatter"
+  autoload :DiffFormatters, "super_diff/diff_formatters"
+  autoload :Differ, "super_diff/differ"
+  autoload :Differs, "super_diff/differs"
+  autoload :EqualityMatcher, "super_diff/equality_matcher"
+  autoload :EqualityMatchers, "super_diff/equality_matchers"
+  autoload :Helpers, "super_diff/helpers"
+  autoload :NoDifferAvailableError, "super_diff/no_differ_available_error"
+  autoload(
+    :NoOperationalSequencerAvailableError,
+    "super_diff/no_operational_sequencer_available_error",
+  )
+  autoload :ObjectInspection, "super_diff/object_inspection"
+  autoload :OperationalSequencer, "super_diff/operational_sequencer"
+  autoload :OperationalSequencers, "super_diff/operational_sequencers"
+  autoload :OperationSequences, "super_diff/operation_sequences"
+  autoload :Operations, "super_diff/operations"
+  autoload :RecursionGuard, "super_diff/recursion_guard"
 
-require_relative "super_diff/differs/base"
-require_relative "super_diff/differs/array"
-require_relative "super_diff/differs/empty"
-require_relative "super_diff/differs/hash"
-require_relative "super_diff/differs/multi_line_string"
-require_relative "super_diff/differs/object"
-require_relative "super_diff/differs"
-require_relative "super_diff/differ"
+  COLORS = {
+    alpha: :magenta,
+    beta: :yellow,
+    border: :blue,
+    header: :white,
+  }.freeze
+end

data/lib/super_diff/active_record.rb

@@ -0,0 +1,41 @@
+require "super_diff/active_support"
+
+module SuperDiff
+  module ActiveRecord
+    autoload :DiffFormatters, "super_diff/active_record/diff_formatters"
+    autoload :Differs, "super_diff/active_record/differs"
+    autoload(
+      :ObjectInspection,
+      "super_diff/active_record/object_inspection",
+    )
+    autoload(
+      :OperationSequences,
+      "super_diff/active_record/operation_sequences",
+    )
+    autoload(
+      :OperationalSequencers,
+      "super_diff/active_record/operational_sequencers",
+    )
+  end
+end
+
+if defined?(SuperDiff::RSpec)
+  SuperDiff::RSpec.configure do |config|
+    config.add_extra_differ_class(
+      SuperDiff::ActiveRecord::Differs::ActiveRecordRelation,
+    )
+    config.add_extra_operational_sequencer_class(
+      SuperDiff::ActiveRecord::OperationalSequencers::ActiveRecordModel,
+    )
+    config.add_extra_operational_sequencer_class(
+      SuperDiff::ActiveRecord::OperationalSequencers::ActiveRecordRelation,
+    )
+    config.add_extra_diff_formatter_class(
+      SuperDiff::ActiveRecord::DiffFormatters::ActiveRecordRelation,
+    )
+  end
+end
+
+SuperDiff::ObjectInspection.map.prepend(
+  SuperDiff::ActiveRecord::ObjectInspection::MapExtension,
+)

data/lib/super_diff/active_record/diff_formatters.rb

@@ -0,0 +1,10 @@
+module SuperDiff
+  module ActiveRecord
+    module DiffFormatters
+      autoload(
+        :ActiveRecordRelation,
+        "super_diff/active_record/diff_formatters/active_record_relation",
+      )
+    end
+  end
+end

data/lib/super_diff/active_record/diff_formatters/active_record_relation.rb

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