Class: Optioning

Inherits:
Object
  • Object
show all
Defined in:
lib/optioning.rb,
lib/optioning/version.rb

Constant Summary collapse

VERSION = 
"0.1.0"

Instance Method Summary collapse

Constructor Details

#initialize(args) ⇒ 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.

Examples:

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)>


19
20
21
22
23
 
# 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

Instance Method Details

#deprecate(option, replacement, version_or_year = nil, month = nil) ⇒ Optioning

Creates a deprecation for an option, stores info about it’s replacement and time or version to its removal.

Examples:

@option = Optioning.new :path, :commit, to_hash: ->(value) { value.upcase }
@option.deprecate :to_hash, :to, Date.new(2015, 05, 01)

Parameters:

  • option (Symbol) —

    option to be deprecated

  • replacement (Symbol) —

    replacement option

  • version_or_year (defaults to: nil) —

    version when the deprecation will be removed, if month is filled, this param will be treated as the year of replacement

  • month (Integer) (defaults to: nil) —

    month when the deprecated option will be removed

Returns:

  • (Optioning) —

    the current instance of optioning



52
53
54
55
56
 
# 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) ⇒ Optioning

Issues all deprecation messages to the $stderr

Parameters:

  • called_from (Array) (defaults to: nil) —

    expected to be the result of calling ‘caller`

Returns:



77
78
79
80
81
82
83
 
# 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) ⇒ Object

Return the value for a specific option

Examples:

@option = Optioning.new [:path, :commit, stored_value: 42]
@option.on :stored_value
# => 42

Parameters:

  • option (Symbol) —

    (or Object used as an index) name of option to retrieve

Returns:

  • value for option passed as parameter



34
35
36
37
 
# File 'lib/optioning.rb', line 34

def on(option)
  replace_deprecations
  options.fetch option, nil
end

#process(called_from = nil) ⇒ Optioning

Issues the deprecation warnings and the unrecognized warnings. Let the current Optioning in a ‘ready to use` state.

Parameters:

  • called_from (Array<String>) (defaults to: nil) —

    the result of calling Object#caller

Returns:



102
103
104
105
106
 
# File 'lib/optioning.rb', line 102

def process(called_from = nil)
  deprecation_warn called_from
  unrecognized_warn called_from
  self
end

#raw ⇒ Array

Return all values passed as varargs to the constructor.

Returns:

  • (Array) —

    all values passed to the constructor



111
112
113
 
# File 'lib/optioning.rb', line 111

def raw
  @args
end

#recognize(*options) ⇒ Optioning

Provides a way to inform which options can be used and which will be ignored by an instance of Optioning

Examples:

@options = Optioning.new :path, :commit, to_hash: ->(value) { value.upcase }
@options.deprecate :to_hash, :to, Date.new(2015, 05, 01)

Parameters:

  • options (Array<Symbol>) —

    all recognized options for the current Optioning

Returns:



67
68
69
70
71
 
# File 'lib/optioning.rb', line 67

def recognize(*options)
  @recognized ||= []
  @recognized += options
  self
end

#unrecognized_warn(called_from = nil) ⇒ Optioning

Issues all unrecognized messages and the recognized_options message to the $stderr

Parameters:

  • called_from (Array<String>) (defaults to: nil) —

    the result of calling Object#caller

Returns:



89
90
91
92
93
94
95
 
# 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 ⇒ Array

Return all the values passed before the last one (if this one is a ‘Hash` instance).

Returns:

  • (Array) —

    arguments that are not part of the options ‘Hash`



119
120
121
 
# File 'lib/optioning.rb', line 119

def values
  @values
end