madderlib 0.1.0

data/lib/madderlib/conditional/registry.rb

@@ -0,0 +1,56 @@
+module MadderLib
+	module Conditional
+		module Registry #:nodoc: all
+
+			module Static
+				#	registers a preparation closure for the container
+				def add_prepare(&block)
+					conditional_prepares << block
+				end
+
+				def conditional_prepares
+					@conditional_prepares ||= []
+				end
+
+				#	registers a test closure for the container
+				def add_test(&block)
+					raise Error, 'block required' unless block_given?
+					conditional_tests << block
+				end
+
+				def conditional_tests
+					@conditional_tests ||= []
+				end
+			end
+
+
+
+			module Instance
+				#	called once per execution
+				def prepare(context)
+					#	execute all of our registered preparation blocks
+					self.class.conditional_prepares.each do |block|
+						(block.arity == 1 ? block.call(self) : block.call(self, context))
+					end
+
+					if self.methods.include?('instructions')
+						#	prepare each instruction
+						self.instructions.each {|instruction| instruction.prepare(context) }
+					end
+				end
+
+				#	returns true if the owner should be used
+				def test(context)
+					#	find the first failing test closure
+					#		it'd be nil if they all pass
+					failed = self.class.conditional_tests.find do |block|
+						#	first failure stops us
+						(! (block.arity == 1 ? block.call(self) : block.call(self, context)))
+					end
+
+					failed.nil?
+				end
+			end
+		end
+	end
+end

data/lib/madderlib/conditional/repeat.rb

@@ -0,0 +1,130 @@
+module MadderLib
+	module Conditional
+		#= Recur
+		#
+		#Introduces support for repeating usage of a Phrase
+		module Repeat
+
+			#= Recur::Phrase
+			#
+			#Introduces support for repeating usage of a Phrase.
+			#The Phrase itself is largely uninvolved; it simply uses the repeat logic of its Instruction
+			#
+			#See:  Recur::Instruction
+			module Phrase
+				#Adds repetition logic to the current Instruction
+				#
+				#See:  Instruction#repeat
+				def repeat(*args, &block)
+					self.instruction.repeat *args, &block
+				end
+				alias :repeats :repeat
+				alias :repeating :repeat
+				alias :times :repeat
+				alias :while :repeat
+			end
+
+
+
+			#= Recur::Instruction
+			#
+			#Introduces support for repeating usage of a Phrase.
+			#The Instruction will simply call its own Instruction#speak method until the repetition is over.
+			#The sum and total of all those calls becomes the Instruction's resulting words.
+			#Note that this is not simply a blind duplication of the results of the first call to speak
+			#
+			#See:  Recur::Phrase
+			module Instruction
+				def self.included(target) #:nodoc:
+					#	this method won't exist until inclusion
+					#		can't mess with it until that point
+					#	moreover, can't call the method 'speak'
+					#		won't overwrite an existing method
+					#		so, we do aliasing to swap
+					target.class_eval %q{
+						alias :pre_repeat_speak :speak
+						alias :speak :repeat_speak
+					}
+				end
+
+
+
+				def repeat_speak(context) #:nodoc:
+					#	no repetition may be requested
+					return pre_repeat_speak(context) unless @repeat_tester
+
+					#	keep speaking until we're told to stop
+					composite, count = [], 0
+
+					loop do
+						break unless @repeat_tester.invoke(count, context)
+
+						words = pre_repeat_speak(context)
+						break if words.empty?
+
+						composite << words
+						count += 1
+					end
+
+					#	as if we said it all at once
+					composite.flatten
+				end
+
+
+
+				#Specifies the repetition of this Phrase
+				#
+				#If provided, the arguments should contain:
+				#* a numeric value, which becomes the count
+				#* a Range, or two numerics (which define a Range), from which the count is chosen randomly
+				#* a Proc / lambda / block / closure, which returns false when the repetition should stop. \
+				#The block can either take (a) no arguments, (b) the repetition count, or; (c) the count <i>and</i> a Context.
+				#
+				#A repetition count of 0 will exclude the Phrase from the Builder result
+				#
+				#A repetition always ends when any Instruction returns an empty set of words.
+				#Processing will skip to the next Phrase, even if it could repeat again.
+				#This is due to the fact that Instruction#speak is called each time, which could provide different results
+				#
+				#Examples:
+				#  builder = madderlib do
+				#    say(:twice).times(2)
+				#    say(:couple).repeats(1, 2)
+				#    say(:thrice).while {|count| count < 3 }
+				#  end
+				#
+				#  words = builder.words
+				#  words.find_all {|word| word == 'twice' }.should have(2).items
+				#  words.find_all {|word| word == 'thrice' }.should have(3).items
+				#  count = words.find_all {|word| word == 'couple' }.size
+				#  (count >= 1 && count <= 2).should be_true
+				def repeat(*args, &block)
+					#	build a tester, set it aside
+					@repeat_tester = Helper::TestBlock.new *args, &block
+					self
+				end
+				alias :repeats :repeat
+				alias :repeating :repeat
+
+				#Specifies the repetition of this Phrase using arguments
+				#
+				#This is syntactic sugar, but also does not accept a block
+				#
+				#See:  repeat
+				def times(*args)
+					repeat *args
+				end
+
+				#Specifies the repetition of this Phrase using a block
+				#
+				#This is syntactic sugar, but also does not accept numeric arguments
+				#
+				#See:  repeat
+				def while(&block)
+					repeat &block
+				end
+			end
+
+		end
+	end
+end

