ensure_it 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3327ef9e83c77e8983afebc84649fa8dbcfa9539
-  data.tar.gz: b7197ebaf1daf96979bd0192d6c0fc5f7d0ba95d
+  metadata.gz: 5ba3443d9d913fa270efaafb09ed62ff942ccb97
+  data.tar.gz: 1748051d5985f1a9ae54f9eec83d7fd70666695a
 SHA512:
-  metadata.gz: 95223df056bfecb587411ca19861cb87dd7d1c84188e886343be34fb02e597ef716d88d97e1e542d86cb4d4702ec9cc139f464d04b323a25085a665c9cbd9cfa
-  data.tar.gz: ad75c0c7d19b5f58f0d10e58db0179b9a23ec347a8dd66f12e68d059b475692ccc72ecef4b32ccc6a47284e740f1475dd9f30b5eaed111ae2e4dc46d01a61d89
+  metadata.gz: a7c50aa22687707d9ab0940aa8bc66bb5dc90c7da4ede7790f99437359acfed6846bf3ece8dfc23fa4c91afaf1ca1a3d6e9c1e88a8746bf5aca18f9dde96c862
+  data.tar.gz: f998fe70c88c0660373d53faa54a4c6076b3c5bd34c7bf3db4a28cf3598c449ebc9523ae9fa39b7f50c923d582515efa8315affdc0526726e342d9a5a3bc4d50

data/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+.ruby-version
 Gemfile.lock
 InstalledFiles
 _yardoc

data/.travis.yml

@@ -4,7 +4,7 @@ rvm:
   - 2.1.1
   - ruby-head
 env:
-  - USE_REFINES=true USE_COVERALLS=true
-  - USE_REFINES=true USE_COVERALLS=false
-  - USE_REFINES=false USE_COVERALLS=true
-  - USE_REFINES=false USE_COVERALLS=false
+  - USE_REFINES=true
+  - USE_REFINES=false
+#  - USE_REFINES=false USE_COVERALLS=true
+#  - USE_REFINES=false USE_COVERALLS=false

data/Gemfile

@@ -3,4 +3,6 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in ensure_it.gemspec
 gemspec
 
-gem 'coveralls', require: false
+group :test do
+  gem 'coveralls', require: false
+end

data/README.md

@@ -5,24 +5,54 @@
 
 # EnsureIt
 
-This library provides way to check and converts local variables for every-method usage, like arguments checking.
+This library provides way to check and convert local variables for every-method usage, like arguments checking.
 
 The main goal of EnsureIt is to provide as fast executed code as it possible with simple and usable syntax.
 
 > **Note:** this library doesn't support ruby older than `2.0.0`
 
+The simplest example, that you can find at `examples/symbol.rb`:
+
+```ruby
+require 'rubygems'
+require 'bundler/setup'
+require 'ensure_it'
+
+def test(arg)
+  arg.ensure_symbol!
+end
+
+puts test(:symbol).inspect
+puts test('string').inspect
+puts test(0).inspect
+```
+
+gives following output:
+
+```
+$ ruby examples/symbol.rb
+:symbol
+:string
+examples/symbol.rb:6:in `test': argument 'arg' of 'test' method should be a Symbol or a String (EnsureIt::Error)
+  from examples/symbol.rb:11:in `<main>'
+```
+
+At first, string converted to symbol.
+
+Secondary, note on error message. The library magically recognizes that `ensure_symbol!` called for `arg` argument of `test` method.
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-  gem 'ensure_it'
+gem 'ensure_it'
 ```
 
 or for [refinements](#refinements) version:
 
 ```ruby
-  gem 'ensure_it', require: 'ensure_it_refines'
+gem 'ensure_it', require: 'ensure_it_refined'
 ```
 
 And then execute:
@@ -39,7 +69,7 @@ $ gem install ensure_it
 
 ## Configuration
 
-For this moment only one configuration option available - global setting of smart errors (see [Usage section](usage)):
+For this moment only one configuration option available - global setting of smart errors (see [Usage section](#usage)):
 
 ```ruby
 require 'ensure_it'
@@ -52,11 +82,11 @@ end
 
 ## Usage
 
