Class: Origen::Utility::Collector

Inherits:
Object
  • Object
show all
Defined in:
lib/origen/utility/collector.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|self| ... } ⇒ Collector

Creates a new Collector object and creates a Hash out of the methods names and values in the given block.

Examples:

Create a collector to transform a block into a Hash

Origen::Utility::Collector.new { |c| c.my_param 'My Parameter'}.to_h #=> {my_param: 'My Parameter'}

Parameters:

  • options (Hash) (defaults to: {}) —

    Customization options.

Options Hash (options):

  • :hash (Hash) —

    Input, or starting, values that are set in the output hash prior to calling the given block.

  • :merge_method (Symbol) — default: :keep_hash —

    Indicates how arguments that exist in both the input hash and in the block should be handled. Accpeted values are :keep_hash, :keep_block, :fail.

Yields:

  • (self) —

    Passes the collector to the given block.

Raises:

See Also:



28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/origen/utility/collector.rb', line 28

def initialize(options = {}, &block)
  @merge_method = options[:merge_method] || :keep_hash
  @fail_on_empty_args = options[:fail_on_empty_args]
  unless [:keep_hash, :keep_block, :fail].include?(@merge_method)
    fail Origen::OrigenError, "Origen::Utility::Collector cannot merge with method :#{@merge_method} (of class #{@merge_method.class}). Known merge methods are :keep_hash (default), :keep_block, or :fail"
  end

  @_hash_ = options.key?(:hash) ? options[:hash].clone : {}
  @_methods_ = []

  if block_given?
    yield self
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &_block) ⇒ Object

Note:

If no args are given, the method key is set to nil.

Using the method name, creates a key in the Collector with argument given to the method.

Raises:

  • (ArgumentError) —

    Raised when a method attempts to use both arguments and a block in the same line. E.g.: collector.my_param 'my_param' { 'MyParam' }

  • (ArgumentError) —

    Raised when a method attempts to use multiple input values. E.g.: collector.my_param 'my_param', 'MyParam'

  • (Origen::OrigenError) —

    Raised when a method is set more than once. I.e., overriding values are not allowed. E.g.: collector.my_param 'my_param'; collector.my_param 'MyParam'

  • (Origen::OrigenError) —

    Raised when the input hash and the block attempt to set the same method name and the merge method is set to :fail.

See Also:



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/origen/utility/collector.rb', line 69

def method_missing(method, *args, &_block)
  key = method.to_s.sub('=', '').to_sym

  # Check that the arguments are correct
  if block_given? && !args.empty?
    # raise Origen::OrigenError, "Origen::Utility::Collector detected both the hash and block attempting to set :#{key} (merge_method set to :fail)"
    fail ArgumentError, "Origen::Utility::Collector cannot accept both an argument list and block simultaneously for :#{key}. Please use one or the other."
  elsif block_given?
    val = _block
  elsif args.size == 0
    # Set any empty argument to nil
    val = nil
  elsif args.size > 1
    fail ArgumentError, "Origen::Utility::Collector does not allow method :#{key} more than 1 argument. Received 3 arguments."
  else
    val = args.first
  end

  # Check if we've already added this key via a method
  if _methods_.include?(key)
    fail Origen::OrigenError, "Origen::Utility::Collector does not allow method :#{key} to be set more than a single time. :#{key} is set to #{_hash_[key]}, tried to set it again to #{val}"
  end

  # indicate that we've seen this method, and decide whether or not to add the new value
  _methods_ << key

  # Merge the value (or don't, depending on what is set)
  if merge_method == :keep_block || !_hash_.key?(key)
    _hash_[key] = val
  elsif merge_method == :fail
    fail Origen::OrigenError, "Origen::Utility::Collector detected both the hash and block attempting to set :#{key} (merge_method set to :fail)"
  end
  # store[key] = val if !store.key?(key) || (store.key?(key) && merge_method == :keep_block)

  # Return self instead of the key value to allow for one-line collector statements
  self
end

Instance Attribute Details

#_hash_ ⇒ Object (readonly)

Returns the collector’s hash. This is the same as calling #to_h



5
6
7
 
# File 'lib/origen/utility/collector.rb', line 5

def _hash_
  @_hash_
end

#_methods_ ⇒ Object (readonly)

List of the currently seen method names.



16
17
18
 
# File 'lib/origen/utility/collector.rb', line 16

def _methods_
  @_methods_
end

#merge_method ⇒ Object (readonly)

Queries the current merge_method.



8
9
10
 
# File 'lib/origen/utility/collector.rb', line 8

def merge_method
  @merge_method
end

Instance Method Details

#store ⇒ Hash

Deprecated.

Use Ruby-centric #to_hash instead.

Retrieve the collector’s hash.

Returns:

  • (Hash) —

    Hash representation of the collector.



46
47
48
49
50
 
# File 'lib/origen/utility/collector.rb', line 46

def store
  Origen.log.deprecate 'Collector::store method was used. Please use the Ruby-centric Collector::to_h or Collector::to_hash method instead' \
                       " Called from: #{caller[0]}"
  @_hash_
end

#to_hash ⇒ Hash Also known as: to_h

Returns the collector, as a Hash.

Returns:

  • (Hash) —

    Hash representation of the collector.



54
55
56
 
# File 'lib/origen/utility/collector.rb', line 54

def to_hash
  @_hash_
end