data/lib/madderlib/context.rb

@@ -0,0 +1,140 @@
+module MadderLib
+	#= 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
+	class Context
+		attr_reader :sequencer #:nodoc:
+		#An Array of all Phrases which contributed words.
+		#The Phrases are listed in the order that they were executed
+		attr_reader :spoken
+		#An Array of all Phrases which <i>did not</i> 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
+		attr_reader :silent
+		#An Array of the ids of all Phrases which contributed words.
+		#The ids are listed in the order that their Phrases were executed
+		attr_reader :spoken_ids
+		#An Array of all Instructions which contributed words, as chosen from their Phrase.
+		#The Phrases are listed in the order that they were executed
+		attr_reader :instructions
+		#A Hash of arbitrary data for the Context.
+		#It is reserved for custom developer logic; the Context doesn't consider its data
+		attr_reader :data
+
+		#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 <i>required</i> for Builder execution.
+		def initialize(sequencer=nil)
+			@sequencer = sequencer
+			@spoken, @silent, @spoken_ids = [], [], []
+			@instructions, @contexts = [], []
+			@state, @data = {}, {}
+		end
+
+		#Returns the Builder associated with the Context, via its Sequencer
+		def builder
+			@sequencer.builder
+		end
+
+		#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)
+		def state(key)
+			hash = @state[key]
+			@state[key] = hash = {} unless hash
+			hash
+		end
+
+		#Provides convenient access to the data Hash.
+		#
+		#Examples:
+		#  context = MadderLib::Context.new
+		#  context.data[:key] = :value
+		#
+		#  context[:key].should equal(:value)
+		def [](k)
+			@data[k]
+		end
+		def []=(k, v)
+			@data[k] = v
+		end
+
+		#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 <i>not</i> include self, only its children (etc.)
+		#
+		#The sub-contexts will be returned as an Array, and so on down the Context hierarchy.
+		#If <code>:flat</code> is passed as an argument, the Array returned will contain a flattened hierarchy
+		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
+
+		#Adds a sub-context to the Context hierarchy
+		def add_context(context)
+			@contexts << context
+		end
+
+
+
+		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
+
+
+
+		class << self
+			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
+
+			def invoke(block, context) #:nodoc:
+				(block.arity == 0 ? block.call : block.call(context))
+			end
+		end
+	end
+
+	#An immutable empty Context singleton.
+	#Beats returning a null
+	Context::EMPTY = Context.new
+	Context::EMPTY.freeze
+end

data/lib/madderlib/core.rb

