madderlib 0.1.0

data/spec/builder_spec.rb

@@ -0,0 +1,321 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+
+
+describe MadderLib::Builder, "building" do
+	before(:each) do
+		@builder = MadderLib::Builder.new
+	end
+
+
+
+	it "doesn't require an id" do
+		@builder.id.should be_nil
+
+		@builder = MadderLib::Builder.new :id
+		@builder.id.should equal(:id)
+	end
+
+	it "transfers a phrase into a Sequence" do
+		@builder.should have(0).phrases
+		@builder.phrase.should be_nil
+
+		phrase = @builder.then
+		phrase.should_not be_nil
+		phrase.id.should be_nil
+
+		@builder.should have(1).phrases
+		@builder.phrases.last.should equal(phrase)
+		@builder.phrase.should equal(phrase)
+
+		#	one more
+		phrase = @builder.and_then
+
+		@builder.should have(2).phrases
+		@builder.phrases.last.should equal(phrase)
+		@builder.phrase.should equal(phrase)
+
+		#	one more, with an id
+		phrase = @builder.also(:id)
+		phrase.id.should equal(:id)
+
+		@builder.should have(3).phrases
+		@builder.phrases.last.should equal(phrase)
+		@builder.phrase.should equal(phrase)
+	end
+
+
+
+	it "has id support for some phrase construction methods, not for others" do
+		[
+			:a, :an,
+			:then, :and_then, :also,
+			:first, :last, :lastly,
+			:anytime,
+		].each do |method|
+			#	the method takes just an id
+			phrase = @builder.__send__ method, method
+			phrase.id.should equal(method)
+		end
+
+		[
+			:before, :after,
+		].each do |method|
+			#	the method takes a reference, then the id
+			phrase = @builder.__send__ method, :ref, method
+			phrase.id.should equal(method)
+		end
+	end
+
+	it "#it is an alias for #phrase" do
+		@builder.it.should equal(@builder.phrase)
+		@builder.it.should be_nil
+
+		@builder.then
+		@builder.should have(1).phrases
+		@builder.it.should equal(@builder.phrase)
+	end
+
+	it "#a & #and are aliases for #and_then, requiring an id" do
+		@builder.should have(0).phrases
+
+		phrase = @builder.phrase
+		@builder.a(:new).should_not equal(phrase)
+		@builder.should have(1).phrases
+
+		phrase = @builder.phrase
+
+		@builder.an(:other).should_not equal(phrase)
+		@builder.should have(2).phrases
+	end
+
+	it "will not permit duplicate phrase ids" do
+		#	this will apply to all id-capable methods
+		@builder.a(:first)
+		@builder.a(:second)
+		lambda { @builder.a(:first) }.should raise_error(MadderLib::Error)
+		lambda { @builder.a(:second) }.should raise_error(MadderLib::Error)
+	end
+
+
+
+	it "has a 'say' shortcut" do
+		@builder.should have(0).phrases
+
+		phrase = @builder.say('hello')
+		phrase.should_not be_nil
+		phrase.id.should be_nil
+
+		@builder.should have(1).phrases
+		@builder.phrases.last.should equal(phrase)
+
+		#	builds a new phrase
+		#	even with the same words, it's different
+		phrase = @builder.say('hello')
+
+		@builder.should have(2).phrases
+
+		#	we do not try to pull an id out of the say
+		#	use and_then, or a similar explicit phrasing method
+		phrase = @builder.say(:it, 'goodbye')
+		phrase.id.should be_nil
+
+		@builder.should have(3).phrases
+	end
+
+
+
+	#	best to test this once we have 'say' in the mix
+	#
+	it "'extend' operates in the context of the builder" do
+		words = %w{ hello goodbye }
+
+		@builder.extend do
+			say words.shift
+			and_then.say words.shift
+		end
+
+		@builder.should have(2).phrases
+	end
+
+	it "automatic 'extend' during construction" do
+		words = %w{ hello goodbye }
+
+		@builder = MadderLib::Builder.new do
+			say 'hello'
+			also.say 'goodbye'
+		end
+
+		@builder.should have(2).phrases
+
+		#	with an id
+		@builder = MadderLib::Builder.new(:id) do
+			say 'hello'
+			#	just testing syntactic sugar
+			an(:other).says 'goodbye'
+		end
+
+		@builder.id.should equal(:id)
+		@builder.should have(2).phrases
+	end
+
+
+
+	it "has an 'or' shortcut" do
+		@builder.say 'hello'
+		@builder.should have(1).phrases
+
+		@builder.or.say 'aloha'
+		@builder.should have(1).phrases
+
+		@builder.append do
+			alternately.say 'konnichiwa'
+		end
+		@builder.should have(1).phrases
+	end
+
+	it "the 'or' shortcut requires a pre-existing phrase" do
+		lambda { @builder.or }.should raise_error(MadderLib::Error)
+	end
+
+
+
+	it "categorizes orderings" do
+		@builder.say 'middle'
+		phrase = @builder.first.say 'beginning'
+
+		@builder.should have(2).phrases
+		@builder.should have(1).orderings
+		@builder.should have(0).dependencies
+
+		model = @builder.orderings.last
+		model.type.should equal(:first)
+		model.phrase.should equal(phrase)
+
+		phrase = @builder.last.say 'end'
+
+		@builder.should have(3).phrases
+		@builder.should have(2).orderings
+
+		model = @builder.orderings.last
+		model.type.should equal(:last)
+		model.phrase.should equal(phrase)
+
+		phrase = @builder.anytime.say 'illustration'
+
+		@builder.should have(4).phrases
+		@builder.should have(3).orderings
+
+		model = @builder.orderings.last
+		model.type.should equal(:anytime)
+		model.phrase.should equal(phrase)
+
+		phrase = @builder.anytime.say 'table'
+		@builder.orderings.last.phrase.should equal(phrase)
+
+		phrase = @builder.last.say 'appendix'
+		@builder.orderings.last.phrase.should equal(phrase)
+
+		phrase = @builder.first.say 'contents'
+		@builder.orderings.last.phrase.should equal(phrase)
+	end
+
+	it "has dependencies which require reference ids" do
+		lambda { @builder.before.say 'no id' }.should raise_error
+		lambda { @builder.after.say 'no id' }.should raise_error
+	end
+
+	it "categorizes dependencies" do
+		phrase = @builder.before(:use).say 'open'
+
+		@builder.should have(1).phrases
+		@builder.should have(0).orderings
+		@builder.should have(1).dependencies
+
+		dep = @builder.dependencies.last
+		dep.ref.should equal(:use)
+		dep.phrase.should equal(phrase)
+		dep.type.should equal(:before)
+
+		phrase = @builder.after(:use).say 'close'
+
+		@builder.should have(2).phrases
+		@builder.should have(2).dependencies
+
+		dep = @builder.dependencies.last
+		dep.ref.should equal(:use)
+		dep.phrase.should equal(phrase)
+		dep.type.should equal(:after)
+
+		phrase = @builder.before(:use).say 'destroy'
+		@builder.dependencies.last.phrase.should equal(phrase)
+
+		phrase = @builder.before(:use).say 'init'
+		@builder.dependencies.last.phrase.should equal(phrase)
+	end
+
+
+
+	it "can be cloned and extended" do
+		builder = madderlib :clone_original do
+			an(:early).says 'early'
+			a(:late).says 'late'
+		end
+		builder.id.should equal(:clone_original)
+
+		#	clone
+		extended = builder.clone(:clone_extended).extend do
+			before(:early).say "it's"
+			after(:late).say 'bird'
+		end
+		extended[:meta] = :extended
+		metas = nil
+		block = lambda {|context| metas << context.builder[:meta] }
+		extended.setup &block
+		extended.teardown &block
+
+		#	modify a shared Phrase
+		shared = builder.phrases.find {|phrase| phrase.id == :late }
+		shared.instructions.first.words << 'later'
+
+		#	new id, in the registry
+		extended.id.should equal(:clone_extended)
+		extended.should equal(madderlib_grammar[:clone_extended])
+
+		#	setup, teardown, meta, and extended content
+		metas = []
+		extended.sentence.should eql("it's early late later bird")
+		metas.should eql([:extended, :extended])
+
+		#	original is not impacted
+		#		except for the shared Phrase
+		metas = []
+		builder.sentence.should eql('early late later')
+		builder[:meta].should be_nil
+		metas.should have(0).items
+	end
+
+	it "adds the clone to the active Grammar if its original is there" do
+		grammar = MadderLib::Grammar.get_instance
+
+		original = MadderLib::Builder.new
+		grammar.builders.include?(original).should_not be_true
+
+		cloned = original.clone
+
+		grammar.add original
+		added = original.clone
+		grammar.builders.include?(added).should be_true
+	end
+
+
+
+	it "holds metadata for you" do
+		builder = madderlib do
+			meta[:cow] = :cow
+		builder.meta[:dog] = :dog
+
+		[:cow, :dog].each {|item| builder[item].should equal(item) }
+	end
+
+end

