Skip to content

Commit 58a7b2d

Browse files
mcmiremcmire
committed
Update README, add LICENSE
1 parent 17bb00b commit 58a7b2d

File tree

2 files changed

+161
-4
lines changed

2 files changed

+161
-4
lines changed

‎LICENSE

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Copyright (c) 2018 Elliot Winkler.
2+
3+
Permission is hereby granted, free of charge, to any person
4+
obtaining a copy of this software and associated documentation
5+
files (the "Software"), to deal in the Software without
6+
restriction, including without limitation the rights to use,
7+
copy, modify, merge, publish, distribute, sublicense, and/or sell
8+
copies of the Software, and to permit persons to whom the
9+
Software is furnished to do so, subject to the following
10+
conditions:
11+
12+
The above copyright notice and this permission notice shall be
13+
included in all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
17+
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
19+
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
20+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22+
OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 139 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,142 @@
1-
# SuperDiff
1+
# SuperDiff [![Gem Version][version-badge]][rubygems] [![Build Status][travis-badge]][travis] ![Downloads][downloads-badge] [![Hound][hound-badge]][hound]
22

3-
I'll fill this in later!
3+
[version-badge]: http://img.shields.io/gem/v/super_diff.svg
4+
[rubygems]: http://rubygems.org/gems/super_diff
5+
[travis-badge]: http://img.shields.io/travis/mcmire/super_diff/master.svg
6+
[travis]: http://travis-ci.org/mcmire/super_diff
7+
[downloads-badge]: http://img.shields.io/gem/dtv/super_diff.svg
8+
[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
9+
[hound]: https://houndci.com
410

5-
## Development
11+
SuperDiff is a utility that helps you diff two complex data structures in Ruby,
12+
and gives you helpful output to show you exactly how the two data structures
13+
differ.
614

7-
bin/setup
15+
## Installation
16+
17+
Add the following line to your Gemfile:
18+
19+
gem "super_diff"
20+
21+
## Usage
22+
23+
Let's say you have two hashes and you want to compare them. Perhaps your first
24+
hash looks like this:
25+
26+
expected = {
27+
customer: {
28+
name: "Marty McFly",
29+
shipping_address: {
30+
line_1: "123 Main St.",
31+
city: "Hill Valley",
32+
state: "CA",
33+
zip: "90382",
34+
},
35+
},
36+
items: [
37+
{
38+
name: "Fender Stratocaster",
39+
cost: 100_000,
40+
options: ["red", "blue", "green"],
41+
},
42+
{ name: "Chevy 4x4" },
43+
],
44+
}
45+
46+
and your second hash looks like this:
47+
48+
actual = {
49+
customer: {
50+
name: "Marty McFly, Jr.",
51+
shipping_address: {
52+
line_1: "456 Ponderosa Ct.",
53+
city: "Hill Valley",
54+
state: "CA",
55+
zip: "90382",
56+
},
57+
},
58+
items: [
59+
{
60+
name: "Fender Stratocaster",
61+
cost: 100_000,
62+
options: ["red", "blue", "green"],
63+
},
64+
{ name: "Mattel Hoverboard" },
65+
],
66+
}
67+
68+
If you want to know what the difference between them is, you could say:
69+
70+
require "super_diff"
71+
72+
puts SuperDiff::EqualityMatcher.call(expected, actual)
73+
74+
This will print out the following:
75+
76+
Differing hashes.
77+
78+
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" }] }
79+
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" }] }
80+
81+
Diff:
82+
83+
84+
{
85+
customer: {
86+
- name: "Marty McFly",
87+
+ name: "Marty McFly, Jr.",
88+
shipping_address: {
89+
- line_1: "123 Main St.",
90+
+ line_1: "456 Ponderosa Ct.",
91+
city: "Hill Valley",
92+
state: "CA",
93+
zip: "90382"
94+
}
95+
},
96+
items: [
97+
{
98+
name: "Fender Stratocaster",
99+
cost: 100000,
100+
options: ["red", "blue", "green"]
101+
},
102+
{
103+
- name: "Chevy 4x4"
104+
+ name: "Mattel Hoverboard"
105+
}
106+
]
107+
}
108+
109+
This works with arrays, too!
110+
111+
## Usage with RSpec
112+
113+
This gem was specifically designed for use with RSpec. RSpec has this great
114+
feature where if you're using `eq` or some other built-in matcher to compare two
115+
objects, and your test fails, you may see a diff between those objects. However,
116+
this diff is not always the most helpful. It's very common when writing tests
117+
for API endpoints to work with large data structures, and these diffs are not
118+
sufficient in highlighting changes between such structures.
119+
120+
To fix this, this gem replaces the default differ in RSpec with SuperDiff so
121+
that you get diffs such as the example provided above. To make use of this,
122+
simply add this line to your `spec_helper`:
123+
124+
require "super_diff/rspec"
125+
126+
## Contributing
127+
128+
If you encounter a bug or have an idea for how this could be better, I'm all
129+
ears! Feel free to create an issue or post a PR and I'll take a look at it when
130+
I get a chance.
131+
132+
To get set up locally, clone this repo and then run:
133+
134+
bundle install
135+
136+
This will install dependencies. From here you can run all of the tests:
137+
138+
bundle exec rake
139+
140+
## Copyright/License
141+
142+
© 2018 Elliot Winkler, released under the [MIT license](LICENSE).

0 commit comments

Comments
 (0)