-EnsureIt does monkey-patching or provides refines (see [Refinements section](#refinements)) for general ruby objects with set of `ensure_*` methods. So you can call this methods with everything in ruby. Corresponding to method name it returns `nil` (or raise exception for bang version of method, that name ended with `!`) for unusual or impossible type conversions and returns object of ensured type if conversion is possible.
+EnsureIt does monkey-patching or provides refines (see [Refinements section](#refinements)) for generic ruby objects with set of `ensure_*` methods. So you can call this methods with everything in ruby. Corresponding to method name it returns `nil` (or raise exception for bang version of method, that name ended with `!`) for unusual or impossible type conversions and returns object of ensured type if conversion is possible.
 
 For example `ensure_symbol` method returns symbol itself for Symbols, converted to symbol value for Strings and nil for all other. Same way `ensure_symbol!` returns symbol for String and Symbol, and raises exception for all other.
 
-The special thing, that EnsureIt can do (and do it by default) is smart error messages in bang methods. In most cases, EnsureIt guesses right context in wich `ensure_*` method called and froms more informative message. It recognizes name of local variable if method called for variable like `my_var.ensure_symbol`, argument name, if variable is argument of method and method calls itself like `'some_string'.to_sym.ensure_symbol` - so `ensure_symbol` called on result of `to_sym` method. You can disable this functionality at all (see [Configuration section](configuration)) or override globally configuration for any method call by `smart` option like this `:symbol.ensure_symbol(smart: true)` or `:symbol.ensure_symbol(smart: false)`. In any way, this `:smart` errors doesn't affect execution speed because the analyzing block of code executed only on exception - not on every `ensure_*` call.
+The special thing, that EnsureIt can do (and do it by default) is smart error messages in bang methods. In most cases, EnsureIt guesses right context in wich `ensure_*` method called and froms more informative message. It recognizes name of local variable if method called for variable like `my_var.ensure_symbol`, argument name, if variable is argument of method and method calls itself like `'some_string'.to_sym.ensure_symbol` - so `ensure_symbol` called on result of `to_sym` method. You can disable this functionality at all (see [Configuration section](#configuration)) or override globally configuration for any method call by `smart` option like this `:symbol.ensure_symbol(smart: true)` or `:symbol.ensure_symbol(smart: false)`. In any way, this `:smart` errors doesn't affect execution speed because the analyzing block of code executed only on exception - not on every `ensure_*` call.
 
 For example, following code
 
@@ -84,7 +114,7 @@ end
 awesome(0)
 ```
 
-will produce ArgumentError with message `it's unusual that 'arg' of 'awesome' method with name arg is not a symbol. Raised in ensure_symbol!`.
+will produce ArgumentError with message `it's bad that 'arg' of 'awesome' method with name arg is not a symbol. Raised in ensure_symbol!`.
 
 ### ensure_symbol, ensure_symbol!
 
@@ -94,6 +124,10 @@ Returns self for Symbol, converted value for String, nil (or raise) for other:
 :test.ensure_symbol # => :test
 'test'.ensure_symbol # => :test
 100.ensure_symbol # => nil
+:test.esnure_symbol(values: %i(one two)) # => nil
+:one.esnure_symbol(values: %i(one two)) # => :one
+'test'.esnure_symbol(values: %i(one two)) # => nil
+'one'.esnure_symbol(values: %i(one two)) # => :one
 ```
 
 ### ensure_string, ensure_string!
@@ -153,7 +187,7 @@ By default, returns Array only for Array itself and **empty** array (not nil) fo
 ```ruby
 [1, nil, 2].ensure_array # => [1, nil, 2]
 true.ensure_array # => []
-true.ensure_array(wrong: nil) # => nil
+true.ensure_array(default: nil) # => nil
 [1, nil, 2].ensure_array(compact: true) # => [1, 2]
 [1, [2, 3], 4].ensure_array(flatten: true) # => [1, 2, 3, 4]
 [1, [5, 6], 4].ensure_array(flatten: true, sorted: true) # => [1, 4, 5, 6]
@@ -224,11 +258,17 @@ Array.ensure_class(Enumerable, CustomModule) # => nil
 Array.ensure_class(Enumerable) # => Array
 ```
 
+### Common options for all methods
+
+|option|possible values|meaning|
+|------|---------------|-------|
+|`:values`|Array|(not used in `ensure_instance_of` and `ensure_hash`) an array of possible values. If value doesn't included in this array, default value returned or exception raised for bang methods. Note that library doesn't check types of this array elements, so be sure to specify array with right elements here.
+
 ### Common options for all non-bang methods
 
 |option|possible values|meaning|
 |------|---------------|-------|
-|`:wrong`|any|if present then will be used as wrong value instead of default `nil`|
+|`:default`|any|if present then will be used as wrong value|
 
 ### Common options for all bang methods
 
@@ -242,23 +282,23 @@ Array.ensure_class(Enumerable) # => Array
 
 Since ruby `2.0.0` [refinements](http://www.ruby-doc.org/core-2.1.1/doc/syntax/refinements_rdoc.html) mechanism intorduced and was experimental till `2.1.0`. Starting from `2.1.0` you can use it without warnings and in module and class scope.
 
-EnsureIt is fully tested and working with refinements. But not by default and not for ruby `< 2.1.0`. To use refined version of EnsureIt (with zero-monkey-pathing) just require `ensure_it_refines` instead of `ensure_it`. If you use bundler, you can do it, by specifying `require: 'ensure_it_refines'` option for `gem 'ensure_it'` in your `Gemfile`:
+EnsureIt is fully tested and working with refinements. But not by default and not for ruby `< 2.1.0`. To use refined version of EnsureIt (with zero-monkey-pathing) just require `ensure_it_refined` instead of `ensure_it`. If you use bundler, you can do it, by specifying `require: 'ensure_it_refined'` option for `gem 'ensure_it'` in your `Gemfile`:
 
 ```ruby
-gem 'ensure_it', require: 'ensure_it_refines'
+gem 'ensure_it', require: 'ensure_it_refined'
 ```
 
 Or without bundler:
 
 ```ruby
 # In you code initialization
-require 'ensure_it_refines'
+require 'ensure_it_refined'
 ```
 
 Then activate EnsureIt refines by `using EnsureIt` in needed scope:
 
 ```ruby
-require 'ensure_it_refines'
+require 'ensure_it_refined'
 
 class AwesomeClass
   using EnsureIt
@@ -275,8 +315,68 @@ AwesomeClass.new.awesome_method(0) # => raises EnsureIt::Error with message
 
 Please read carefully [refinements](http://www.ruby-doc.org/core-2.1.1/doc/syntax/refinements_rdoc.html) documentation before using refined EnsureIt. Don't forget to call `using EnsureIt` in every file (not class or method if your class or method placed in many files) you need it.
 
+## Benchmarking
+
+In development mode a set of thor tasks under 'ensure_it:benchmark' namespace provided for benchmarking and profiling any library method. Also tasks `:non_bang`, `:bang` and `:all` provided for benchmarking all non-bang methods, all bang methods and allmost all methods respectively. To benchmark refined version of library, use `USE_REFINES=true` environment variable.
+
+```sh
+thor ensure_it:benchmark:symbol   # benchmark #ensure_symbol method
+thor ensure_it:benchmark:symbol!  # benchmark #ensure_symbol! method
+thor ensure_it:benchmark:non_bang # benchmark all non-bang methods
+thor ensure_it:benchmark:all      # benchmark all library methods
+USE_REFINES=true thor ensure_it:benchmark:all # benchmark refined library
+```
+
+Some results on my machine:
+
+```
+$ thor ensure_it:benchmark:symbol
+Starting benchmarks for #ensure_symbol  with monkey-patched version of EnsureIt. Errors: standard. Ruby version: 2.1.1
+ensure_it:      0.090000   0.000000   0.090000 (  0.083292)
+standard way:   0.050000   0.000000   0.050000 (  0.051999)
+
+$ thor ensure_it:benchmark:symbol!
+Starting benchmarks for #ensure_symbol!  with monkey-patched version of EnsureIt. Errors: standard. Ruby version: 2.1.1
+ensure_it:      6.350000   0.000000   6.350000 (  6.431325)
+standard way:   0.440000   0.000000   0.440000 (  0.435714)
+```
+
+As you can see, call to `#esnure_symbol` is very close to standard type checking (number of benchmark runs - 10000), but bang version consumes much more time. This because we need to do some job to grab information from code for error message. And, of course, this code will execute only when error occured. Call to bang method for expected values (Symbols and Strings in this case) consume same time, as for normal `#ensure_symbol`.
+
+Some options available for benchmarking.
+
+### profiling
+`-p` or `--profile=true` or `--profile=/ouput/dir`. Turns on profiling. If you specify profiling as boolean option, all progiling output will be putted into tmp dir under library root.
+
+```sh
+thor ensure_it:benchmark:symbol -p # benchmark and profile #ensure_symbol
+thor ensure_it:benchmark:symbol --profile=/tmp/emsure_it
+```
+
+### number of examples
+`-n` or `--number`. By default, all benchmarking procs runs 10000 times. You can specify another value with this option.
+
+```sh
+thor ensure_it:benchmark:all -n 1000
+```
+
+### smart errors
+`-s` or `smart=true`. By default smart errors are off for time consuming. You can turn it on by this option.
+
+```sh
+thor ensure_it:benchmark:all -n 1000 -s
+```
+
 ## Changelog
 
+`0.1.2`
+* smart errors refactored
+* benchmarking added
+* `wrong` option changed to `default`
+* `values` option added
+* a lot of code refactored
+* `ensure_it_refines` changed to `ensure_it_refined`
+
 `0.1.1`
 * fixed: no error_class in standard errors mode
 
@@ -297,15 +397,19 @@ Please read carefully [refinements](http://www.ruby-doc.org/core-2.1.1/doc/synta
 
 ## Todo
 
-* enlarge method set
+* class from string converting for ensure_class
+* ensure_file_name
+* ensure_var_name
 * enlarge number of options for arrays and hashes
 * block processing for arrays and hashes
-* benchmarking and profiling
+* rspec matchers
+* ActiveSupport and MongoId integration
 * custom extending functionality support
+* profiling distribution
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/skeleton/fork )
+1. Fork it (http://github.com/cybernetlab/ensure_it/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/ensure_it.gemspec

@@ -36,4 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'redcarpet',  '~> 3.1'
   spec.add_development_dependency 'yard',       '~> 0.8'
   spec.add_development_dependency 'rspec',      '~> 2.14'
+  spec.add_development_dependency 'coveralls',  '~> 0.7'
+  spec.add_development_dependency 'thor',       '~> 0.18'
+  spec.add_development_dependency 'ruby-prof',  '~> 0.14'
 end

data/examples/symbol.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'ensure_it'
+
+def test(arg)
+  arg.ensure_symbol!
+end
+
+puts test(:symbol).inspect
+puts test('string').inspect
+puts test(0).inspect

data/lib/ensure_it/ensure_array.rb

@@ -1,20 +1,20 @@
 module EnsureIt
   patch Object do
-    def ensure_array(*args, **opts)
-      opts.key?(:wrong) ? opts[:wrong] : []
+    def ensure_array(*args, default: [], **opts)
+      default
     end
 
-    def ensure_array!(*args, **opts)
+    def ensure_array!(*args, default: nil, **opts)
       opts[:message] ||= '#{subject} should be an Array'
       EnsureIt.raise_error(:ensure_array!, **opts)
     end
   end
 
   patch Array do
-    using EnsureIt if ENSURE_IT_REFINES
+    using EnsureIt if ENSURE_IT_REFINED
 
-    if ENSURE_IT_REFINES
-      def ensure_array(*args, **opts)
+    if ENSURE_IT_REFINED
+      def ensure_array(*args, values: nil, **opts)
         arr = self
         args.each do |arg|
           arg = arg.ensure_symbol || next
@@ -39,6 +39,7 @@ module EnsureIt
         return arr if opts.empty?
         arr = arr.map { |x| x } if arr == self
         arr.flatten! if opts[:flatten] == true
+        arr.select! { |x| values.include?(x) } if values.is_a?(Array)
         opts[:sorted] ||= opts.delete(:ordered) if opts.key?(:ordered)
         arr.sort! if opts.key?(:sorted)
         arr.reverse! if opts[:sorted].ensure_symbol == :desc
@@ -46,7 +47,7 @@ module EnsureIt
         arr
       end
     else
-      def ensure_array(*args, **opts)
+      def ensure_array(*args, values: nil, **opts)
         arr = self
         args.each do |arg|
           arg = arg.ensure_symbol || next
@@ -55,6 +56,7 @@ module EnsureIt
         return arr if opts.empty?
         arr = arr.map { |x| x } if arr == self
         arr.flatten! if opts[:flatten] == true
+        arr.select! { |x| values.include?(x) } if values.is_a?(Array)
         opts[:sorted] ||= opts.delete(:ordered) if opts.key?(:ordered)
         arr.sort! if opts.key?(:sorted)
         arr.reverse! if opts[:sorted].ensure_symbol == :desc

data/lib/ensure_it/ensure_class.rb

@@ -1,26 +1,32 @@
 module EnsureIt
   patch Object do
-    def ensure_class(*args, **opts)
-      opts.key?(:wrong) ? opts[:wrong] : nil
+    def ensure_class(*args, default: nil, **opts)
+      default
     end
 
-    def ensure_class!(*args, **opts)
+    def ensure_class!(*args, default: nil, **opts)
       opts[:message] ||= '#{subject} should be a class'
       EnsureIt.raise_error(:ensure_class!, **opts)
     end
   end
 
   patch Class do
-    using EnsureIt if ENSURE_IT_REFINES
-
-    def ensure_class(*args, **opts)
+    def ensure_class(*args, default: nil, values: nil, **opts)
       args.select! { |x| x.is_a?(Module) }
-      args.all? { |x| self <= x } ? self : super(**opts)
+      return default unless args.all? { |x| self <= x }
+      if values.nil? || values.is_a?(Array) && values.include?(self)
+        self
+      else
+        default
+      end
     end
 
-    def ensure_class!(*args, **opts)
+    def ensure_class!(*args, default: nil, values: nil, **opts)
       args.select! { |x| x.is_a?(Module) }
-      return self if args.all? { |x| self <= x }
+      if args.all? { |x| self <= x } &&
+         (values.nil? || values.is_a?(Array) && values.include?(self))
+        return self
+      end
       args = args.map!(&:name).join(', ')
       opts[:message] ||=
         "\#{subject} should subclass or extend all of ['#{args}']"

data/lib/ensure_it/ensure_float.rb

@@ -2,47 +2,104 @@ module EnsureIt
   FLOAT_REGEXP = /\A[+\-]?(?:\d+(?:\.\d*)?|\d*\.\d+)(?:[eE][+\-]?\d+)?\z/
 
   patch Object do
-    def ensure_float(**opts)
-      opts.key?(:wrong) ? opts[:wrong] : nil
+    def ensure_float(default: nil, **opts)
+      default
     end
 
-    def ensure_float!(**opts)
-      opts[:message] ||= '#{subject} should be a float or be able' \
-                         ' to convert to it'
-      EnsureIt.raise_error(:ensure_float!, **opts)
+    def ensure_float!(default: nil, **opts)
+      EnsureIt.raise_error(
+        :ensure_float!,
+        **EnsureIt::ensure_float_error_options(**opts)
+      )
     end
   end
 
   patch String do
-    using EnsureIt if ENSURE_IT_REFINES
-
-    def ensure_float(**opts)
-      self =~ FLOAT_REGEXP ? to_f : nil
+    def ensure_float(default: nil, values: nil, **opts)
+      return default unless self =~ FLOAT_REGEXP
+      value = to_f
+      if values.nil? || values.is_a?(Array) && values.include?(value)
+        value
+      else
+        default
+      end
     end
 
-    def ensure_float!(**opts)
-      ensure_float(**opts) || super(**opts)
+    def ensure_float!(default: nil, values: nil, **opts)
+      if self =~ FLOAT_REGEXP
+        value = to_f
+        if values.nil? || values.is_a?(Array) && values.include?(value)
+          return value
+        end
+      end
+      EnsureIt.raise_error(
+        :ensure_float!,
+        **EnsureIt::ensure_float_error_options(**opts)
+      )
     end
   end
 
   patch Integer do
-    def ensure_float(**opts)
-      to_f
+    def ensure_float(default: nil, values: nil, **opts)
+      return to_f if values.nil?
+      value = to_f
+      values.is_a?(Array) && values.include?(value) ? value : default
+    end
+
+    def ensure_float!(default: nil, values: nil, **opts)
+      return to_f if values.nil?
+      value = to_f
+      return values if values.is_a?(Array) && values.include?(value)
+      EnsureIt.raise_error(
+        :ensure_float!,
+        **EnsureIt::ensure_float_error_options(**opts)
+      )
     end
-    alias_method :ensure_float!, :ensure_float
   end
 
   patch Float do
-    def ensure_float(**opts)
-      self
+    def ensure_float(default: nil, values: nil, **opts)
+      if values.nil? || values.is_a?(Array) && values.include?(self)
+        self
+      else
+        default
+      end
+    end
+
+    def ensure_float!(default: nil, values: nil, **opts)
+      if values.nil? || values.is_a?(Array) && values.include?(self)
+        return self
+      end
+      EnsureIt.raise_error(
+        :ensure_float!,
+        **EnsureIt::ensure_float_error_options(**opts)
+      )
     end
-    alias_method :ensure_float!, :ensure_float
   end
 
   patch Rational do
-    def ensure_float(**opts)
-      to_f
+    def ensure_float(default: nil, values: nil, **opts)
+      return to_f if values.nil?
+      value = to_f
+      values.is_a?(Array) && values.include?(value) ? value : default
+    end
+
+    def ensure_float!(default: nil, values: nil, **opts)
+      return to_f if values.nil?
+      value = to_f
+      return values if values.is_a?(Array) && values.include?(value)
+      EnsureIt.raise_error(
+        :ensure_float!,
+        **EnsureIt::ensure_float_error_options(**opts)
+      )
+    end
+  end
+
+  def self.ensure_float_error_options(**opts)
+    unless opts.key?(:message)
+      opts[:message] = '#{subject} should be a float or be able' \
+                       ' to convert to it'
     end
-    alias_method :ensure_float!, :ensure_float
+    opts
   end
 end

data/lib/ensure_it/ensure_hash.rb

@@ -1,20 +1,20 @@
 module EnsureIt
   patch Object do
-    def ensure_hash(*args, **opts)
-      opts.key?(:wrong) ? opts[:wrong] : {}
+    def ensure_hash(*args, default: {}, **opts)
+      default
     end
 
-    def ensure_hash!(*args, **opts)
+    def ensure_hash!(*args, default: nil, **opts)
       opts[:message] ||= '#{subject} should be a Hash'
       EnsureIt.raise_error(:ensure_hash!, **opts)
     end
   end
 
   patch Hash do
-    using EnsureIt if ENSURE_IT_REFINES
+    using EnsureIt if ENSURE_IT_REFINED
 
     def ensure_hash(*args, **opts)
-      return self if opts[:symbolize_keys] != true
+      return self if opts.empty? || opts[:symbolize_keys] != true
       Hash[map { |k, v| [k.ensure_symbol, v] }.reject { |x| x[0].nil? }]
     end
     alias_method :ensure_hash!, :ensure_hash

data/lib/ensure_it/ensure_instance_of.rb

@@ -1,17 +1,16 @@
 module EnsureIt
   patch Object do
-    def ensure_instance_of(klass, **opts)
+    def ensure_instance_of(klass, default: nil, **opts)
       unless klass.is_a?(Class)
         fail(
           ArgumentError,
           'Wrong class argument for #ensure_instance_of specified'
         )
       end
-      return self if is_a?(klass)
-      opts.key?(:wrong) ? opts[:wrong] : nil
+      is_a?(klass) ? self : default
     end
 
-    def ensure_instance_of!(klass, **opts)
+    def ensure_instance_of!(klass, default: nil, **opts)
       unless klass.is_a?(Class)
         fail(
           ArgumentError,