Class: MadderLib::Phrase

Inherits:
Object
  • Object
show all
Extended by:
Conditional::Registry::Static
Includes:
Conditional::Allowed::Phrase, Conditional::Likely::Phrase, Conditional::Registry::Instance, Conditional::Repeat::Phrase
Defined in:
lib/madderlib/phrase.rb

Overview

Phrase

A specific phrase within a MadderLib Builder.

A Phrase is a collection of one or more Instruction objects. An Instruction is selected, and that becomes the Phrase’s result

A Phrase supports:

  • proportioned choice of Instructions, via Conditional::Likely

Direct Known Subclasses

AnytimePhrase

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Conditional::Registry::Static

add_prepare, add_test, conditional_prepares, conditional_tests

Methods included from Conditional::Likely::Phrase

included, #likely

Methods included from Conditional::Repeat::Phrase

#repeat

Methods included from Conditional::Allowed::Phrase

#assuming, #forbidding

Methods included from Conditional::Registry::Instance

#prepare, #test

Constructor Details

#initialize(builder, id = nil, *args, &block) ⇒ Phrase

Constructs a new Phrase

The containing Phrase is builder.

An optional id can be provided. The id is particularly useful in the case of:

  • relative positioning, via Builder#before or Builder#after

  • conditional usage, via Conditional::Allowed#assuming , etc.

  • positioning ranges, via AnywherePhrase#between , etc.

Any number of arguments may be provided, and they are dispatched to the say method. An optional block can be provided, and if so, it is also dispatched to say.



39
40
41
42
43
44
45
 
# File 'lib/madderlib/phrase.rb', line 39

def initialize(builder, id=nil, *args, &block)
	@builder, @id = builder, id
	@instructions = []

	#	don't start out with an empty instruction
	say *args, &block unless (args.empty?) && (! block_given?)
end

Instance Attribute Details

#builder ⇒ Object (readonly)

A refererence to the Builder which contains this Phrase



19
20
21
 
# File 'lib/madderlib/phrase.rb', line 19

def builder
  @builder
end

#id ⇒ Object (readonly)

The (optional) id of the Phrase



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

def id
  @id
end

#instructions ⇒ Object (readonly)

An Array of the Instructions used by this Phrase



23
24
25
 
# File 'lib/madderlib/phrase.rb', line 23

def instructions
  @instructions
end

Instance Method Details

#alternately(*args, &block) ⇒ Object Also known as: or

Sets aside proportion logic to be used by the next call to the say method.

Calling this method is a prelude to adding another optional Instruction via say. All arguments are optional; if none are provided, the default proportions will be assumed. Without any arguments, a call to this method is syntactic sugar. You could call say(…).say(…), but it’s not quite as descriptive

See: Builder#alternately

Examples:

builder = madderlib do
  say('barnard').or.say('bryn mawr')
  alternately(2).say('mount holyoke').alternately(2).say('radcliffe')
  it.alternately(4).says('smith').or(4).says('vassar')
end
builder.phrase.says('wellesley').or(5).nothing

usage = {}
200.times do
  key = builder.sentence
  usage[key] = (usage[key] || 0) + 1
end

#  if proportions were accurately reproducible:
#    ['barnard', 'bryn mawr', 'wellesley'].each {|name| usage[name].should eql(10) }
#    ['mount holyoke', 'radcliffe'].each {|name| usage[name].should eql(20) }
#    ['smith', 'vassar'].each {|name| usage[name].should eql(40) }
#    [''].each {|name| usage[name].should eql(50) }



98
99
100
101
102
 
# File 'lib/madderlib/phrase.rb', line 98

def alternately(*args, &block)
	#	hold onto these until we say something
	@or_likely = [args, block]
	self
end

#instruction ⇒ Object

Returns the current Instruction.

An Error will be raised if there is no current Instruction. It’s an easy condition to recover from, but it’s bad use of the syntax.

Raises:



122
123
124
125
126
127
 
# File 'lib/madderlib/phrase.rb', line 122

def instruction
	raise Error, 'there is no current Instruction' if @instructions.empty?

	#	whatever our current once is
	@instructions.last
end

#nothing ⇒ Object

Adds a new Instruction to the Phrase which has no content. The Instruction will always return an empty Array, and thus be omitted from the Builder results

This method is provided for proportionate Phrases, where ‘nothing’ may be a suitable output

See: alternately



111
112
113
114
 
# File 'lib/madderlib/phrase.rb', line 111

def nothing
	#	say nothing
	say
end

#say(*args, &block) ⇒ Object Also known as: says

Adds a new Instruction to the Phrase using the provided arguments.

All arguments, and any block provided, are used to construct the new Instruction. Any proportion logic which has been cached via a prior call to alternately us applied to the new Instruction

See: Builder#say



55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/madderlib/phrase.rb', line 55

def say(*args, &block)
	#	allocate new
	@instructions << Instruction.new(self, *args, &block)

	if @or_likely
		#	retro-apply the likelihood from the 'or' operation
		args, block = @or_likely
		self.instruction.likely *args, &block unless (args.empty? && block.nil?)
		@or_likely = nil
	end

	self
end

#speak(context) ⇒ Object

Generates the list of words for this Phrase

This is done by:

  • choosing a suitable Instruction

  • invoking Instruction#speak

See: Instruction#speak



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/madderlib/phrase.rb', line 138

def speak(context)
	found = nil

	#	should we speak at all?
	if self.test(context)
		#	say the first sensible thing
		found = instructions.find do |instruction|
			instruction.test(context)
		end
	end

	if found
		#	track our instructions
		context.instructions << found

		#	now, speak your say (as words)
		found = found.speak(context)
	end
	found || []
end