madderlib 0.1.0

data/lib/madderlib/conditional/allowed.rb

@@ -0,0 +1,144 @@
+module MadderLib
+	module Conditional
+		#= Allowed
+		#
+		#Introduces support for conditional usage of an Instruction
+		module Allowed
+
+			#= Allowed::Phrase
+			#
+			#Introduces support for conditional usage of an Instruction
+			#
+			#If a Phrase has no Instructions that can be used, it will return an empty result and be omitted
+			#
+			#See:  Allowed::Instruction
+			module Phrase
+				#Adds conditional logic to the current Instruction
+				#
+				#See:  Instruction#assuming
+				def assuming(*args, &block)
+					self.instruction.assuming *args, &block
+				end
+				alias :presuming :assuming
+				alias :if :assuming
+
+				#Adds conditional logic to the current Instruction
+				#
+				#See:  Instruction#forbidding
+				def forbidding(*args, &block)
+					self.instruction.forbidding *args, &block
+				end
+				alias :unless :forbidding
+			end
+
+
+
+			#= Allowed::Instruction
+			#
+			#Introduces support for conditional usage of an Instruction
+			#
+			#The conditional logic is evaluated for each separate execution of the Builder.
+			#If the conditional returns false, then the Instruction is excluded from use.
+			#If it returns true, then the Instruction is still a viable candidate (though other constraints may be applied)
+			#
+			#See:  Allowed::Phrase
+			module Instruction
+				def self.included(target) #:nodoc:
+					#	register a test to test all allowances for the instruction
+					#		return false at the first one that fails
+					target.add_test do |instruction, context|
+						failure = instruction.conditional_allowances.find do |block|
+							#	first failure stops us
+							(! Context.invoke(block, context))
+						end
+
+						failure.nil?
+					end
+				end
+
+
+
+				#The instruction will only be used if these conditions are true
+				#
+				#The id of a Phrase can be provided.
+				#If so, then the condition tested is:  the reference must have already been added to the Builder's result.
+				#This can be identified through Context#spoken
+				#
+				#Alternately, a custom block can be provided.
+				#The block can either take no arguments, or a Context.
+				#The Instruction may only be used when that block returns a true (eg. non-false) value
+				#
+				#Examples:
+				#  switch = false
+				#  builder = madderlib do
+				#    an(:on).says('on').assuming { switch }
+				#    an(:off).says('off').if { ! switch }
+				#    say('bright').if :on
+				#    say('dark').if :off
+				#  end
+				#
+				#  builder.sentence.should eql('off dark')
+				#  switch = true
+				#  builder.sentence.should eql('on bright')
+				def assuming(id=nil, &block)
+					if block
+						raise Error, 'block AND id provided, requires one or the other' if id
+						Context.validate(block)
+					else
+						#	true if the id expressed has been spoken
+						block = lambda {|context| context.spoken_ids.include?(id) }
+					end
+
+					#	set it aside for a lazy day
+					conditional_allowances << block
+					self
+				end
+				alias :presuming :assuming
+				alias :if :assuming
+
+				#The instruction will only be used if these conditions are false.
+				#This is the logical opposite of assuming.
+				#
+				#The id of a Phrase can be provided.
+				#If so, then the condition tested is:  the reference must not have been added to the Builder's result.
+				#This can be identified through Context#spoken
+				#
+				#Alternately, a custom block can be provided.
+				#The block can either take no arguments, or a Context.
+				#The Instruction may only be used when that block returns a false value
+				#
+				#Examples:
+				#  switch = false
+				#  builder = madderlib do
+				#    an(:on).says('on').forbidding { ! switch }
+				#    an(:off).says('off').unless { switch }
+				#    say('bright').unless :off
+				#    say('dark').unless :on
+				#  end
+				#
+				#  builder.sentence.should eql('off dark')
+				#  switch = true
+				#  builder.sentence.should eql('on bright')
+				def forbidding(id=nil, &block)
+					if block
+						raise Error, 'block AND id provided, requires one or the other' if id
+						Context.validate(block)
+
+						self.assuming {|context| ! Context.invoke(block, context) }
+					else
+						#	true unless the id expressed has been spoken
+						self.assuming {|context| ! context.spoken_ids.include?(id) }
+					end
+				end
+				alias :unless :forbidding
+
+
+
+				def conditional_allowances #:nodoc:
+					@conditional_allowances ||= []
+				end
+			end
+
+		end
+	end
+end