data/spec/builder_to_other_spec.rb

@@ -0,0 +1,47 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+
+
+describe MadderLib::Builder, "has component parts" do
+	WORDS = %w{ one two three }
+
+
+
+	it "is iterable" do
+		words = []
+
+		(madderlib do
+			WORDS.each {|word| say word }
+		end).each do |word|
+			words << word
+		end
+
+		words.should eql(WORDS)
+	end
+
+	it "converts to an Array" do
+		array = (madderlib do
+			WORDS.each {|word| say word }
+		end).to_a
+
+		array.should eql(WORDS)
+	end
+
+	it "converts to a String" do
+		s = (madderlib do
+			WORDS.each {|word| say word }
+		end).to_s
+
+		#	default separator
+		s.should eql(WORDS.join(' '))
+	end
+
+	it "converts to a String, with separator" do
+		s = (madderlib do
+			WORDS.each {|word| say word }
+		end).to_s("\t")
+
+		#	explicit separator
+		s.should eql(WORDS.join("\t"))
+	end
+end

data/spec/builder_to_sequencer_spec.rb

@@ -0,0 +1,388 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+
+
+describe MadderLib::Builder, "to Sequencer" do
+
+	it "turns an empty builder into an empty sequencer" do
+		sequencer = MadderLib::Builder.new.to_sequencer
+
+		sequencer.should have(0).steps
+		sequencer.should have(0).anytimes
+		sequencer.should have(0).befores
+		sequencer.should have(0).afters
+	end
+
+	it "handles a single phrase" do
+		builder = MadderLib::Builder.new()
+		phrase = builder.say('puh-TAY-to').or.say('puh-TAH-to')
+		sequencer = builder.to_sequencer
+
+		sequencer.should have(1).steps
+		sequencer.should have(0).anytimes
+		sequencer.should have(0).befores
+		sequencer.should have(0).afters
+
+		sequencer.steps.last.should equal(phrase)
+	end
+
+	it "requires valid ids for befores and afters" do
+		builder = madderlib do
+			before(:missing).say('uh')
+		end
+		lambda { builder.to_sequencer }.should raise_error(MadderLib::Error)
+
+		builder = madderlib do
+			after(:missing).say('whoa')
+		end
+		lambda { builder.to_sequencer }.should raise_error(MadderLib::Error)
+	end
+
+	it "reminder... Builder#say doesn't derive a Phrase id" do
+		phrase = nil
+		builder = madderlib do
+			phrase = say(:it, 'words')
+			before(:it).say('something')
+		end
+
+		phrase.id.should be_nil
+		lambda { builder.to_sequencer }.should raise_error(MadderLib::Error)
+	end
+
+
+
+	it "properly sequences firsts" do
+		builder = madderlib :sequence_befores do
+			says('loud')
+			first.say('too')
+			first.say('yer')
+		end
+
+		sequencer = builder.to_sequencer
+		sequencer.should have(3).steps
+
+		ids = []
+		sequencer.each_phrase do |phrase|
+			phrase.should have(1).instructions
+			words = phrase.instructions.last.words
+			words.should have(1).items
+
+			ids << words.last
+		end
+		ids.should eql(%w{ yer too loud })
+	end
+
+	it "properly sequences lasts" do
+		builder = madderlib do
+			last.say('too')
+			lastly.say('big')
+			say('feet')
+		end
+
+		sequencer = builder.to_sequencer
+		sequencer.should have(3).steps
+
+		ids = []
+		sequencer.each_phrase do |phrase|
+			phrase.should have(1).instructions
+			words = phrase.instructions.last.words
+			words.should have(1).items
+
+			ids << words.last
+		end
+		ids.should eql(%w{ feet too big })
+	end
+
+
+
+	it "before and after require referenceable ids" do
+		#	doesn't complain on build
+		builder = madderlib do
+			before(:say).say 'before'
+			say 'saying'
+		end
+		#	but during validation, etc.
+		lambda { builder.validate }.should raise_error MadderLib::Error
+
+		builder = madderlib do
+			after(:say).say 'after'
+			say 'saying'
+		end
+		lambda { builder.validate }.should raise_error MadderLib::Error
+	end
+
+	it "moves befores and afters into their own little worlds" do
+		builder = madderlib do
+			after(:say, :after).say 'after'
+			before(:say, :before).say 'before'
+			a(:say).says 'says'
+		end
+
+		sequencer = builder.to_sequencer
+		sequencer.should have(1).steps
+
+		#	before
+		sequencer.should have(1).befores
+		dep = sequencer.befores[:say]
+		dep.should have(1).items
+		dep.last.instructions.last.words.last.should eql('before')
+
+		#	after
+		sequencer.should have(1).afters
+		dep = sequencer.afters[:say]
+		dep.should have(1).items
+		dep.last.instructions.last.words.last.should eql('after')
+
+		#	some more, to prove ordering
+		builder.append do
+			after(:say).say 'end'
+			before(:say).say 'begin'
+		end
+
+		sequencer = builder.to_sequencer
+
+		#	before
+		words = []
+		sequencer.befores[:say].each do |before|
+			words << before.instructions.last.words.last
+		end
+		words.should eql(['begin', 'before'])
+
+		#	after
+		words = []
+		sequencer.afters[:say].each do |after|
+			words << after.instructions.last.words.last
+		end
+		words.should eql(['after', 'end'])
+	end
+
+
+
+	it "anytime requires referenceable ids" do
+		#	doesn't complain on build
+		builder = madderlib do
+			anytime.say('dipsy').before(:say)
+			say 'doodle'
+		end
+		#	but during validation, etc.
+		lambda { builder.validate }.should raise_error MadderLib::Error
+
+		builder = madderlib do
+			anytime.say('doodle').after(:say)
+			say 'dipsy'
+		end
+		lambda { builder.validate }.should raise_error MadderLib::Error
+
+		builder = madderlib do
+			anytime.say('zzz').between(:night, :day)
+			say 'ni-night'
+		end
+		lambda { builder.validate }.should raise_error MadderLib::Error
+	end
+
+	it "anytimes go into their own little world" do
+		builder = madderlib :sequence_befores do
+			anytime(:b).before(:say).say('before')
+			anytime(:a).after(:say).say('after')
+			anytime(:ab).say('somewhere').after(:b).before(:a)
+			anytime(:t).between(:b, :a).say('tween')
+			a(:say).says 'hello'
+		end
+
+		sequencer = builder.to_sequencer
+		sequencer.should have(1).steps
+
+		sequencer.should have(4).anytimes
+
+		ids = []
+		sequencer.anytimes.each do |anytime|
+			id = anytime.id
+			ids << id
+			anytime.before.should_not be_nil unless :a == id
+			anytime.after.should_not be_nil unless :b == id
+		end
+
+		ids.should eql([:b, :a, :ab, :t])
+	end
+
+
+
+	it "blends everything together perfectly" do
+		builder = madderlib :sequence_befores do
+			last(:late).say('4')
+			first(:early).say('2')
+			last.say('5')
+			first.say('1')
+
+			before(:late).say('3.9')
+			after(:early).say('2.1')
+			before(:early).say('1.9')
+			after(:late).say('4.1')
+
+			anytime.between(:early, :late).say('imaginary')
+			anytime.say('random')
+
+			says('3')
+		end
+
+		sequencer = builder.to_sequencer
+		sequencer.should have(5).steps
+
+		marks = []
+		sequencer.steps.each do |phrase|
+			phrase.should have(1).instructions
+			words = phrase.instructions.last.words
+			words.should have(1).items
+
+			marks << words.last
+		end
+		marks.should eql(%w{ 1 2 3 4 5 })
+
+		sequencer.befores[:early].last.instructions.last.words.last.should eql('1.9')
+		sequencer.afters[:early].last.instructions.last.words.last.should eql('2.1')
+		sequencer.befores[:late].last.instructions.last.words.last.should eql('3.9')
+		sequencer.afters[:late].last.instructions.last.words.last.should eql('4.1')
+
+		marks = []
+		sequencer.anytimes.each do |phrase|
+			marks << phrase.instructions.last.words.last
+		end
+		marks.should eql(%w{ imaginary random })
+	end
+
+
+
+	it "supports setup and teardown blocks" do
+		holder = []
+
+		sequencer = (madderlib do
+			#	takes context, uses data, get and set local scope
+			#	multiple are handled sequentially
+			setup {|context| holder << :setup }
+			setup {|context| context.data[:word] = holder.first }
+			setup {|context| holder << :a_s }
+			setup(:first) {|context| holder << :b_s }
+
+			#	takes context
+			say {|context| context.data[:word] }
+
+			#	doesn't need context, set local scope
+			#	multiple are handled sequentially
+			teardown { holder << :teardown }
+			teardown(:first) { holder << :b_t }
+			teardown { holder << :a_t }
+		end).to_sequencer
+
+		#	due to execution sequence...
+		sequencer.words.should eql(%w{ b_s })
+
+		holder.should eql([:b_s, :setup, :a_s, :b_t, :teardown, :a_t])
+	end
+
+
+
+	it "can collect the executed context" do
+		builder = madderlib :outer do
+			say madderlib(:inner_1) { say 'inner' }
+			say 'plain'
+			#	tried a do .. end block here, wasn't seen
+			#		using { .. } does work
+			say madderlib(:inner_2) {
+				say madderlib(:deep_1) { say 'deep' }
+				say madderlib(:deep_2) { say 'deeper' }
+			}
+		end
+
+		#	capture the context
+		#		setup or teardown, not important
+		context, count = nil, 0
+		words = builder.words do |ctx|
+			context = ctx
+			count = ctx.spoken.size
+		end
+		words.should eql(%w{ inner plain deep deeper })
+
+		#	it'll be called before the context is used
+		count.should eql(0)
+
+		#	and here's what you get back
+		context.should_not be_nil
+		context.spoken.should have(3).phrases
+		context.silent.should have(0).phrases
+		context.instructions.should have(3).instructions
+
+		#	the :flat approach (default)
+		context.contexts.should have(4).contexts
+
+		#	just the sub-contexts, not the outer builder
+		ids = []
+		context.contexts.each {|ctx| ids << ctx.builder.id }
+
+		ids.should have(4).ids
+		ids.should eql([ :inner_1, :inner_2, :deep_1, :deep_2 ])
+
+		#	the :tree approach
+		#		just the inner ones
+		context.contexts(:tree).should have(2).contexts
+
+		#	hierarchical traversal
+		#		this traversal provides a full tree
+		#		including he the outer builder
+		ids = []
+		traverse = lambda do |ctx|
+			ids << ctx.builder.id
+			ctx.contexts(:tree).each {|sub| traverse.call(sub) }
+		end
+		traverse.call(context)
+
+		ids.should have(5).ids
+		ids.should eql([:outer, :inner_1, :inner_2, :deep_1, :deep_2 ])
+	end
+
+	it "can inject data into the context" do
+		builder = madderlib :inject_data do
+			say '('
+			say {|context| context[:text] }
+			say ')'
+
+		#	text is nil, so doesn't appear
+		builder.words.should eql(['(', ')'])
+
+		#	round trip with simple value
+		#		can't pull out the context with enumerator-based methods
+		#		but you can still inject data
+		context = nil
+
+		words = builder.words(:text => 'words') {|ctx| context = ctx }
+		context[:text].should eql('words')
+		words.should eql(['(', context[:text], ')'])
+
+		s = ''
+		builder.each_word(:text => 'each_word') {|word| s << word }
+		s.should eql('(each_word)')
+
+		#	proper handling of data / separator mixing
+		builder.sentence.should eql('( )')
+		builder.sentence(:text => 'sentence').should eql('( sentence )')
+		builder.sentence('', :text => 'sentence').should eql('(sentence)')
+		map = { :text => 'sentence' }
+		builder.sentence(map, '.').should eql('(.sentence.)')
+
+		#	so, let's try an indirection through the sequence
+		#		we're testing by omission
+		#		we won't see a phrase if the text is nil
+		sequencer = builder.to_sequencer
+
+		sequencer.phrases.should have(2).phrases
+		sequencer.phrases(:text => 'phrase').should have(3).phrases
+
+		phrases = []
+		sequencer.each_phrase {|phrase| phrases << phrase }
+		phrases.should have(2).phrases
+
+		phrases = []
+		sequencer.each_phrase(:text => 'phrase') {|phrase| phrases << phrase }
+		phrases.should have(3).phrases
+	end
+
+end