class Optioning

Constants

VERSION

Public Class Methods

new(args) click to toggle source

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

deprecate(option, replacement, version_or_year = nil, month = nil) click to toggle source

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
deprecation_warn(called_from = nil) click to toggle source

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
on(option) click to toggle source

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
process(called_from = nil) click to toggle source

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
raw() click to toggle source

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
recognize(*options) click to toggle source

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
unrecognized_warn(called_from = nil) click to toggle source

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
values() click to toggle source

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

deprecated_but_used() click to toggle source

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
deprecations() click to toggle source

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
options() click to toggle source
# File lib/optioning.rb, line 138
def options
  @options ||= {}
end
recognized() click to toggle source

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
recognized_options_warn(called_from = nil) click to toggle source

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
replace_deprecations() click to toggle source

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
set_caller_on_deprecations(called_from) click to toggle source

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
unrecognized_options() click to toggle source

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