data/lib/madderlib/conditional/helper.rb

@@ -0,0 +1,135 @@
+module MadderLib
+	module Conditional
+		module Helper #:nodoc: all
+
+			class TestBlock
+				FALSE = lambda { false }
+				ONE = lambda { 1 }
+
+				attr_reader :criteria
+
+				def initialize(*args, &block)
+					if block
+						#	if we get a block, use it!
+						raise Error, 'block AND args provided, requires one or the other' if (args && (! args.empty?))
+						raise Error, 'block arity should be 0; 1 (count) or; 2 (count, Context)' if (block.arity > 2)
+
+						#	it will remain unchanging
+						@criteria = block
+					else
+						#	leave the originals alone
+						args = args.clone
+
+						begin
+							#	how does it start?
+							arg = args.shift
+
+							if Range === arg
+								#	we received a Range
+								@criteria = arg
+							elsif arg.respond_to?(:integer?) && arg.integer?
+								upper = args.first
+								if upper && upper.respond_to?(:integer?) && upper.integer?
+									#	we can make a Range from that
+									@criteria = Range.new(arg, args.shift)
+								else
+									#	just a count
+									@criteria = arg
+								end
+							else
+								raise Error, "invalid test block argument : #{arg.inspect}"
+							end
+						rescue Error => e
+							raise e
+						rescue Exception => e
+							#	wrap
+							raise e
+							raise Error.new("invalid test block argument : #{arg.inspect}", e)
+						end
+
+						#	beyond that, is there a unit?
+						#		we deal with all of that during build
+						@units = args.shift
+					end
+				end
+
+
+
+				def block
+					if Proc === @criteria
+						#	the block will do its own testing
+						@criteria
+					elsif Range === @criteria
+						#	we'll stop somewhere in that range
+						#		note that it's inclusive
+						#		if the caller says '2 .. 4', 4 should be a possibility
+						limit = unitize(@criteria.rand_inclusive)
+						lambda {|count| count < limit }
+					elsif @criteria.integer?
+						limit = unitize(@criteria)
+						lambda {|count| count < limit }
+					else
+						#	never will succeed
+						FALSE
+					end
+				end
+
+				def invoke(*args, &given_block)
+					#	take in a block, or use the internally held one
+					#		allows for external buffering
+					b = block_given? ? given_block : self.block
+					p = args
+
+					if b.arity < 1
+						#	how interesting!  arity of -1
+						b.call
+					else
+						#	only as many args as supported
+						#		do not worry about shortfall; that'll be a failure
+						p.pop while b.arity < p.size
+						b.call *p
+					end
+				end
+
+
+
+				def to_i(context)
+					value = nil
+
+					if Proc === @criteria
+						value = MadderLib::Context.invoke(@criteria, context)
+					elsif Range === @criteria
+						value = @criteria.max
+					elsif @criteria.integer?
+						value = @criteria
+					end
+
+					#	has to be an integer, by definition
+					if value && value.respond_to?(:integer?) && value.integer?
+						unitize(value)
+					else
+						nil
+					end
+				end
+
+
+
+				#	- - - - -
+				protected
+
+				def unitize(limit)
+					case @units
+						when :minutes, :minute
+							#	no diff, for now
+							limit
+						when :times, :time
+							limit
+						else
+							limit
+					end
+				end
+			end
+
+		end
+	end
+end

data/lib/madderlib/conditional/likely.rb

