class ArrayFu::ArrayDefinition

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

Attributes

constraints[RW]

The list of constraints specified for this array definition

mutators[RW]

List of mutator definitions for this array

name[R]

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

readable[RW]

Flag for readability

visitors[RW]

List of processing visitors

writeable[RW]

Flag for writeability

Public Class Methods

new(name) click to toggle source

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]

# File lib/arrayfu/array_definition.rb, line 25
def initialize(name)
  @name = name
  initialize_arrays :mutators, :visitors, :constraints
  initialize_false :writeable, :readable
end

Public Instance Methods

addition_constraint(constraint, fail_option = NoFailure) click to toggle source

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 {ArrayFu::ArrayDefinition::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
# File lib/arrayfu/array_definition.rb, line 222
def addition_constraint(constraint, fail_option = NoFailure)
  self.constraints.push(ItemConstraint.new(constraint, fail_option))
end
Also aliased as: new_item_must
configure_using(*configurators) click to toggle source

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 {ArrayDefinition}.

If a configurator is a block, it will be a block that takes a singular parameter which is the {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')
    
# 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) click to toggle source

Run each of its {ArrayFu::ItemConstraint} against the provided block

# File lib/arrayfu/array_definition.rb, line 203
def each_constraint(&block)
  constraints.each &block
end
each_mutator(&block) click to toggle source

Run each of its {ArrayFu::MutatorDefinition} against the provided block

# File lib/arrayfu/array_definition.rb, line 198
def each_mutator(&block)
  mutators.each &block 
end
each_visitor(&block) click to toggle source

Run each of its {ArrayFu::VisitorDefinition} against the provided block

# File lib/arrayfu/array_definition.rb, line 208
def each_visitor(&block)
  visitors.each &block
end
mutator(*names, &block) click to toggle source

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
    
# 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
new_item_must(constraint, fail_option = NoFailure)
Alias for: addition_constraint
process_using(name,visitor) click to toggle source
# File lib/arrayfu/array_definition.rb, line 227
def process_using(name,visitor)
  self.visitors.push(VisitorDefinition.new(name, visitor))
end
read_and_write() click to toggle source

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
# File lib/arrayfu/array_definition.rb, line 50
def read_and_write
  writeable
  readable
end
readable?() click to toggle source

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

# File lib/arrayfu/array_definition.rb, line 72
def readable?
  @readable ||= false
end
variable_name() click to toggle source

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

# File lib/arrayfu/array_definition.rb, line 232
def variable_name
  "@#{@name}"
end
writeable?() click to toggle source

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

# File lib/arrayfu/array_definition.rb, line 67
def writeable?
  @writeable ||= false
end