wrong 0.1.0 → 0.2.0

data/README.markdown

@@ -1,56 +1,145 @@
+"Feels so right, it can't be Wrong"
+
 ## Abstract ##
 
-Wrong provides a general assert method that takes a predicate block.  Assertion failure messages are rich in detail.
+Wrong provides a general assert method that takes a predicate block. Assertion failure
+messages are rich in detail. The Wrong idea is to replace all those countless assert_this,
+assert_that library methods which only exist to give a more useful failure message than
+"assertion failed". Wrong replaces all of them in one fell swoop, since if you can write it
+in Ruby, Wrong can make a sensible failure message out of it.
 
-Wrong is alpha-quality - I'd very much appreciate feedback and bug reports.
+Wrong is alpha-quality. We'd very much appreciate feedback and bug reports. There are plenty of things left to be done
+to make the results look uniformly clean and beautiful. We want your feedback, and especially to give us cases where
+either it blows up or the output is ugly or uninformative.
 
-It's an offshoot of predicated.
-[http://github.com/sconover/predicated](http://github.com/sconover/predicated)
+It relies on [Predicated](http://github.com/sconover/predicated) for its main failure message.
 
-Inspired by assert { 2.0 }
-[http://assert2.rubyforge.org/](http://assert2.rubyforge.org/)
+Inspired by [assert { 2.0 }](http://assert2.rubyforge.org/) but rewritten from scratch to be compatible with Ruby 1.8 and 1.9.
 
 ## Usage ##
 
-Wrong provides a simple assert method:
+Wrong provides a simple assert method that takes a block:
 
 	require "wrong"
 	
 	include Wrong::Assert
 	
-	assert{1==1} 
+	assert {1==1}
 	 ==> nil
 	
-	assert{2==1}
-	 ==> Wrong::Assert::AssertionFailedError: 2 is not equal to 1
-
+	assert {2==1}
+	 ==> Wrong::Assert::AssertionFailedError: Expected (2 == 1), but 2 is not equal to 1
+
+If your assertion is more than a simple predicate, then Wrong will split it into parts and show you the values of all the relevant subexpressions.
+
+    x = 7; y = 10; assert { x == 7 && y == 11 }
+     ==>
+    Wrong::Assert::AssertionFailedError: Expected ((x == 7) and (y == 11)), but
+        (x == 7) is true
+        x is 7
+        (y == 11) is false
+        y is 10
+    
 And a companion, 'deny':
 
 	deny{'abc'.include?('bc')}
-	 ==> Wrong::Assert::AssertionFailedError: 'abc' includes 'bc'
+	 ==> Wrong::Assert::AssertionFailedError: Didn't expect "abc".include?("bc"), but 'abc' includes 'bc'
 
-There's a convenience method for catching errors:
+There's also a convenience method for catching errors:
 
-	assert{ catch_raise{raise "boom!"}.message == "boom!" }
-	 ==> nil
+    assert{ catch_raise{raise "vanilla"}.message == "chocolate" }
+	 ==>
+    Wrong::Assert::AssertionFailedError: Expected (catch_raise { raise("vanilla") }.message == "chocolate"), but 'vanilla' is not equal to 'chocolate'
+
+## Apology ##
+
+So does the world need another assertion framework? In fact, it does not! We actually believe the world needs **fewer** assert methods.
+
+The Wrong idea is to replace all those countless assert\_this, assert\_that library methods which only exist to give a more useful failure message than "assertion failed". Wrong replaces all of them in one fell swoop, since if you can write it in Ruby, Wrong can make a sensible failure message out of it.
+
+Even the lowly workhorse `assert_equal` is bloated compared to Wrong: would you rather write this
+
+    assert_equal time, money
+
+or this
+
+    assert { time == money }
+
+? The Wrong version has the advantage of being plain, transparent Ruby code, not an awkward DSL that moves "equal" out of its natural place between the comparands. Plus, WYSIWYG! You know just from looking at it that "equal" means `==`, not `eql?` or `===` or `=~`.
+
+Moreover, much like TDD itself, Wrong encourages you to write cleaner code. If your assertion messages are not clear and "Englishy", then maybe it's time for you to refactor a bit -- extract an informatively named variable or method, maybe push some function onto its natural object *a la* the [Law of Demeter](http://en.wikipedia.org/wiki/Law_of_Demeter)...
+
+Wrong also lets you put the expected and actual values in any order you want! Consider the failure messages for
+
+    assert { current_user == "joe" } # => Expected (current_user == "joe") but current_user is "fred"
+    assert { "joe" == current_user } # => Expected ("joe" == current_user) but current_user is "fred"
+
+You get just the information you want, and none you don't want. At least, that's the plan! :-)
+
+## Algorithm ##
+
+So wait a second. How do we do it? Doesn't Ruby have [poor support for AST introspection](http://blog.zenspider.com/2009/04/parsetree-eol.html)? Well, yes, it does, so we cheat: we figure out what file and line the assert block is defined in, then open the file, read the code, and parse it directly using Ryan Davis' amazing [RubyParser](http://parsetree.rubyforge.org/ruby_parser/) and [Ruby2Ruby](http://seattlerb.rubyforge.org/ruby2ruby/). You can bask in the kludge by examining `chunk.rb` and `assert.rb`. If you find some code it can't parse, please send it our way.
+
+Before you get your knickers in a twist about how this is totally unacceptable because it doesn't support this or that use case, here are our caveats and excuses:
+
+* It works! Tested in 1.8.6, 1.8.7, 1.9.1, and 1.9.2-rc2. (Thank you, [rvm](http://rvm.beginrescueend.com/)!)
+* Your code needs to be in a file. That means it doesn't work in IRB. (If you're developing Ruby code without saving it to a mounted disk, then sorry, Wrong is not right for you.)
+* It's a development-time testing library, not a production runtime library, so there are no security or filesystem issues.
+* `eval` isn't evil, it's just misunderstood.
+* It makes a few assumptions about the structure of your code, leading to some restrictions:
+  * You can't have more than one call to `assert` per line. (This should not be a problem since even if you're nesting asserts for some bizarre reason, we assume you know where your Return key is. And actually, technically you can put two asserts on a line, but it always describes the first one it sees, which means that if the second one executes, its failure message will be incorrect or broken.)
+  * You can't use metaprogramming to write your assert blocks.
+  * All variables and methods must be available in the binding of the assertion block.
 
 ## Adapters ##
 
 Adapters for various test frameworks sit under wrong/adapters.
-TODO
 
-## Message ##
+Currently we support
+
+  * Test::Unit
+  * Minitest
+
+Coming soon
+
+  * RSpec
+  * ???
+
+## Explanations ##
+
+`assert` and `deny` can take an optional explanation, e.g.
+
+      assert("since we're on Earth") { sky.blue? }
+
+Since the point of Wrong is to make asserts self-explanatory, you should feel free to use explanations only when they would add something that you couldn't get from reading the (failed) assertion code itself. Don't bother doing things like this:
+
+      assert("the sky should be blue") { sky.blue? } # redundant
+
+The failure message of the above would be something like "Expected sky.blue? but sky is :green" which is not made clearer by the addition of "the sky should be blue". We already know it should be blue since we see right there that we're expecting it to be blue.
+
+And if your assertion code isn't self-explanatory, then that's a hint that you might need to do some refactoring until it is. (Yes, even test code should be clean as a whistle. **Especially** test code.)
+
+## Special Formatting ##
 
 Enhancements for error messages sit under wrong/message.
-TODO
 
-## Etc ##
+Currently we support special messages for
+
+  * String ==
+  * Enumerable ==
+    * including nested string elements
+
+## Helper Assert Methods ##
 
-Tracker project:
-[http://www.pivotaltracker.com/projects/95014](http://www.pivotaltracker.com/projects/95014)
+If you really want to, you can define your procs in one method, pass it in to another method, and have that method assert it. This is very bizarre and you probably shouldn't do it. Wrong will do its best to figure out where the actual assertion code is but it might not succeed.
 
-“I think it's wrong that only one company makes the game Monopoly.” -Steven Wright
+If you're in Ruby 1.8, you **really** shouldn't do it! But if you do, you can use the "depth" parameter to give Wrong a better hint about how far up the stack it should crawl to find the code. See `assert_test.rb` for more details, if you dare.
+
+## Authors ##
+
+* Steve Conover - <sconover@gmail.com>
+* Alex Chaffee - <alex@stinky.com> - <http://alexch.github.com>
+
+## Etc ##
 
-"And it really doesn't matter if I'm wrong 
- I'm right where I belong"
--Fixing a Hole
+Tracker project: <http://www.pivotaltracker.com/projects/109993>

data/lib/predicated/Gemfile

@@ -0,0 +1,15 @@
+source :gemcutter
+gem "ruby_parser"
+gem "ruby2ruby"
+gem "ParseTree"
+gem "diff"
+gem "diff-lcs"
+gem "minitest"
+gem "nokogiri"
+gem "arel", "~>0.4"
+gem "sqlite3-ruby"
+gem "activerecord", "~>3.0.0.beta"
+gem "i18n"
+gem "json", "1.1.9"
+gem "treetop", "~>1.4.8"
+

data/lib/predicated/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Steve Conover
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/predicated/README.markdown

@@ -0,0 +1,191 @@
+## Abstract ##
+
+Predicated is a simple predicate model for Ruby.  It provides useful predicate transformations and operations.
+
+Tracker project:
+[http://www.pivotaltracker.com/projects/95014](http://www.pivotaltracker.com/projects/95014)
+
+## Transformations ##
+
+- From:
+  - json
+  - xml
+  - url part, ex: "!(a=1&b=2|c=3)"
+  - callable objects (lambdas/procs, and therefore blocks) - ruby 1.8.x only
+  - ruby code - ruby 1.8.x only
+- To:
+  - json
+  - xml
+  - sql where clause via [arel](http://github.com/rails/arel)
+  - [solr](http://lucene.apache.org/solr/) query string
+  - english sentence, ex: "'a' is not equal to 'b'"
+
+## Usage ##
+
+Note: The test suite acts as a comprehensive usage guide.
+
+
+Evaluate a predicate:
+    
+    require "predicated/evaluate"
+    include Predicated
+            
+    Predicate { Eq(1, 2) }.evaluate == false
+    Predicate { Lt(1, 2) }.evaluate == true
+    Predicate { Or(Lt(1, 2),Eq(1, 2)) }.evaluate == true
+    
+    x = 1
+    Predicate { Lt(x, 2) }.evaluate == true
+
+
+Parse a predicate from part of a url and then turn it into a sql where clause:
+    
+    require "predicated/from/url_part"
+    require "predicated/to/arel"
+        
+    predicate = Predicated::Predicate.from_url_part("(color=red|color=green)&size=large")
+    
+    predicate.inspect == 
+      "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+    
+    predicate.to_arel(Table(:shirt)).to_sql == 
+      %{(("shirt"."color" = 'red' OR "shirt"."color" = 'green') AND "shirt"."size" = 'large')} 
+  
+
+Parse a predicate from json and then turn it into a solr query string:
+    
+    require "predicated/from/json"
+    require "predicated/to/solr"
+        
+    predicate = Predicated::Predicate.from_json_str(%{
+      {"and":[{"or":[["color","==","red"],["color","==","green"]]},["size","==","large"]]}
+    })
+        
+    predicate.inspect == "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+        
+    predicate.to_solr == "((color:red OR color:green) AND size:large)" 
+
+  
+From json:
+    
+    require "predicated/from/json"
+        
+    Predicated::Predicate.from_json_str(%{
+      {"and":[
+        {"or":[
+          ["color","==","red"],
+          ["color","==","green"]
+        ]},
+        ["size","==","large"]
+      ]}
+    }).inspect == "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+
+
+From xml:
+    
+    require "predicated/from/xml"
+        
+    Predicated::Predicate.from_xml(%{
+      <and>
+        <or>
+          <equal><left>color</left><right>red</right></equal>
+          <equal><left>color</left><right>green</right></equal>
+        </or>
+        <equal><left>size</left><right>large</right></equal>
+      </and>
+    }).inspect == "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+
+
+From url part:
+    
+    require "predicated/from/url_part"
+        
+    Predicated::Predicate.from_url_part("(color=red|color=green)&size=large").inspect ==
+      "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+
+
+From callable object:
+    
+    require "predicated/from/callable_object"
+        
+    Predicated::Predicate.from_callable_object{('color'=='red' || 'color'=='green') && 'size'=='large'}.inspect ==
+      "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+
+
+From ruby code string:
+      
+    require "predicated/from/ruby_code_string"
+            
+    Predicated::Predicate.from_ruby_code_string("('color'=='red' || 'color'=='green') && 'size'=='large'").inspect ==
+      "And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))" 
+  
+  
+To json:
+      
+    require "predicated/to/json"
+    include Predicated
+            
+    Predicate{And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))}.to_json_str ==
+    %{
+      {"and":[
+        {"or":[
+          ["color","==","red"],
+          ["color","==","green"]
+        ]},
+        ["size","==","large"]
+      ]}
+    }
+  
+  
+To xml:
+      
+    require "predicated/to/xml"
+    include Predicated
+            
+    Predicate{And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))}.to_xml ==
+    %{
+      <and>
+        <or>
+          <equal><left>color</left><right>red</right></equal>
+          <equal><left>color</left><right>green</right></equal>
+        </or>
+        <equal><left>size</left><right>large</right></equal>
+      </and>      
+    }
+  
+  
+To arel (sql where clause):
+      
+    require "predicated/to/arel"
+    include Predicated
+            
+    Predicate{And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))}.to_arel(Table(:shirt)).to_sql ==
+      %{(("shirt"."color" = 'red' OR "shirt"."color" = 'green') AND "shirt"."size" = 'large')}
+  
+  
+To solr query string:
+      
+    require "predicated/to/solr"
+    include Predicated
+            
+    Predicate{And(Or(Eq('color','red'),Eq('color','green')),Eq('size','large'))}.to_solr ==
+      "((color:red OR color:green) AND size:large)"
+  
+  
+To sentence:
+      
+    require "predicated/to/sentence"
+    include Predicated
+        
+    Predicate{ And(Eq("a",1),Eq("b",2)) }.to_sentence == 
+      "'a' is equal to 1 and 'b' is equal to 2"
+    
+    Predicate{ Gt("a",1) }.to_negative_sentence == 
+      "'a' is not greater than 1" 
+
+
+## Testing Notes ##
+
+Right now this project makes use of Wrong for assertions.  Wrong uses this project.  It's kind of neat in an eat-your-own-dogfood sense, but it's possible that this will be problematic over time (particularly when changes in this project cause assertions to behave differently - if even temporarily).
+
+A middle ground is to make "from ruby string" and "from callable object" use minitest asserts, since these are the "interesting" parts of Predicated relied on by Wrong.

data/lib/predicated/Rakefile

@@ -0,0 +1,51 @@
+require "rubygems"
+require "bundler"
+Bundler.setup
+
+def gemspec
+  @gemspec ||= begin
+    gemspec_file = File.expand_path('../predicated.gemspec', __FILE__)
+    gemspec = eval(File.read(gemspec_file), binding, gemspec_file)
+  end
+end
+
+task :default => :test
+
+desc 'run all tests'
+task :test do
+  sh %{ruby test/suite.rb}
+end
+
+desc "Build pkg/#{gemspec.full_name}.gem"
+task :build => "gemspec:validate" do
+  sh %{gem build predicated.gemspec}
+  FileUtils.mkdir_p "pkg"
+  FileUtils.mv gemspec.file_name, "pkg"
+end
+
+desc "Install the latest built gem"
+task :install => :build do
+  sh "gem install --local pkg/#{gemspec.file_name}"
+end
+
+namespace :release do
+  task :tag do
+    release_tag = "v#{gemspec.version}"
+    sh "git tag -a #{release_tag} -m 'Tagging #{release_tag}'"
+    sh "git push origin #{release_tag}"
+  end
+
+  task :gem => :build do
+    sh "gem push pkg/#{gemspec.file_name}"
+  end
+end
+
+desc "Release the current branch to GitHub and Gemcutter"
+task :release => %w(release:tag release:gem)
+
+namespace :gemspec do
+  desc 'Validate the gemspec'
+  task :validate do
+    gemspec.validate
+  end
+end