@@ -0,0 +1,162 @@
+module MadderLib
+	module Conditional
+		#= Likely
+		#
+		#Introduces support for proportional selection from multiple Instructions in a given Phrase
+		module Likely
+			#The default weight for an Instruction, which is 1
+			DEFAULT_WEIGHT = 1
+
+			#= Likely::Phrase
+			#
+			#Introduces support for proportional selection from multiple Instructions in a given Phrase
+			#
+			#This is a very fancy way of saying 'weighted choices'.
+			#Using Phrase#alternately, multiple Instructions can be added to the same Phrase.
+			#Each one will either use the DEFAULT_WEIGHT, if not otherwise specified, or:
+			#
+			#* a numeric value
+			#* a Proc / lambda / block / closure which returns a numeric value
+			#
+			#The weights for all Instructions are totalled prior to each execution of the Builder.
+			#A random weight is chosen, and that defines the Instruction to be used
+			#
+			#See:  Likely::Instruction
+			module Phrase
+				def self.included(target) #:nodoc:
+					#	before each run, we need to prepare ourself
+					target.add_prepare do |phrase, context|
+						#	no point in likelihood when there's only one choice
+						unless phrase.instructions.size < 2
+							weights = []
+							phrase.instructions.each do |instruction|
+								#	put on a default weight if no other option
+								while (tester = instruction.conditional_likely_tester).nil?
+									instruction.likely(DEFAULT_WEIGHT)
+								end
+
+								weight = tester.to_i(context)
+								raise Error, 'invalid weight for instruction : #{instruction.words}' unless weight
+								weights << weight
+							end
+
+							#	easy distributions
+							total = 0
+							Range.new(0, weights.size - 1).each do |index|
+								weight, instruction = weights[index], phrase.instructions[index]
+
+								state = context.state(instruction)
+								state[:likely_lower] = total
+								state[:likely_upper] = (total += weight)
+							end
+
+							#	choose a random value
+							state = context.state(phrase)
+							state[:likely_total] = total
+							state[:likely_count] = rand(total) # Range.new(0, total).rand_inclusive
+						end
+					end
+				end
+
+
+
+				#Adds proportional logic to the current Instruction
+				#
+				#See:  Instruction#likely
+				def likely(*args, &block)
+					self.instruction.likely *args, &block
+				end
+				alias :weight :likely
+				alias :weighted :likely
+				alias :weighing :likely
+				alias :odds :likely
+			end
+
+
+
+			#= Likely::Instruction
+			#
+			#Introduces support for proportional selection from multiple Instructions in a given Phrase
+			#
+			#See:  Likely::Phrase
+			module Instruction
+				def self.included(target) #:nodoc:
+					#	register a test to test all allowances for the instruction
+					#		return false at the first one that fails
+					target.add_test do |instruction, context|
+						phrase = instruction.phrase
+						test = true
+
+						state = context.state(phrase)
+						total = state[:likely_total]
+						count = state[:likely_count]
+
+						#	will only have a count if there's likelihood calc required
+						if count
+							state = context.state(instruction)
+							lower = state[:likely_lower]
+							upper = state[:likely_upper]
+
+							test = (count >= lower) && (count < upper)
+
+							if test && phrase.respond_to?(:recurs?) && phrase.recurs?
+								#	set it up for the next recurrance
+								#		we don't want the same thing over and over again
+								state[:likely_count] = rand(total)
+							end
+						end
+
+						test
+					end
+				end
+
+
+
+				#Specifies the likelihood of this Instruction being used, compared to its siblings in their Phrase
+				#
+				#If provided, the arguments should contain:
+				#* a numeric value, which becomes the weight
+				#* a Range, or two numerics (which define a Range), from which the weight is chosen randomly
+				#* a Proc / lambda / block / closure, which returns a numeric value. \
+				#The block can either take no arguments, or a Context.
+				#
+				#See:  Instruction#alternately
+				#
+				#Examples:
+				#  builder = madderlib do
+				#    say('parsley').likely(4)
+				#    alternately(3).say('sage')
+				#    alternately.say('rosemary').weighted(2).or.say('thyme')
+				#  end
+				#
+				#  usage = {}
+				#  60.times do
+				#    key = builder.sentence
+				#    usage[key] = (usage[key] || 0) + 1
+				#  end
+				#
+				#  #  if proportions were accurately reproducible:
+				#  #    usage['parsley'].should eql(20)
+				#  #    usage['sage'].should eql(15)
+				#  #    usage['rosemary'].should eql(10)
+				#  #    usage['thyme'].should eql(5)
+				def likely(*args, &block)
+					#	build a tester, set it aside
+					@likely_tester = Helper::TestBlock.new *args, &block
+					self
+				end
+				alias :weight :likely
+				alias :weighted :likely
+				alias :weighing :likely
+				alias :odds :likely
+
+
+
+				def conditional_likely_tester #:nodoc:
+					@likely_tester
+				end
+			end
+
+		end
+	end
+end

