solid_assert 0.5.0 → 0.6.0

data/README.md

@@ -1,11 +1,17 @@
 # solid_assert
 
-solid_assert is a simple implementation of an `assert` utility in Ruby. 
+*solid_assert* is a simple implementation of an `assert` utility in Ruby. It let you code tests for your assumptions inside your code itself. 
 
-It let you code in your assumptions when coding. Sometimes, when you are coding, you have this thinking of "I it reaches here, then this variable has to be this value", or "This line should never be executed", or "At this point, this list should contain an entry for all the keys in this hash". These are the kind of scenarios when assertions comes handy.
+Notice that assertions shouldn't be used for handling error situations. Use Ruby built-in exception handling for that. Assertions are meant to test conditions about the integrity of your code. You should use them for testing assumptions like the following: 
+
+- If it reaches here, then this variable has to have this value.
+- This line of code should never be executed.
+- At this point, this list should contain one entry for all the keys in this hash.
 
 The practice of using assertions makes your code more solid, since it is the computer who systematically verifies your code integrity. 
 
+Assertions should be used in development mode. You can disable them in production for performance reasons.
+
 # Installation
 
 In your `Gemfile`
@@ -14,11 +20,37 @@ In your `Gemfile`
 
 # Usage
 
+You can enable assertions with
+
+	SolidAssert.enable_assertions
+
+You can disabled assertions with
+	
+	SolidAssert.disable_assertions
+
+Use `assert` for testing conditions. You can optionally provide a message
+
+	assert some_string != "some value"
+	assert clients.list?, "Isn't the clients list empty?"
+	
+Use `invariant` for testing blocks of code. This comes handy when testing your assumptions requires several lines of code. You can provide an optional message if you want
+
+	invariant do
+		one_variable = calculate_some_value
+		other_variable = calculate_some_other_value
+		one_variable > other_variable
+	end
+
+	invariant "Have the lists had different sizes?" do
+		one_variable = calculate_some_value
+		other_variable = calculate_some_other_value
+		one_variable > other_variable
+	end
 
 ## References
 
 - [Programming with assertions](http://download.oracle.com/javase/1.4.2/docs/guide/lang/assert.html). A great article on assertions. It is about the Java language, but the concepts it explains apply to any programming language.
-- [Writing Solid Code](http://www.amazon.com/Writing-Solid-Code-Microsoft-Programming/dp/1556155514).
+- [Writing Solid Code](http://www.amazon.com/Writing-Solid-Code-Microsoft-Programming/dp/1556155514). A great book on good coding design practices. Again, it is related to C, but the practices it talks about apply to coding in any programming language.
 
 
 

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

data/solid_assert.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{solid_assert}
-  s.version = "0.5.0"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Jorge Manrubia}]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: solid_assert
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 7
   prerelease: 
   segments: 
   - 0
-  - 5
+  - 6
   - 0
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Jorge Manrubia