Class: Leap::Committee

Inherits:
Object
  • Object
show all
Defined in:
lib/leap/committee.rb

Overview

One of the basic building blocks of a Leap decision.

Committees represent computable attributes of a subject instance and facilitate multiple means of computing these attributes. In some cases, you will define committees that match the names of attributes that can be explicitly set on a subject; in this case, the committees are only useful when a particular instance does not have this attribute set. In other cases, committees are part of internal logic within the Leap decision, providing intermediate results in pursuit of the decision’s ultimate goal.

As a Leap decision is made, it approaches each committee in turn, providing it with its current knowledge of the subject. The committee accepts this information, determines an appropriate methodology, and returns additional information about the subject. This newly-augmented knowledge about the subject is then passed to the next committee for further augmentation, and so forth.

Committees are composed of one or more quorums (Leap::Quorum objects) that encapsulate specific methodologies for drawing the committee’s conclusion. This composition is defined within the Leap::Decision#committee block using the Leap::Committee#quorum DSL.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, options) ⇒ Committee

Creates a new Leap::Committee with the given name.

Generally you don’t create these objects directly; Leap::Decision#committee does that for you.

Parameters:

  • name (Symbol) —

    The name of the committee, traditionally formulated to represent a computable attribute of the subject.

  • options (Hash) —

    Any options you wish the committee to remember (for third-party use).

See Also:



31
32
33
34
35
 
# File 'lib/leap/committee.rb', line 31

def initialize(name, options)
  @name = name
  @options = options
  @quorums = []
end

Instance Attribute Details

#name ⇒ Object (readonly)

The name of the committee, traditionally formulated to represent a computable attribute of the subject.



16
17
18
 
# File 'lib/leap/committee.rb', line 16

def name
  @name
end

#options ⇒ Object (readonly)

An options hash



22
23
24
 
# File 'lib/leap/committee.rb', line 22

def options
  @options
end

#quorums ⇒ Object (readonly)

The array of quorums defined within the committee.



19
20
21
 
# File 'lib/leap/committee.rb', line 19

def quorums
  @quorums
end

Instance Method Details

#default(options = {}, &blk) ⇒ Object

Convenience method for defining a quorum named “default” with no needs, wants, or compliances.



76
77
78
 
# File 'lib/leap/committee.rb', line 76

def default(options = {}, &blk)
  quorum 'default', options, &blk
end

#quorum(name, options = {}) { ... } ⇒ Object

Defines a quorum within this committee.

A quorum encapsulate a specific methodology for drawing the committe’s conclusion.

Parameters:

  • name (String) —

    A descriptive name for this methodology.

  • options (optional, Hash) (defaults to: {})
  • [Symbol, (Hash) —

    a customizable set of options

  • complies (Hash) —

    a customizable set of options

Yields:

  • The quorum’s methodology, as a Ruby closure. You may define your block with any number of block vars. If zero, the methodology requires no outside information (useful for “default” quorums). If one, Leap will provide the characteristics hash, accumulated over the course of the deliberation, that represents its total knowledge of the subject at the time. (Note that Leap will actually provide only a subset of the characteristics hash–namely, only attributes that are specifically requested by the :needs and :wants options below.) If more than one, additional block vars will be filled with as many considerations (given during Leap::Decision#make) as is necessary.



71
72
73
 
# File 'lib/leap/committee.rb', line 71

def quorum(name, options = {}, &blk)
  @quorums << ::Leap::Quorum.new(name, options, blk)
end

#report(characteristics, considerations, options = {}) ⇒ Object

Instructs the committee to draw its conclusion.

Steps through each quorum defined within the committee in search of one that can be called with the provided characteristics and is compliant with the requested protocols. Upon finding such a quorum, it is called. If a conclusion is returned, it becomes the committee’s conclusion; if not, the quorum-seeking process continues.

Generally you will not call this method directly; Leap::Decision#make requests reports at the appropriate time.

Parameters:

  • characteristics (Hash) —

    What we know so far about the subject.

  • considerations (Array) —

    Auxiliary contextual details about the decision (see Leap::GoalMethodsDocumentation)

  • options (optional, Hash) (defaults to: {})
  • comply (Hash) —

    a customizable set of options

Returns:

  • Leap::Report

See Also:



48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/leap/committee.rb', line 48

def report(characteristics, considerations, options = {})
  Leap.log.committee "Convening committee", name
  quorums.each do |quorum|
    Leap.log.quorum "Assessing quorum", quorum.name
    next unless quorum.satisfied_by? characteristics and quorum.complies_with? options[:comply]
    Leap.log.quorum "Acknowledging quorum", quorum.name
    if conclusion = quorum.acknowledge(characteristics.slice(*quorum.characteristics), considerations.dup)
      Leap.log.quorum "Success", quorum.name 
      return ::Leap::Report.new(self, quorum, conclusion)
    end
  end
  nil
end