Module: Compo::Composites::Composite

Extended by:
Forwardable
Includes:
Enumerable
Included in:
Array, Hash, Leaf, Parentless
Defined in:
lib/compo/composites/composite.rb

Overview

Mixin for objects that can contain other objects

Objects implementing this interface should implement add!, remove! or remove_id!, and id_function.

add! - Given a desired ID and child, adds the child to the children

of this object; returns the child if successful, nil
otherwise.

remove! - Given a child, removes and returns it from the children; if

not provided, this is implemented in terms of remove_id!.

remove_id! - Given an ID, removes and returns the child with this ID from

the children; if not provided, this is implemented in terms
of remove!.

children - Returns the children, as a Hash mapping from current IDs to

their child values.

id_function - Given a newly inserted child, returns a proc that will

always return the child's current ID so long as it is part
of the Composite.

Instance Method Summary collapse

Instance Method Details

#add(id, child) ⇒ Object

Adds a child to this Composite

Examples:

Adds a child with intended id 3.

composite.add_child(3, leaf)

Parameters:

  • id (Object) —

    The intended ID of the child in this Composite. The actual ID may not be the same as this; consult the proc supplied to the child via #update_parent.

  • child (Object) —

    The child to add to this Composite.

Returns:

  • (Object) —

    The added child if successful; nil otherwise.



39
40
41
 
# File 'lib/compo/composites/composite.rb', line 39

def add(id, child)
  add!(id, child).tap(&method(:assign_parent_to))
end

#get_child(id) ⇒ Object

Gets the child in this Composite with the given ID

The ID is compared directly against the IDs of the children of this composite. To use a predicate to find an ID, use #get_child_such_that.

Examples:

Gets the child with ID :in, if children is 3.

composite.get_child(:in)
#=> 3

Fails to get the child with ID :out, if children is 3.

composite.get_child(:out)
#=> nil

Fails to get the child with ID ‘1’, if children is => 3.

composite.get_child('1')
#=> nil

Parameters:

  • id (Object) —

    The ID of the child to get from this Composite.

Returns:

  • (Object) —

    The child if successful; nil otherwise.



94
95
96
 
# File 'lib/compo/composites/composite.rb', line 94

def get_child(id)
  children[id]
end

#get_child_such_that {|id| ... } ⇒ Object

Gets the child in this Composite whose ID matches a given predicate

If multiple children match this predicate, the result is the first child in the hash.

Examples:

Gets the child with ID :in, if children is 3.

composite.get_child_such_that { |x| x == :in }
#=> 3

Fails to get the child with ID :out, if children is 3.

composite.get_child_such_that { |x| x == :out }
#=> nil

Get the child with an ID whose string form is ‘1’, if children

is {1 => 3}.
composite.get_child_such_that { |x| x.to_s == '3' }
#=> 3

Yield Parameters:

  • id (Object) —

    An ID to check against the predicate.

Returns:

  • (Object) —

    The child if successful; nil otherwise.



118
119
120
121
122
 
# File 'lib/compo/composites/composite.rb', line 118

def get_child_such_that(&block)
  child = children.each.find { |k, _| block.call(k) }
  (_, value) = child unless child.nil?
  value
end

#on_node {|_self| ... } ⇒ false

Performs an action on this node, if it is an actual Composite node

By default, this does indeed run the block provided, and returns the block’s result. Composites that do not represent proper nodes (for example, Parentless) may override this to ignore the block and return nil.

Examples:

Performs an action on this Parentless.

parentless.on_node { |n| 3 }
#=> 3

Yields:

  • (_self)

Yield Parameters:

Returns:

  • (false) 


138
139
140
 
# File 'lib/compo/composites/composite.rb', line 138

def on_node
  yield self
end

#remove(child) ⇒ Object

Removes a child from this Composite directly

This method can fail (for example, if the child does not exist in the Composite).

Examples:

Removes a child.

composite.remove(child)

Parameters:

  • child (Object) —

    The child to remove from this object.

Returns:

  • (Object) —

    The removed child if successful; nil otherwise.



55
56
57
 
# File 'lib/compo/composites/composite.rb', line 55

def remove(child)
  remove!(child).tap(&method(:remove_parent_of))
end

#remove_id(id) ⇒ Object

Removes a child from this Composite, given its ID

This method can fail (for example, if the ID does not exist in the Composite).

Examples:

Removes the child with ID :foo.

composite.remove_id(:foo)

Parameters:

  • id —

    The ID of the child to remove from this object.

Returns:

  • (Object) —

    The removed child if successful; nil otherwise.



71
72
73
 
# File 'lib/compo/composites/composite.rb', line 71

def remove_id(id)
  remove_id!(id).tap(&method(:remove_parent_of))
end