optioning 0.0.1.beta → 0.0.1

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: fc150f3f4fa42753cb3c1011ad5b600ee99161ba
-  data.tar.gz: 81fab4b72bd887253736ef73fb4f410c46b70bac
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTNiNDg2OWNhZTkwNDIwYTk1MGYzYTBmMzQyMmU0ZTZjZmIyYmE4OA==
+  data.tar.gz: !binary |-
+    Nzc3YjdmYjNjOTYwOGZlMDg0MmRkNWM4ODA4OTI5MjczNGM0MWFiMw==
 SHA512:
-  metadata.gz: e1755b2e41aa8dd4cb98a9aa04603e9c0670722954ccb711ef6480317ba8d4a070cf30cb01587239a98d99ee8279c4ce670db7ea2bb46a46cc305c3112312c1b
-  data.tar.gz: c1072d7a3dd4b834ef7587027f9afc3da134998b5feaa0eae7f3a1da4436dded1b2add9edc2130e71847ce392af650668c39415d947dab658aaddb5ca9733d63
+  metadata.gz: !binary |-
+    NDYyYTI5YWNhZDUwYTBlNGJiMjFhMDEyZTRlOWFlZDFlOGNkOGRiMDgxMzRi
+    MTk0NjAwMWFkY2U4ZWYxMjM4MzE1NWM3NWQyOGViZDgyYTNmM2E2ODk0OTRi
+    MjM5YjBmNDg0ZjY0YTJlYjlmN2RlMTg4NzU5NDcwYzkwZGRjMjk=
+  data.tar.gz: !binary |-
+    NTA3YWY5MGU3MDQ1MjdhY2UyMzI0MmI0ZjI4ZTk3YTNiODdlNTE1OWM4Yzhj
+    Mjg0YzQ2YzQ4ZjBiZGYzYmYxNmUzYTUxN2YxNWVmYjliYTg4NGNhMjhlOWU5
+    NzUzMjZjOTNlNjY1ZTg4YzJlMWE5MTQxNTQxMDE2MWZkZWIyZTk=

data/README.md

@@ -1,13 +1,14 @@
 # Optioning
 
 An easy way to retrieve, store, filter, transform and deprecate `options` passed