@@ -0,0 +1,217 @@
+module MadderLib
+	#= Error
+	#
+	#A Module-specific Exception class
+	#
+	#--
+	# i would have called it MadderLib::Exception
+	# except that i don't know how to access Kernel::Exception within the initialize logic
+	#++
+	class Error < Exception
+		#The propagated cause of this Exception, if appropriate
+		attr_reader :cause
+
+		#Constructed with a message and an optional 'causing' Exception.
+		#
+		#If no message is passed -- eg. only an Exception -- then this Error inherits its message.
+		def initialize(message, cause=nil)
+			if (Exception === message)
+				super message.to_s
+				@cause = message
+			else
+				super message
+				@cause = cause
+			end
+		end
+	end
+
+
+
+	#= KernelMethods
+	#
+	#A Module containing MadderLib methods which are injected into the Kernel scope / namespace.
+	#Requiring the gem has the side-effect of injecting these methods.
+	module KernelMethods
+		#A proxy for MadderLib::Builder.new .
+		#It returns a constructed Builder.
+		#
+		#The resulting Builder is automatically added to the active Grammar.
+		#The active grammar can be accessed via madderlib_grammar .
+		#
+		#Please see MadderLib::Builder for extensive examples of how a Builder itself is put to use
+		#
+		#Examples:
+		#  builder = madderlib do
+		#    say 'no id'
+		#  end
+		#  madderlib_grammar.builders.include?(builder).should be_true
+		#  madderlib_grammar.builder_map.values.include?(builder).should_not be_true
+		#
+		#  builder = madderlib :id do
+		#    say 'has id'
+		#  end
+		#  madderlib_grammar.builders.include?(builder).should be_true
+		#  madderlib_grammar.builder_map.values.include?(builder).should be_true
+		def madderlib(*args, &block)
+			builder = Builder.new *args
+			madderlib_grammar.add builder
+
+			builder.extend &block
+		end
+
+		#A proxy for MadderLib::Grammar.get_instance .
+		#It returns the active Grammar
+		#
+		#See:  madderlib
+		def madderlib_grammar
+			#	the current instance we're working with
+			Grammar.get_instance
+		end
+	end
+
+
+
+	#= Grammar
+	#
+	#A class for registering MadderLib Builders.
+	#
+	#It is intended to help de-couple Ruby scripts which generate Builders from those which use them.
+	class Grammar
+		class << self
+			#Constructs a new Grammar instance
+			#
+			#The new instance becomes the active Grammar, as accessible from get_instance
+			#
+			#Examples:
+			#  current = MadderLib::Grammar.new_instance
+			#  current.should have(0).builders
+			#  current.should equal(MadderLib::Grammar.get_instance)
+			#
+			#  one = madderlib { say 'one' }
+			#  current.should have(1).builders
+			#  current.builders.include?(one).should be_true
+			#
+			#  fresh = MadderLib::Grammar.new_instance
+			#  fresh.should equal(MadderLib::Grammar.get_instance)
+			#
+			#  two = madderlib { say 'two' }
+			#  fresh.should have(1).builders
+			#  fresh.builders.include?(two).should be_true
+			#
+			#  current.should_not equal(MadderLib::Grammar.get_instance)
+			#  current.builders.include?(two).should_not be_true
+			def new_instance
+				@instance = self.new
+			end
+
+			#Returns the active Grammar instance
+			#
+			#If no such Grammar exists, a new one is created
+			#
+			#See:  new_instance
+			def get_instance
+				@instance ||= new_instance
+			end
+		end
+
+		#An Array of all Builders in the Grammar
+		attr_reader :builders
+		#A Hash of all the Builders in the Grammar which have an id
+		attr_reader :builder_map
+
+		#Constructs a new Grammar
+		def initialize
+			@builders = []
+			@builder_map = {}
+
+			#	randomness
+			srand(Time.now.to_i)
+		end
+
+		#Adds a Builder to the Grammar.
+		#
+		#How this is done depends on the arguments passed
+		#* if an existing Builder is provided, it is added to the Grammar (as-is)
+		#* if nothing is provided, then a new Builder is constructed (without any id)
+		#* otherwise, any argument passed is treated as the id for a newly-constructed Builder
+		#
+		#If a block is provided, and a Builder is constructed, that block is leveraged <i>a la</i> Builder#extend
+		#
+		#Examples:
+		#  grammar = MadderLib::Grammar.new_instance
+		#
+		#  builder = madderlib { say 'exists' }
+		#  x = grammar.add(builder)
+		#  x.should equal(builder)
+		#  grammar.should have(1).builders
+		#  grammar.builder_map.should have(0).keys
+		#
+		#  builder = grammar.add { say 'no id' }
+		#  grammar.should have(2).builders
+		#  grammar.builder_map.should have(0).keys
+		#  builder.sentence.should eql('no id')
+		#
+		#  builder = grammar << :id
+		#  grammar.should have(3).builders
+		#  grammar.builder_map.values.include?(builder).should be_true
+		#  builder.sentence.should eql('')
+		def add(*args, &block)
+			builder = args.first
+
+			case builder
+				when Builder
+					#	leave it alone
+				when nil
+					#	new, with block dispatched
+					builder = Builder.new &block
+				else
+					#	new, assume the arg is an ID
+					builder = Builder.new args.first, &block
+			end
+
+			unless @builders.include?(builder)
+				@builders << builder
+
+				#	an id is not required
+				id = builder.id
+				(@builder_map[id] = builder) if id
+			end
+
+			builder
+		end
+		alias :<< :add
+
+		#Provides convenient access to the Builder map (builder_map).
+		#
+		#Examples:
+		#  grammar = MadderLib::Grammar.new_instance
+		#
+		#  builder = grammar.add(:id) { say 'has id' }
+		#  grammar[:id].should equal(builder)
+		def [](key)
+			@builder_map[key]
+		end
+
+		#Freezes, and closes / completes, the current Grammar
+		#
+		#The Grammar becomes immutable.
+		#As a side-effect, if it is the current Grammar, a new_instance is created and used from this point forwards
+		def freeze
+			super
+
+			#	deep freeze
+			[@builders, @builder_map].each {|o| o.freeze }
+
+			if self.class.get_instance == self
+				#	we can no longer be the current Grammar
+				self.class.new_instance
+			end
+		end
+		alias :close :freeze
+		alias :complete :freeze
+	end
+end
+
+
+#	inject into the Kernel
+include MadderLib::KernelMethods