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

#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