-to a method. Where `options` are the keys our beloved `Hash` as last parameter
-for a method call.
+to a method. Where `options` are the keys in our beloved `Hash` as last parameter
+in a method call.
 
 ## Status
 [![Gem Version](https://badge.fury.io/rb/optioning.svg)](http://badge.fury.io/rb/hashing)
 [![Build Status](https://travis-ci.org/ricardovaleriano/optioning.svg?branch=master)](http://travis-ci.org/ricardovaleriano/hashing?branch=master)
 [![Code Climate](https://codeclimate.com/github/ricardovaleriano/optioning.png)](https://codeclimate.com/github/ricardovaleriano/hashing)
+[![Inline docs](http://inch-pages.github.io/github/ricardovaleriano/optioning.png)](http://inch-pages.github.io/github/ricardovaleriano/optioning)
 
 ## Installation
 
@@ -31,6 +32,54 @@ Or install it yourself as:
 
 ## Usage
 
+### An "end to end" example
+
+Given a `Hashing` module, with a `.hasherize` method like this:
+
+```ruby
+module Hashing
+  def hasherize(*values_and_options)
+    optioning = Optioning.new values_and_options
+    optioning.deprecate :to_hash, :to, "v2.0.0"
+    optioning.recognize :persist
+    optioning.process caller
+
+    puts "*" * 80
+    puts optioning.on :to
+    puts optioning.on :persist
+  end
+end
+```
+
+And a `class` `Client` extending the `Hashing` and invoking the `.hasherize`
+method like in this example:
+
+```ruby
+require "./hashing"
+class Client
+  extend Hashing
+
+  hasherize :some_ivar, to_hash: ->(){}, store: "NO!", persist: "I will persist!"
+end
+```
+
+The following output will be generated:
+
+```
+NOTE: option `:to_hash` is deprecated; use `:to` instead. It will be removed on or after version v2.0.0.
+Called from examples/client_maroto.rb:5:in `<class:Client>'.
+NOTE: unrecognized option `:store` used.
+You should use only the following: `:to`, `:persist`
+Called from examples/client_maroto.rb:5:in `<class:Client>'.
+********************************************************************************
+#<Proc:0x007fd6f42749a8@examples/client_maroto.rb:5 (lambda)>
+I will persist!
+```
+
+The warning messages will be written in the `$stderr`. Done! :smiley:
+
+### A more step by step example
+
 Given the following `File` class:
 
 ```ruby
@@ -85,13 +134,13 @@ methods:
 
 ```ruby
 @options.raw
-# => [:path, :commit, {to_hash: #<Proc:0x007fa4120bd318@(irb):1 (lambda)>}]
+# => [:path, :commit, {to_hash: #<Proc:0x007fa4120bd318@(irb):42 (lambda)>}]
 
 @options.values
 # => [:path, :commit]
 
 @options.on :to_hash
-# => #<Proc:0x007fa4120bd318@(irb):1 (lambda)>
+# => #<Proc:0x007fa4120bd318@(irb):42 (lambda)>
 ```
 
 ### Deprecating options
@@ -102,7 +151,7 @@ favor of the new `:to` option, you could do:
 ```ruby
 def hasherize(*ivars_and_options)
   @options = Optioning.new ivars_and_options
-  @options.deprecate :to_hash, :to, Date.new(2015, 05, 01)
+  @options.deprecate :to_hash, :to
 
   # ...
 end
@@ -113,9 +162,9 @@ so you can do the following invocation to recover the value passed to the
 deprecated `option`:
 
 ```ruby
-@options.on :to_hash
+@options.on :to
 
-# => #<Proc:0x007fa4120bd318@(irb):1 (lambda)>
+# => #<Proc:0x007fa4120bd318@(irb):42 (lambda)>
 ```
 
 #### Deprecation warnings
@@ -127,17 +176,21 @@ method:
 def hasherize(*ivars_and_options)
   @options = Optioning.new ivars_and_options
   @options.deprecate :to_hash, :to
-  @options.deprecated_warn
+  @options.deprecation_warn
 
   # ...
 end
 ```
 
 You can inform the date when the deprecation will not be available anymore.
-These date will be parte of the deprecation message:
+These date will be part of the deprecation message:
 
 ```ruby
-@options.deprecate :to_hash, :to, Date.new(2015, 05, 01)
+@options.deprecate :to_hash, :to, 2015, 05
+@options.deprecation_warn
+
+# => NOTE: option `:to_hash` is deprecated use `:to` instead. It will be
+#    removed on or after 2015-05-01."
 ```
 
 Or if you prefer, you can specify a version of your software that pretend to
@@ -145,8 +198,39 @@ remove the deprecated thing:
 
 ```ruby
 @options.deprecate :to_hash, :to, "v2.0.0"
+@options.deprecation_warn
+
+# => NOTE: option `:to_hash` is deprecated use `:to` instead. It will be
+#    removed on or after version v2.0.0"
 ```
 
+And finally, you can add information about where te deprecated option was used
+by passing the `caller` to the `deprecation_warn` method.
+
+##### Caller info
+
+Sometimes you will want to show information about where the call with the
+deprecated option took place. If this is the case, you can pass the caller info
+when instantiating the `Optioning`:
+
+```ruby
+def hasherize(*ivars_and_options)
+  @options = Optioning.new ivars_and_options
+  @options.deprecate :to_hash, :to
+  @options.deprecated_warn caller
+
+  # ...
+end
+```
+
+##### Calling a deprecated option
+
+If you call a deprecated option, the return will be `nil`, and the deprecation
+warning will be exhibited.
+
+ * [ ] maybe we should allow a deprecation strategy? To choose between warning
+   or exception when a deprecated options is called?
+
 ### Ignoring unrecongnized options
 
 If you need, you could fitler the options to mantain just the recognized ones
@@ -157,19 +241,19 @@ the `#unrecognized_warn` method:
 ```ruby
 def hasherize(*ivars_and_options)
   @options = Optioning.new ivars_and_options
-  @options.recognize :to_hash
+  @options.recognize :from
   @options.unrecognized_warn
 
   # ...
 end
 ```
 
-Now, if a user pass an option different than the `:to_hash` one, a warning will
+Now, if a user pass an option different than the `:from` one, a warning will
 inform that the option is not recognized and will be ignored.
 
 #### Do I Need to register deprecated options as recognized?
 
-Fortunatelly no. You just need to register your deprecations as usual:
+Fortunately no. You just need to register your deprecations as usual:
 
 ```ruby
 def hasherize(*ivars_and_options)
@@ -203,6 +287,14 @@ def hasherize(*ivars_and_options)
 end
 ```
 
+If you want the deprecation warning messages with the information about where
+the deprecated options were passed, you can pass the `caller` info to the
+`process` method:
+
+```ruby
+@options.process caller
+```
+
 ### Fluent interface
 
 And finally, just for a matter of taste, `#deprecate`, `#recognize` and
@@ -220,7 +312,7 @@ end
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/optioning/fork )
+1. Fork it ( http://github.com/ricardovaleriano/optioning/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/examples/client_maroto.rb

@@ -0,0 +1,6 @@
+require_relative "./module_maroto"
+class Client
+  extend Maroto
+
+  hasherize :some_ivar, to_hash: ->(){}, store: "NO!", persist: "I will persist!"
+end

data/examples/module_maroto.rb

@@ -0,0 +1,20 @@
+begin
+  require "optioning"
+rescue LoadError => e
+  $:.unshift File.expand_path "../../lib", __FILE__
+  require "optioning"
+end
+
+module Maroto
+  def hasherize(*values_and_options)
+    optioning = Optioning.new values_and_options
+    optioning.deprecate :to_hash, :to, "v2.0.0"
+    optioning.recognize :persist
+    optioning.process caller
+
+    puts "\n"
+    puts "*" * 80
+    puts optioning.on :to
+    puts optioning.on :persist
+  end
+end

data/lib/deprecation.rb

@@ -0,0 +1,73 @@
+# Represent a deprecated option.
+# Util to store deprecated options for future reference.
+class Deprecation
+  attr_reader :option, :replacement, :date, :version
+  attr_writer :caller
+
+  # Creates a representation of a {Deprecation}
+  #
+  # @example using a version as a deadline to deprecate
+  #   deprecation = Deprecation.new :to_hash, :to, "v2.0.0"
+  #   deprecation.warn
+  #   # => NOTE: option `:to_hash` is deprecated; use `:to` instead. It will be
+  #   #    removed on or after version v2.0.0.
+  #
+  # @example using a date (YYYY/MM) as a deadline to deprecate
+  #   deprecation = Deprecation.new :to_hash, :to, 2015, 05
+  #   deprecation.warn
+  #   # => NOTE: option `:to_hash` is deprecated; use `:to` instead. It will be
+  #   #    removed on or after 2015-05-01.
+  #
+  # @example using the caller information to compose the warn message
+  #   deprecation = Deprecation.new :to_hash, :to, "v2.0.0"
+  #   deprecation.warn
+  #   deprecation.caller = caller
+  #   # => NOTE: option `:to_hash` is deprecated; use `:to` instead. It will be
+  #   #    removed on or after version v2.0.0.
+  #   #    Called from examples/client_maroto.rb:5:in `<class:Client>'.
+  def initialize(option, replacement, version_or_year = nil, month = nil)
+    @option = option
+    @replacement = replacement
+    @date, @version = extract_date_and_version version_or_year, month
+  end
+
+  # Composes the deprecation message accordingly to date or version of
+  # deprecation. Also verifies (and show) the caller information.
+  #
+  # @return [String]
+  def warn
+    message = [ "NOTE: option `:#{@option}` is deprecated; use ",
+                "`:#{@replacement}` instead. ",
+                "It will be removed #{when_deprecation_occurs}."]
+    message << "\nCalled from #{@caller}." if @caller
+    message.join << "\n"
+  end
+
+  private
+  # Decides if the parameters related to when a deprecation will occur are date
+  # or version based.
+  #
+  # @return [Array<Date, String>] the [Date] or version (string) for a deprecation
+  def extract_date_and_version(version_or_year, month)
+    date, version = nil, nil
+    if month.nil?
+      version = version_or_year
+    else
+      date = Date.new version_or_year, month, 1
+    end
+    [date, version]
+  end
+
+  # Returns a string ready to be used in a message, indicating when a
+  # deprecation will occur (based on date or version).
+  #
+  # @return [String]
+  def when_deprecation_occurs
+    if @date || @version
+      after = "on or after "
+      after += @date ? @date.strftime("%Y-%m-%d") : "version #{@version}"
+    else
+      "in a future version"
+    end
+  end
+end

data/lib/optioning/version.rb

@@ -1,3 +1,3 @@
-module Optioning
-  VERSION = "0.0.1.beta"
+class Optioning
+  VERSION = "0.0.1"
 end

data/lib/optioning.rb

@@ -1,5 +1,183 @@
 require "optioning/version"
+require "deprecation"
 
-module Optioning
-  # Your code goes here...
+class Optioning
+  # Receives a varargs to extract the values (anything before a last parameter
+  # `Hash`) and the options (last parameter instance_of `Hash`)
+  #
+  # These values can be retrieved using the methods {#values}, {#raw} and {#on}.
+  #
+  # @example a standard usage
+  #   @options = Optioning.new :path, :commit, to_hash: ->(value) { value.upcase }
+  #   @options.deprecate :to_hash, :to, Date.new(2015, 05, 01)
+  #
+  #   @ivars = @options.values
+  #   # => [:path, :commit]
+  #
+  #   @to = @options.on :to
+  #   # => #<Proc:0x8d99c54@(irb):42 (lambda)>
+  def initialize(args)
+    @args = args
+    @values = @args.dup
+    @options = @values.pop if @args.last.is_a? Hash
+  end
+
+  # Return the value for a specific option
+  #
+  # @example
+  #   @option = Optioning.new [:path, :commit, stored_value: 42]
+  #   @option.on :stored_value
+  #   # => 42
+  #
+  # @param option [Symbol] (or Object used as an index) name of option to retrieve
+  # @return value for option passed as parameter
+  def on(option)
+    replace_deprecations
+    @options[option]
+  end
+
+  # Creates a deprecation for an option, stores info about it's replacement
+  # and time or version to its removal.
+  #
+  # @example
+  #   @option = Optioning.new :path, :commit, to_hash: ->(value) { value.upcase }
+  #   @option.deprecate :to_hash, :to, Date.new(2015, 05, 01)
+  #
+  # @param option [Symbol] option to be deprecated
+  # @param replacement [Symbol] replacement option
+  # @param version_or_year version when the deprecation will be removed, if
+  #   month is filled, this param will be treated as the year of replacement
+  # @param month [Integer] month when the deprecated option will be removed
+  # @return [Optioning] the current instance of optioning
+  def deprecate(option, replacement, version_or_year = nil, month = nil)
+    deprecations << Deprecation.new(option, replacement, version_or_year, month)
+    recognize(replacement)
+    self
+  end
+
+  # Provides a way to inform which options can be used and which will be ignored
+  # by an instance of {Optioning}
+  #
+  # @example
+  #   @options = Optioning.new :path, :commit, to_hash: ->(value) { value.upcase }
+  #   @options.deprecate :to_hash, :to, Date.new(2015, 05, 01)
+  #
+  # @param options [Array<Symbol>] all recognized options for the current {Optioning}
+  # @return [Optioning] the current {Optioning} instance
+  def recognize(*options)
+    @recognized ||= []
+    @recognized += options
+    self
+  end
+
+  # Issues all deprecation messages to the $stderr
+  #
+  # @param called_from [Array] expected to be the result of calling `caller`
+  # @return [Optioning] current {Optioning} instance
+  def deprecation_warn(called_from = nil)
+    set_caller_on_deprecations(called_from)
+    deprecations.select { |deprecation|
+      deprecated_but_used.include? deprecation.option
+    }.each { |deprecation| $stderr.write deprecation.warn }
+    self
+  end
+
+  # Issues all unrecognized messages and the recognized_options message to the $stderr
+  #
+  # @param called_from [Array<String>] the result of calling {Object#caller}
+  # @return [Optioning] the current {Optioning} instance
+  def unrecognized_warn(called_from = nil)
+    unrecognized_options.each do |unrecognized|
+      $stderr.write "NOTE: unrecognized option `:#{unrecognized}` used.\n"
+    end
+    recognized_options_warn called_from
+    self
+  end
+
+  # Issues the deprecation warnings and the unrecognized warnings.
+  # Let the current {Optioning} in a `ready to use` state.
+  #
+  # @param called_from [Array<String>] the result of calling {Object#caller}
+  # @return [Optioning] the current {Optioning} instance
+  def process(called_from = nil)
+    deprecation_warn called_from
+    unrecognized_warn called_from
+    self
+  end
+
+  # Return all values passed as varargs to the constructor.
+  #
+  # @return [Array] all values passed to the constructor
+  def raw
+    @args
+  end
+
+  # Return all the values passed before the last one (if this one is a `Hash`
+  # instance).
+  #
+  # @return [Array] arguments that are not part of the options `Hash`
+  def values
+    @values
+  end
+
+  private
+  # Memoization for the `deprecations` created by invocations of {#deprecate}
+  #
+  # @return [Array<Deprecation>] all {Deprecation}s for these {Optioning} instance
+  def deprecations
+    @deprecations ||= []
+  end
+
+  # Memoization for the `recognized` options created by {#recognize}
+  #
+  # @return [Array<Symbol>] all options recognized by this {Optioning}
+  def recognized
+    @recognized ||= []
+  end
+
+  # Cleanup the options trashing up the deprecated options in favor the
+  # replacements.
+  #
+  # @return [Hash] @options already filtered
+  def replace_deprecations
+    deprecations.each do |deprecation|
+      @options[deprecation.replacement] = @options.delete deprecation.option
+    end
+    @options
+  end
+
+  # All unrecognized options used as parameter to an {Optioning}
+  #
+  # @return [Array<Symbol>] unrecognized options
+  def unrecognized_options
+    values = raw.dup
+    return [] unless values.last.is_a? Hash
+    options = values.pop
+    options.keys - (recognized + deprecations.map { |d| d.option.to_sym })
+  end
+
+  # Issues a message containing all the recognized options for an {Optioning}
+  #
+  # @param called_from [Array<String>] the result of calling {Kernel#caller}
+  def recognized_options_warn(called_from = nil)
+    recognized = @recognized.map { |option| "`:#{option}`" }
+    $stderr.write "You should use only the following: #{recognized.join(", ")}"
+    $stderr.write "\nCalled from #{called_from.first}." if called_from.respond_to? :first
+  end
+
+  # Configure the caller in all the deprecations for this instance
+  #
+  # @return [Array<Deprecations>]
+  def set_caller_on_deprecations(called_from)
+    return unless called_from.respond_to? :first
+    deprecations.each { |deprecation| deprecation.caller = called_from.first }
+  end
+
+  # All deprecated options that were passed to the constructor for this instance
+  # of {Optioning}
+  #
+  # @return [Array<Symbol>] deprecated options used in the construction of a {Optioning}
+  def deprecated_but_used
+    deprecations.map(&:option).select { |option| @options.include? option  }
+  end
 end

data/optioning.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["ricardo.valeriano@gmail.com"]
   spec.summary       = %q{An object oriented way to treat our beloved last parameter: Hash.}
   spec.description   = %q{An easy way to retrieve, store, filter and deprecate `options` passed to a method. Where `options` are the keys on our beloved `Hash` as last parameter for a method call.}
-  spec.homepage      = ""
+  spec.homepage      = "http://github.com/ricardovaleriano/optioning"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/test/deprecation_test.rb

@@ -0,0 +1,92 @@
+describe Deprecation do
+  let(:to_hash_lambda) { ->(value) { value } }
+  let(:optioning) { Optioning.new [:path, :commit, to_hash: to_hash_lambda] }
+
+  it "stores the option deprecated and the replacement" do
+    deprecation = Deprecation.new :to_hash, :to
+    deprecation.option.must_be :==, :to_hash
+    deprecation.replacement.must_be :==, :to
+  end
+
+  it "accepts the date of deprecation" do
+    deprecation = Deprecation.new :to_hash, :to, 2015, 3
+    deprecation.date.must_be :==, Date.new(2015, 03, 01)
+  end
+
+  it "accepts a version of deprecation" do
+    deprecation = Deprecation.new :to_hash, :to, "v2.0.0"
+    deprecation.version.must_be :==, "v2.0.0"
+  end
+
+  describe "#warn" do
+    it "without version or date" do
+      deprecation = Deprecation.new :to_hash, :to
+      deprecation.warn.must_be :==, "NOTE: option `:to_hash` is deprecated;"+
+        " use `:to` instead. It will be removed in a future version.\n"
+    end
+
+    it "returns the message to warn about deprecation" do
+      deprecation = Deprecation.new :to_hash, :to, "v2.0.0"
+      deprecation.warn.must_be :==, "NOTE: option `:to_hash` is deprecated;"+
+        " use `:to` instead. It will be removed on or after version v2.0.0.\n"
+    end
+
+    it "uses date to deprecate when it is available" do
+      deprecation = Deprecation.new :to_hash, :to, 2015, 3
+      deprecation.warn.must_be :==, "NOTE: option `:to_hash` is deprecated;"+
+        " use `:to` instead. It will be removed on or after 2015-03-01.\n"
+    end
+
+    describe "when caller is available" do
+      let(:deprecation) { Deprecation.new :to_hash, :to, "v2.0.0" }
+      before do
+        deprecation.caller = "/x/p/t/o/omg_lol_bbq.rb:42:in `hasherize'"
+      end
+
+      it "deprecation message includes caller info" do
+        deprecation.warn.must_be :==, "NOTE: option `:to_hash` is deprecated;"+
+          " use `:to` instead. It will be removed on or after version v2.0.0.\n"+
+          "Called from /x/p/t/o/omg_lol_bbq.rb:42:in `hasherize'.\n"
+      end
+    end
+  end
+
+  describe Optioning do
+    describe "#deprecate" do
+      it "returns the instance of `Optioning`" do
+        optioning.deprecate(:to_hash, :to).must_be_same_as optioning
+      end
+
+      it "replaces the deprecate option" do
+        optioning.deprecate :to_hash, :to
+        optioning.on(:to).object_id.must_be :==, to_hash_lambda.object_id
+      end
+    end
+
+    describe "#deprecation_warn" do
+      before do
+        @original_stderr, $stderr = $stderr, StringIO.new
+        optioning.deprecate :to_hash, :to, "v2.0.0"
+      end
+
+      after do
+        $stderr = @original_stderr
+      end
+
+      it "constructs a deprecation message accordingly to the arguments" do
+        optioning.deprecation_warn
+        deprecation = Deprecation.new :to_hash, :to, "v2.0.0"
+        $stderr.string.must_be :==, deprecation.warn
+      end
+
+      it "uses the callee information to compose the warning message" do
+        optioning.deprecation_warn [
+          "examples/client_maroto.rb:5:in `<class:Client>'",
+          "examples/client_maroto.rb:2:in `<main>'"]
+        deprecation = Deprecation.new :to_hash, :to, "v2.0.0"
+        deprecation.caller = "examples/client_maroto.rb:5:in `<class:Client>'"
+        $stderr.string.must_be :==, deprecation.warn
+      end
+    end
+  end
+end

data/test/optioning_test.rb

@@ -0,0 +1,78 @@
+describe Optioning do
+  let(:to_hash_lambda) { ->(value) { value } }
+  let(:optioning) { Optioning.new [:path, :commit, to_hash: to_hash_lambda] }
+
+  before do
+    @original_stderr, $stderr = $stderr, StringIO.new
+  end
+
+  after do
+    $stderr = @original_stderr
+  end
+
+  describe "#process" do
+    let(:optioning) {
+      Optioning.new [:path, :commit,
+        old: "OH!",
+        from: ->(){},
+        omg: "O YEAH!",
+        wtf: "?"]
+    }
+
+    before do
+      optioning.deprecate :old, :new
+      optioning.deprecate :from_hash, :from
+      optioning.recognize :omg
+    end
+
+    it "returns the instance of `Optioning`" do
+      optioning.process.must_be_same_as optioning
+    end
+
+    it "shows deprecations and unrecognized warnings" do
+      optioning.process
+      $stderr.string.must_be :==,[
+        "NOTE: option `:old` is deprecated;",
+        " use `:new` instead. It will be removed in a future version.\n",
+
+        "NOTE: unrecognized option `:wtf` used.",
+        "\nYou should use only the following: `:new`, `:from`, `:omg`"
+      ].join
+    end
+
+    it "accepts the caller info as argument" do
+      optioning.process [
+        "examples/client_maroto.rb:5:in `<class:Client>'",
+        "examples/client_maroto.rb:2:in `<main>'"]
+
+      $stderr.string.must_be :==,[
+        "NOTE: option `:old` is deprecated;",
+        " use `:new` instead. It will be removed in a future version.\n",
+        "Called from examples/client_maroto.rb:5:in `<class:Client>'.\n",
+
+        "NOTE: unrecognized option `:wtf` used.",
+        "\nYou should use only the following: `:new`, `:from`, `:omg`\n",
+        "Called from examples/client_maroto.rb:5:in `<class:Client>'.",
+      ].join
+    end
+  end
+
+  describe "#raw" do
+    it "transforms the var args passed to the constructor into an Array" do
+      optioning.raw.must_be :==, [:path, :commit, to_hash: to_hash_lambda]
+    end
+  end
+
+  describe "#values" do
+    it "the arguments passed before the last one (if it is a `Hash`)" do
+      optioning.values.must_be :==, [:path, :commit]
+    end
+  end
+
+  describe "#on" do
+    it "returns the value passed to specific option" do
+      # impossible to use lambda.must_be_same_as, maybe a bug?
+      optioning.on(:to_hash).object_id.must_be :==, to_hash_lambda.object_id
+    end
+  end
+end

data/test/unrecognized_option_test.rb

@@ -0,0 +1,60 @@
+describe Optioning do
+  let(:optioning) {
+    Optioning.new [from: "xpto", to: "bbq", no_one_knows: "omg lol"]
+  }
+
+  before do
+    @original_stderr, $stderr = $stderr, StringIO.new
+  end
+
+  after do
+    $stderr = @original_stderr
+  end
+
+  describe "#recognize" do
+    it "returns the instance of `Optioning`" do
+      optioning.recognize(:x).must_be_same_as optioning
+    end
+  end
+
+  describe "#unrecognized_warn" do
+    it "should not warning about a recognized option" do
+      optioning.recognize :from
+      optioning.unrecognized_warn
+      ($stderr.string =~ /unrecognized option `:from`/).must_be :==, nil
+    end
+
+    it "should warning about a unrecognized option" do
+      optioning.recognize :from, :to
+      optioning.unrecognized_warn
+      $stderr.string.must_be :==, "NOTE: unrecognized option `:no_one_knows` used."+
+        "\nYou should use only the following: `:from`, `:to`"
+    end
+
+    it "not consider deprecated options unrecognized" do
+      optioning = Optioning.new [
+        from: "xpto",
+        to: "bbq",
+        omg: "x",
+        no_one_knows: "omg lol"]
+      optioning.deprecate :omg, :lol
+      optioning.recognize :from, :to
+      optioning.unrecognized_warn
+      $stderr.string.must_be :==, "NOTE: unrecognized option `:no_one_knows` used."+
+        "\nYou should use only the following: `:lol`, `:from`, `:to`"
+    end
+
+    it "not consider replacement options unrecognized" do
+      optioning = Optioning.new [
+        from: "xpto",
+        to: "bbq",
+        lol: "x",
+        no_one_knows: "omg lol"]
+      optioning.deprecate :omg, :lol
+      optioning.recognize :from, :to
+      optioning.unrecognized_warn
+      $stderr.string.must_be :==, "NOTE: unrecognized option `:no_one_knows` used."+
+        "\nYou should use only the following: `:lol`, `:from`, `:to`"
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optioning
 version: !ruby/object:Gem::Version
-  version: 0.0.1.beta
+  version: 0.0.1
 platform: ruby
 authors:
 - Ricardo Valeriano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-07 00:00:00.000000000 Z
+date: 2014-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -28,14 +28,14 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
@@ -67,13 +67,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/client_maroto.rb
+- examples/module_maroto.rb
+- lib/deprecation.rb
 - lib/optioning.rb
 - lib/optioning/version.rb
 - optioning.gemspec
 - tasks/lines.rake
 - tasks/test.rake
+- test/deprecation_test.rb
+- test/optioning_test.rb
 - test/test_helper.rb
-homepage: ''
+- test/unrecognized_option_test.rb
+homepage: http://github.com/ricardovaleriano/optioning
 licenses:
 - MIT
 metadata: {}
@@ -83,19 +89,23 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.1.4
 signing_key: 
 specification_version: 4
-summary: 'An object oriented way to treat our beloved last parameter: Hash.'
+summary: ! 'An object oriented way to treat our beloved last parameter: Hash.'
 test_files:
+- test/deprecation_test.rb
+- test/optioning_test.rb
 - test/test_helper.rb
+- test/unrecognized_option_test.rb
+has_rdoc: