Permalink
Browse files

Words

  • Loading branch information...
1 parent 4449d89 commit a966e77317f5ab62d61e369071336ac32888b880 @mcmire committed Jan 20, 2011
Showing with 35 additions and 21 deletions.
  1. +35 −21 README.md
View
@@ -1,12 +1,12 @@
# super_diff
-## What is it?
+## What is this?
super_diff 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.
-## Can you give me an example?
+## How does it work?
-Sure. Let's say we have two arrays. Array A looks like this:
+Let's say we have two arrays. Array A looks like this:
[
"foo",
@@ -24,13 +24,15 @@ Array B looks like this:
["blargh", "gragh", 1, ["raz", ["ralston"]], ["foreal", ["zap"]]]
]
-We want to know what the difference is between them, so we say:
+We want to know what the difference is between them, so we say (note: the API doesn't work like this yet but you get the idea):
+ differ = SuperDiff::Differ.new
+ result = differ.diff(a, b)
stdout = StringIO.new
- differ = SuperDiff::Differ.new(stdout)
- differ.diff(a, b)
+ reporter = SuperDiff::Reporter.new(stdout)
+ reporter.report(result)
-Differ#diff will dump some output to the stream you've given, so if we read the StringIO here, we'll get this:
+Assuming that Reporter#report takes the result from the Differ and dumps output to the stream we've given, if we read the StringIO here, we'll get this:
Error: Arrays of same size but with differing elements.
@@ -60,35 +62,47 @@ Differ#diff will dump some output to the stream you've given, so if we read the
- *[2]: Expected to be present, but missing "ffff".
- *[4]: Expected to not be present, but found ["foreal", ["zap"]].
+## Why did you make it?
+
+For testing, specifically with RSpec. For instance, say you're doing a simple equality test, but between two complex data structures:
+
+ complex_data_structure.should == another_complex_data_structure
+
+Now, RSpec (at least RSpec 2) *does* give you a difference between the two data structures, but all it really does is call `complex_data_structure.pretty_inspect` and `another_complex_data_structure.pretty_inspect` and then run the two strings through the unified diff tool that's ordinarily used to find the difference between two text files. It's not a bad solution, but it could be more helpful. So I set out to make this better.
+
## Why not use Diff::LCS or \<insert other tool here\>?
Because Diff::LCS really only works for arrays (as far as I know). My goal is for this to work with hashes too (or possibly other Enumerable types).
-As far as other tools, I know plenty of them exist, but from the brief googling I did, I didn't get the impression that any of them are that great or really give any helpful information. But feel free to prove me wrong.
-
-## Why did you make it?
+As far as other tools, I know plenty of them exist, but from the brief googling I did, I didn't get the impression that any of them are that great or really give any helpful information. If I'm wasting my time, feel free to let me know.
-For RSpec (2). Specifically the case where you're doing a simple equality test between two complex data structures:
+## Can I use it?
- complex_data_structure.should == another_complex_data_structure
-
-It's true that RSpec gives you a difference between the two data structures, but all it really does is call `complex_data_structure.inspect` and `another_complex_data_structure.inspect` and then run the two strings through the ubiquitous unified diff tool that's ordinarily used to find the difference between two text files, which really isn't that helpful. So I set out to solve that problem.
+Sure. Be aware that this is kind of proof-of-concept at the moment, so things will probably change in the future, like the API or even the name of the project. If that's okay with you, feel free to try it out.
-## So what does it do?
+## What are your plans for this?
-At the moment, it only handles basic types (strings, numbers) and arrays. I plan on handling hashes, possibly other enumerables, and possibilities like circular data structures, though. I also plan on splitting the output part of the Differ into a separate Reporter class, and making an RSpec matcher.
+Check out the [issue tracker](http://github.com/mcmire/super_diff/issues). If you have an idea, add an issue and I'll take a look.
-## Can I use it?
+## Can I hack on it?
-Sure, but keep in mind that this is really a proof-of-concept right now. I may change the API or even the name of the project. If that's okay with you, feel free to try it out.
+Totally! One thing is that I develop everything using [RVM](http://rvm.beginrescueend.com) these days. I'm going to assume you do, too. If not, at least ensure you're using 1.9. With that in mind, here's what you need to do.
-## I've got an idea about this...
+* `rvm install 1.9.2` with a "super_diff" gemset. There's an .rvmrc so when you drop into the repo (assuming you've cloned it) you'll be in the gemset automatically.
+* Install Bundler, then `bundle install` (there are only a few development dependencies).
-Great! I'm not really accepting issues for this, but feel free to send me a Github message or email.
+If you're contributing an idea:
+
+* Add tests. I'm using 1.9's MiniTest with its "spec" layer; you should be able to figure it out. Run all tests with `rake test`.
+* I accept pull requests, so you should know what to do.
## Copyright/License
-&copy; 2011 Elliot Winkler. You're free to do whatever you want with the code here. You know, provided I get some sort of recognition ;)
+&copy; 2011 Elliot Winkler.
+
+You're free to do whatever you want with the code here.
+
+That's all, folks!
## Contact

0 comments on commit a966e77

Please sign in to comment.