class Optioning
Constants
- VERSION
Public Class Methods
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)>
# File lib/optioning.rb, line 19 def initialize(args) @args = args @values = @args.dup @options = @values.pop.dup if @args.last.is_a? Hash end
Public Instance Methods
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
# File lib/optioning.rb, line 52 def deprecate(option, replacement, version_or_year = nil, month = nil) deprecations << Deprecation.new(option, replacement, version_or_year, month) recognize(replacement) 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
# File lib/optioning.rb, line 77 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
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
# File lib/optioning.rb, line 34 def on(option) replace_deprecations options.fetch option, nil 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
# File lib/optioning.rb, line 102 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
# File lib/optioning.rb, line 111 def raw @args 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
# File lib/optioning.rb, line 67 def recognize(*options) @recognized ||= [] @recognized += options 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
# File lib/optioning.rb, line 89 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) if unrecognized_options.count > 0 self 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`
# File lib/optioning.rb, line 119 def values @values end
Private Instance Methods
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}
# File lib/optioning.rb, line 185 def deprecated_but_used deprecations.map(&:option).select { |option| options.include? option } end
Memoization for the ‘deprecations` created by invocations of {#deprecate}
@return [Array<Deprecation>] all {Deprecation}s for these {Optioning} instance
# File lib/optioning.rb, line 127 def deprecations @deprecations ||= [] end
# File lib/optioning.rb, line 138 def options @options ||= {} end
Memoization for the ‘recognized` options created by {#recognize}
@return [Array<Symbol>] all options recognized by this {Optioning}
# File lib/optioning.rb, line 134 def recognized @recognized ||= [] end
Issues a message containing all the recognized options for an {Optioning}
@param called_from [Array<String>] the result of calling {Kernel#caller}
# File lib/optioning.rb, line 167 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
Cleanup the options trashing up the deprecated options in favor the replacements.
@return [Hash] @options already filtered
# File lib/optioning.rb, line 146 def replace_deprecations deprecations.each do |deprecation| deprecated_value = options.delete deprecation.option options[deprecation.replacement] ||= deprecated_value end options end
Configure the caller in all the deprecations for this instance
@return [Array<Deprecations>]
# File lib/optioning.rb, line 176 def set_caller_on_deprecations(called_from) return unless called_from.respond_to? :first deprecations.each { |deprecation| deprecation.caller = called_from.first } end
All unrecognized options used as parameter to an {Optioning}
@return [Array<Symbol>] unrecognized options
# File lib/optioning.rb, line 157 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