Class: ArrayFu::ArrayDefinition

Inherits:
Object
  • Object
show all
Includes:
Initializer
Defined in:
lib/arrayfu/array_definition.rb

Overview

A builder for specifying behaviours exposed by a class that defines arrays

Defined Under Namespace

Modules: NoFailure

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Initializer

#initialize_arrays, #initialize_defaults, #initialize_false, #initialize_hashes

Constructor Details

#initialize(name) ⇒ ArrayDefinition

Create an array definition with the specified name

Parameters:

@name

Name given to the array definition. This name will also be used to generate a variable on the target class named: @[name]



25
26
27
28
29
 
# File 'lib/arrayfu/array_definition.rb', line 25

def initialize(name)
  @name = name
  initialize_arrays :mutators, :visitors, :constraints
  initialize_false :writeable, :readable
end

Instance Attribute Details

#constraints ⇒ Object

The list of constraints specified for this array definition



18
19
20
 
# File 'lib/arrayfu/array_definition.rb', line 18

def constraints
  @constraints
end

#mutators ⇒ Object

List of mutator definitions for this array



13
14
15
 
# File 'lib/arrayfu/array_definition.rb', line 13

def mutators
  @mutators
end

#name ⇒ Object (readonly)

The name that will be given to this array definition, it will also become a variable named @[name] on the class that defined this array



7
8
9
 
# File 'lib/arrayfu/array_definition.rb', line 7

def name
  @name
end

#readable ⇒ Object

Flag that the class that is defining this array will expose a writer for the array variable



11
12
13
 
# File 'lib/arrayfu/array_definition.rb', line 11

def readable
  @readable
end

#visitors ⇒ Object

List of processing visitors



15
16
17
 
# File 'lib/arrayfu/array_definition.rb', line 15

def visitors
  @visitors
end

#writeable ⇒ Object

Flag that the class that is defining this array will expose a writer for the array variable



9
10
11
 
# File 'lib/arrayfu/array_definition.rb', line 9

def writeable
  @writeable
end

Instance Method Details

#addition_constraint(constraint, fail_option = NoFailure) ⇒ Object Also known as: new_item_must

Adds a constraint that must be met for any new item being passed to a mutator method

Parameters:

constraint

An object that responds to the following 2 methods:

name: - Should return a descriptive name for the constraint
matches?(item) - The constraint method, it will be called with any new item about to be added
fail_option (defaults to NoFailure)

An object that responds to the following methods:

run(description, value) - Behaviour to run when the constraint is not met. It is given the description of the failed constraint, and the value
that did not meet the constraint



222
223
224
 
# File 'lib/arrayfu/array_definition.rb', line 222

def addition_constraint(constraint, fail_option = NoFailure)
  self.constraints.push(ItemConstraint.new(constraint, fail_option))
end

#configure_using(*configurators) ⇒ Object

This method allows for external configurators to customize the behaviour of this array definition

Parameters:

configurators

One or many objects/blocks (can be a mix). If a configurator is an object, it must respond to the following method:

def configure(definition)

Where definition is an ArrayFu::ArrayDefinition.

If a configurator is a block, it will be a block that takes a singular parameter which is the ArrayFu::ArrayDefinition

Examples:

  • Configuring using an object

    class SomeConfigurator
  def self.configure(array_definition)
    array_definition.mutator :add_it
  end
end

class SomeClass
  include ArrayFu

  array :names do
    configure_using SomeConfigurator
  end
end

instance = SomeClass.new
instance.add_it('JP')

  • Configuring using a lambda

    class SomeClass
  include ArrayFu

  array :names do
    configure_using -> (item) do
      item.mutator :add_it
    end
  end
end

instance = SomeClass.new
instance.add_it('JP')



119
120
121
122
123
124
 
# File 'lib/arrayfu/array_definition.rb', line 119

