Class: MadderLib::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/madderlib/context.rb

Overview

Context

A context-holder object for MadderLib sentences.

During the execution of a builder, the context is used to retain state for all parties that care about such things. Each execution produces a new context

It is a useful tool for providing dynamic logic and data to a completed (eg. ‘static’) Builder

Constant Summary collapse

EMPTY =

An immutable empty Context singleton. Beats returning a null

Context.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sequencer = nil) ⇒ Context

Constructs a new Context.

An optional Sequencer can be provided. The Sequencer is intentionally clouded in mystery, since it fulfils no external purpose. It is optional only for mock testing; it is required for Builder execution.



34
35
36
37
38
39
 
# File 'lib/madderlib/context.rb', line 34

def initialize(sequencer=nil)
	@sequencer = sequencer
	@spoken, @silent, @spoken_ids = [], [], []
	@instructions, @contexts = [], []
	@state, @data = {}, {}
end

Instance Attribute Details

#data ⇒ Object (readonly)

A Hash of arbitrary data for the Context. It is reserved for custom developer logic; the Context doesn’t consider its data



27
28
29
 
# File 'lib/madderlib/context.rb', line 27

def data
  @data
end

#instructions ⇒ Object (readonly)

An Array of all Instructions which contributed words, as chosen from their Phrase. The Phrases are listed in the order that they were executed



24
25
26
 
# File 'lib/madderlib/context.rb', line 24

def instructions
  @instructions
end

#sequencer ⇒ Object (readonly)

:nodoc:



11
12
13
 
# File 'lib/madderlib/context.rb', line 11

def sequencer
  @sequencer
end

#silent ⇒ Object (readonly)

An Array of all Phrases which did not contribute words. A conditional may have failed, or the resulting content was either empty or nil. The Phrases are listed in the order that they were executed



18
19
20
 
# File 'lib/madderlib/context.rb', line 18

def silent
  @silent
end

#spoken ⇒ Object (readonly)

An Array of all Phrases which contributed words. The Phrases are listed in the order that they were executed



14
15
16
 
# File 'lib/madderlib/context.rb', line 14

def spoken
  @spoken
end

#spoken_ids ⇒ Object (readonly)

An Array of the ids of all Phrases which contributed words. The ids are listed in the order that their Phrases were executed



21
22
23
 
# File 'lib/madderlib/context.rb', line 21

def spoken_ids
  @spoken_ids
end

Class Method Details

.invoke(block, context) ⇒ Object

:nodoc:



130
131
132
 
# File 'lib/madderlib/context.rb', line 130

def invoke(block, context) #:nodoc:
	(block.arity == 0 ? block.call : block.call(context))
end

.validate(block) ⇒ Object

:nodoc:

Raises:



125
126
127
128
 
# File 'lib/madderlib/context.rb', line 125

def validate(block) #:nodoc:
	raise Error, 'block required' unless block
	raise Error, 'block arity should be 0 or 1 (Context)' unless (block.arity < 2)
end

Instance Method Details

#[](k) ⇒ Object

Provides convenient access to the data Hash.

Examples:

context = MadderLib::Context.new
context.data[:key] = :value

context[:key].should equal(:value)



71
72
73
 
# File 'lib/madderlib/context.rb', line 71

def [](k)
	@data[k]
end

#[]=(k, v) ⇒ Object 



74
75
76
 
# File 'lib/madderlib/context.rb', line 74

def []=(k, v)
	@data[k] = v
end

#add_context(context) ⇒ Object

Adds a sub-context to the Context hierarchy



104
105
106
 
# File 'lib/madderlib/context.rb', line 104

def add_context(context)
	@contexts << context
end

#builder ⇒ Object

Returns the Builder associated with the Context, via its Sequencer



42
43
44
 
# File 'lib/madderlib/context.rb', line 42

def builder
	@sequencer.builder
end

#contexts(mode = nil) ⇒ Object

Returns a list of all sub-contexts which were generated during Builder execution. These would come from any Builders that were executed as children of their parent Builder The list will not include self, only its children (etc.)

The sub-contexts will be returned as an Array, and so on down the Context hierarchy. If :flat is passed as an argument, the Array returned will contain a flattened hierarchy



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/madderlib/context.rb', line 84

def contexts(mode=nil)
	mode ||= :flat

	if mode == :flat
		queue, ctxs = @contexts.clone, []
		while (ctx = queue.shift)
			#	myself
			ctxs << ctx
			#	all my children
			queue += ctx.contexts
		end

		ctxs
	else
		#	only the ones for our immediate children
		@contexts
	end
end

#freeze ⇒ Object

:nodoc:



110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/madderlib/context.rb', line 110

def freeze #:nodoc:
	super

	#	just like clone, we have to do this deeply!
	[
		@sequencer,
		@spoken, @silent, @spoken_ids,
		@instructions, @contexts,
		@state, @data,
	].each {|o| o.freeze }
end

#state(key) ⇒ Object

Returns a Hash associated with the key provided. The value returned will not be nil

This Hash can be used to store state data through the lifecycle of the Context.

Examples:

context = MadderLib::Context.new
state = context.state(:state)
state.should_not be_nil

state[:key] = :value
context.state(:state)[:key].should equal(:value)



58
59
60
61
62
 
# File 'lib/madderlib/context.rb', line 58

def state(key)
	hash = @state[key]
	@state[key] = hash = {} unless hash
	hash
end