data/lib/madderlib/conditional/recur.rb

@@ -0,0 +1,103 @@
+module MadderLib
+	module Conditional
+		#= Recur
+		#
+		#Introduces support for recurrant usage of a Phrase
+		module Recur
+
+			#= Recur::Phrase
+			#
+			#Introduces support for recurrant usage of a Phrase.
+			#This is particularly useful for an AnywherePhrase, whose position is randomly chosen.
+			#If it has a recurrence, it may appear multiple times.
+			#All of this is independent of whatever Instructions are contained within the Phrase
+			module Phrase
+				def self.included(target) #:nodoc:
+					#	before each run, we need to prepare ourself
+					target.add_prepare do |phrase, context|
+						unless phrase.conditional_recur_tester
+							#	we'll only run once if not told otherwise
+							phrase.recur 1
+						end
+
+						#	we must retain state (the number of times called)
+						#	and a consistent block for testing
+						state = context.state(phrase)
+						state[:recur_block] = phrase.conditional_recur_tester.block
+						state[:recur_count] = 0
+					end
+
+					#	register a test for recurrance
+					target.add_test do |phrase, context|
+						#	where we at now
+						state = context.state(phrase)
+						block = state[:recur_block]
+						count = state[:recur_count]
+						state[:recur_count] = count + 1
+
+						#	the block call returns the result of our test
+						#		we buffered the block, but want to invoke it conveniently
+						phrase.conditional_recur_tester.invoke(count, context, &block)
+					end
+				end
+
+
+
+				#Specifies the recurrance 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 recurrance should stop. \
+				#The block can either take (a) no arguments, (b) the recurrance count, or; (c) the count <i>and</i> a Context.
+				#
+				#A recurrance count of 0 will exclude the Phrase from the Builder result
+				#
+				#A recurrance always ends when any Instruction returns an empty set of words.
+				#Processing will skip to the next Phrase, even if more recurrances are available
+				#
+				#Examples:
+				#  builder = madderlib do
+				#    say(:start)
+				#    say(:end)
+				#    anytime.recurring(2).say(:any)
+				#    anytime.recurring {|count| count < 2 }.say(:also)
+				#  end
+				#
+				#  words = builder.words
+				#  words.find_all {|word| word == 'any' }.should have(2).items
+				#  words.find_all {|word| word == 'also' }.should have(2).items
+				def recur(*args, &block)
+					#	build a tester, set it aside
+					@recur_tester = Helper::TestBlock.new *args, &block
+					self
+				end
+				alias :recurs :recur
+				alias :recurring :recur
+
+				#Returns true if the Phrase can recur.
+				#By default, the recurrance count is 1, in which case this method returns false
+				def recurs?(context=MadderLib::Context::EMPTY)
+					!! (conditional_recur_tester && (conditional_recur_tester.to_i(context) > 1))
+				end
+
+
+
+				def conditional_recur_tester #:nodoc:
+					@recur_tester
+				end
+			end
+
+
+
+			module Instruction #:nodoc:
+				#	not impacted
+				#		the Phrase repeats, not the Instruction
+				#	we could proxy the recur back to the active phrase
+				#		but that would be confusing
+				#		you should only set up recurrence once; it's singleton to the phrase
+			end
+
+		end
+	end
+end