def configure_using(*configurators)
  configurators.each do|configurator|
    method = configurator.respond_to?(:configure) ? :configure : 'call'.to_sym
    configurator.send(method, self)
  end
end

#each_constraint(&block) ⇒ Object

Run each of its ItemConstraint against the provided block



203
204
205
 
# File 'lib/arrayfu/array_definition.rb', line 203

def each_constraint(&block)
  constraints.each &block
end

#each_mutator(&block) ⇒ Object

Run each of its MutatorDefinition against the provided block



198
199
200
 
# File 'lib/arrayfu/array_definition.rb', line 198

def each_mutator(&block)
  mutators.each &block 
end

#each_visitor(&block) ⇒ Object

Run each of its VisitorDefinition against the provided block



208
209
210
 
# File 'lib/arrayfu/array_definition.rb', line 208

def each_visitor(&block)
  visitors.each &block
end

#mutator(*names, &block) ⇒ Object

Method used to specify a list of methods that will be exposed on the class that is defining this array. The methods are write methods that will push data back to the underlying array

Parameters:

names

Method names that will be used to expose push methods to this array

&block

If provided, this block will be run anytime the mutator method is invoked. It’s single parameter is the new item that is attempting to be added to the underlying array if you provide this block, and dont push the item parameter back to the original array, no changes will happen to the underlying array

Examples:

class SomeClass
  include ArrayFu

  array :names { mutator :add_item }
end

The above will generate an instance method named :add_item on the SomeClass class. When you call this method, the names array will have an item pushed to it:

instance = SomeClass.new
instance.add_item('Hello') #the @names array variable will now contain ['Hello']

You can specify multiple mutators at once:

class SomeClass
  include ArrayFu

  array :names do
    mutator :add_item, 
            :add_another, 
            :add_one_more 
  end
end

instance = SomeClass.new
instance.add_item('JP')
instance.add_another('Yeah')
instance.add_one_more('Yep')

Example:

  • A mutator with custom logic in a block

    class SomeClass
  include ArrayFu

  array :names do
    mutator :add_one do |item|
      puts 'About to add one new item #{item}'
      @names.push(item) #if this does not happen, no changes will occur to the underlying array
    end
  end
end

instance = SomeClass.new
instance.add_one('JP') # at this point we will see a console out



183
184
185
186
187
 
# File 'lib/arrayfu/array_definition.rb', line 183

def mutator(*names, &block)
  names.each do |mutator_name| 
    self.mutators.push(MutatorDefinition.new(mutator_name, block))
  end
end

#process_using(name, visitor) ⇒ Object 



227
228
229
 
# File 'lib/arrayfu/array_definition.rb', line 227

def process_using(name,visitor)
  self.visitors.push(VisitorDefinition.new(name, visitor))
end

#read_and_write ⇒ Object

Flag that the class that is defining this array will expose both a reader and writer for the array variable

Example:

class SomeClass
  include ArrayFu

  array :names { read_and_write }
end

The above is the same as the following

class SomeClass
  attr_accessor :names

  def initialize
    @names = []
  end
end



50
51
52
53
 
# File 'lib/arrayfu/array_definition.rb', line 50

def read_and_write
  writeable
  readable
end

#readable? ⇒ Boolean

Used by internal infrastructure to determine if this arraydefinition should expose a reader for the array variable

Returns:

  • (Boolean) 


72
73
74
 
# File 'lib/arrayfu/array_definition.rb', line 72

def readable?
  @readable ||= false
end

#variable_name ⇒ Object

Method used by internal builder mechanism. Specifies the name that will be used for the backing array variable for this array definition



232
233
234
 
# File 'lib/arrayfu/array_definition.rb', line 232

def variable_name
  "@#{@name}"
end

#writeable? ⇒ Boolean

Used by internal infrastructure to determine if this arraydefinition should expose a writer for the array variable

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/arrayfu/array_definition.rb', line 67

def writeable?
  @writeable ||= false
end