README.md in simplecheck-1.0 vs README.md in simplecheck-2.0

- old
+ new

@@ -1,11 +1,13 @@ # Simplecheck -Simplecheck is a lightweight property checking API for Ruby designed to quickly check arguments. Once included into a class it provides the `check` instance method which takes arguments and a condition to check them against. +Simplecheck is a lightweight property checking API for Ruby designed to quickly check arguments in under 50 lines of Ruby. Once included into a class it provides the `check` instance method which takes arguments and a condition to check them against. If a check fails a `Simplecheck::CheckFailed` exception is raised. +Simplecheck is compatiable with Ruby 2.0.0 and above only. + ## Installation Simplecheck is available as a Rubygem installable via [gem install simplecheck](http://rubygems.org/gems/simplecheck). A git repository is also available at [http://github.com/farrel/simplecheck](http://github.com/farrel/simplecheck). @@ -18,87 +20,102 @@ include Simplecheck attr_accessor( :name, :age ) def initialize( name, age ) - check( name, String ) # Check name is String - check( age, 18..75 ) # Check age is within Range + check(name, String, error_message: 'name must be a String') # Check name is String with custom error message + check(age, 18..75) # Check age is within Range @name, @age = name, age end end - Customer.new( "Joe", 25 ) # No error - Customer.new( nil, 25 ) rescue puts "Name can not be nil" - Customer.new( "Joe", 15 ) rescue puts "Age is out of range" + Customer.new("Joe", 25) # No error + begin + Customer.new(nil, 25) + rescue Simplecheck::CheckFailed => exception + puts exception.message # => 'name must be a String' + ebd + + begin + Customer.new("Joe", 15) + rescue Simplecheck::CheckFailed => exception + puts exception.message # => '15 does not satisfy 18..75' + ebd + ## Check Methods Simplecheck currently supports three different check methods: * Expression Check * Case Equality (===) Check * Block Check +### Custom Error Message + +All check methods may take an optional named parameter `error_message` to override the default error message. + + check(age, Integer, error_message: 'Age must be an whole number') + ### Expression Check In the simplest case `check` takes an expression as an argument. If the expression evaluates to `nil` or `false` it will fail. def calculate_percentage( score, total ) - check( total > 0 ) + check(total > 0) 100.0 * score / total end ### Case Equality (===) Check If two or more arguments are given without a block, then the last argument becomes the condition against which the previous arguments are checked. To accomplish this the condition argument should implement the case equality operator (`===` or threequal) in a logical manner. - def greatest_common_divisor( a, b ) - check( a, b, Integer ) + def greatest_common_divisor(a, b) + check(a, b, Integer) # GCD Algorithm... end If a class does not alias or implement it's own version of `===` it has the same functionality as `==`. The following Ruby Core classes already alias `===` to various instance methods. - #### Class `===` is aliased to `kind_of?`: - check( age, Numeric ) + check(age, Numeric) #### Range `===` is aliased to `include?`: - check( age, 18..75 ) + check(age, 18..75) #### Regexp -`===` is aliased to `match`: +`===` is aliased to `=~`: - check( phone_number, /^\d\d\d-\d\d\d\d$/ ) + check(phone_number, /^\d\d\d-\d\d\d\d$/) #### Proc `===` is aliased to `call`: - check( password, password_confirmation , ->(p){ !Dict.lookup( p )}) + check(password, password_confirmation , ->(p) { !Dict.lookup(p) }) #### Custom Check Object The default behaviour of `Object#===` is the same as `Object#==`. To customise the behaviour implement your own `Object#===` method. For example to check whether a set of points is inside a given polygon we would implement `Polygon#===` as a [point-in-polygon algorithm](https://en.wikipedia.org/wiki/Point_in_polygon), allowing us to carry out the check using a Polygon instance: - check( point_1, point_2, polygon ) + check(point_1, point_2, polygon) ### Block Check A block can be passed to `check`, with the arguments passed to `check` then passed individually to the block: - check( a, b, c ) do |n| + check(a, b, c) do |n| n.odd? end This is syntactic sugar for the Proc Case Equality check. @@ -113,20 +130,5 @@ ## Resources * Git repository - [http://github.com/farrel/simplecheck](http://github.com/farrel/simplecheck) * Rubygem page - [http://rubygems.org/gems/simplecheck](http://rubygems.org/gems/simplecheck) - -## License -Simplecheck is released under the BSD License. - -Copyright 2013 AIMRED CC. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY AIMRED CC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AIMRED CC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of AIMRED CC.