madderlib 0.1.0

data/lib/madderlib/extensions.rb

@@ -0,0 +1,40 @@
+class Range
+	#Returns a random number between the min and max of the Range.
+	#An optional precision can be provided, which assumed to be 0 (eg. Fixnum.floor)
+	def rand(precision=0)
+		rand_from self.min, self.max, precision
+	end
+
+	#Returns a random number within the min and max of the Range, which can potentially include the max.
+	#An optional precision can be provided, which assumed to be 0 (eg. Fixnum.floor)
+	def rand_inclusive(precision=0)
+		rand_from self.min, self.max + 1, precision
+	end
+
+	#	- - - - -
+	private
+
+	def rand_from(a, b, precision)
+		span = [a, b]
+		min, max = span.min, span.max
+
+		min + if precision == 0
+			#	no effort required
+			Kernel.rand(max - min).floor
+		else
+			#	some precision
+			p = (10 ** precision).to_f
+			Kernel.rand((max - min) * p) / p
+		end
+	end
+end
+
+
+
+class Array
+	#Composites the Array -- of Fixnums (characters) -- into a String.
+	#An exception will be raised if any value in the Array is not a Fixnum
+	def to_byte_s
+		self.collect {|c| c.chr }.join(nil)
+	end
+end

data/lib/madderlib/instruction.rb

@@ -0,0 +1,171 @@
+module MadderLib
+	#= Instruction
+	#
+	#A specific instruction within a MadderLib ruleset.
+	#
+	#A Phrase is comprised of one or more Instructions.
+	#Each Instruction contains the logic necessary to produce the result for the Phrase
+	#
+	#Typical 'words' that can appear in an Instruction are:
+	#* a String
+	#* a Symbol
+	#* a Proc / lambda / block / closure
+	#* another Builder
+	#* an Array of the above
+	#
+	#The logic by which these Object types are resolved is described within wordify .
+	#
+	#An Instruction also supports:
+	#
+	#* repetition, via Conditional::Repeat
+	#* conditional usage, via Conditional::Allowed
+	#* proportionate usage, via Conditional::Likely
+	class Instruction
+		class << self
+			include Conditional::Registry::Static
+		end
+		include Conditional::Registry::Instance
+
+		#A refererence to the Phrase which contains this Instruction
+		attr_reader :phrase
+		#An Array of the words produced by this Instruction.
+		#The term 'word' is used very loosely here; they are simply the Objects provided during construction
+		attr_reader :words
+
+
+
+		#Constructs a new Instruction
+		#
+		#The containing Phrase is required.
+		#
+		#Any number of arguments may be provided, and they become the Instruction's words.
+		#An optional block can be provided, and if so, it is also treated as a word (since a Proc is considered a valid 'word')
+		def initialize(phrase, *args, &block)
+			@phrase = phrase
+			@words = args
+			@words << block if block_given?
+		end
+
+
+
+		#A proxy for phrase.alternately .
+		#The Phrase#alternately method is invoked against the Instruction's containing Phrase with the arguments provided
+		def alternately(*args, &block)
+			#	proxy to the phrase
+			self.phrase.or *args, &block
+		end
+		alias :or :alternately
+
+
+
+		#Generates the list of words for this Instruction.
+		#
+		#This method returns a flattened Array of all the Instruction's words, resolved as of 'now'.
+		#All blank and nil values are removed from the Array
+		#
+		#A thorough description of how words are resolved can be find in the wordify method
+		#
+		#Example:
+		#  builder = madderlib do
+		#    say nil
+		#    say ''
+		#  end
+		#  builder.words.should eql([])
+		#
+		#  builder = madderlib do
+		#    say 'one'
+		#    say :two
+		#    say 3
+		#  end
+		#  builder.words.should eql(%w{ one two 3 })
+		#
+		#  builder = madderlib do
+		#    say []
+		#    say [ nil, 'one' ]
+		#    say [ :two, [ '', 3 ]]
+		#  end
+		#  builder.words.should eql(%w{ one two 3 })
+		#
+		#  builder = madderlib do
+		#    say madderlib { say 'one' }
+		#    say madderlib {
+		#      say madderlib { say :two }
+		#      say madderlib { say 3 }
+		#    }
+		#  end
+		#  builder.words.should eql(%w{ one two 3 })
+		#
+		#  words = [ 'one', lambda { :two }, madderlib { say 3 } ]
+		#  builder = madderlib do
+		#    say { words.shift }.repeat { ! words.empty? }
+		#  end
+		#  builder.words.should eql(%w{ one two 3 })
+		def speak(context)
+			#	wordify everything, and strip out blanks & nils
+			spoken = self.class.wordify(words, context)
+			spoken.find_all {|word| word && (! word.empty?) }
+		end
+
+
+
+		include Conditional::Allowed::Instruction
+		include Conditional::Repeat::Instruction
+		include Conditional::Likely::Instruction
+
+		#	- - - - -
+		protected
+
+		class << self
+			#Converts the object passed into a 'word', according to the following rules:
+			#
+			#* <code>nil</code> => nil
+			#* <code>String</code> => itself (blank Strings also)
+			#* <code>Proc / lambda / block / closure</code> => the result of invoking the block. \
+			#The block can either take no arguments, or a Context. \
+			#Please note that resolution of the Proc's scoped variables (etc.) occurs only at the time that wordify is invoked!
+			#* <code>Builder</code> => the result of Builder#words, which will be an Array
+			#* <code>Array</code> => a flattened Array of the each element, as converted via wordify
+			#
+			#Anything other Object type is converted to a string via Object#to_s.
+			#
+			#See:  speak
+			def wordify(source, context)
+				#	our own dogfood
+				if Builder === source
+					#	build the words
+					#		pull back and track the context
+					#		we know they'll be Strings, so no need for recursion
+					return source.words {|sub_context| context.add_context sub_context }
+				end
+
+				while (Proc === source)
+					#	evaluate, then wordify the result
+					#		this addresses the Proc-returns-a-Proc condition
+					#		it's a corner case
+					source = Context.invoke(source, context)
+				end
+
+				if (Array === source)
+					#	recursive parsing
+					#		plus flattening!
+					source = source.inject([]) do |a, word|
+						word = wordify(word, context)
+
+						if Array === word
+							a += word
+						else
+							a << word
+						end
+
+						a
+					end
+				elsif source && ! (String === source)
+					#	don't stringify nil
+					source = source.to_s
+				end
+
+				source
+			end
+		end
+	end
+end

data/lib/madderlib/phrase.rb

@@ -0,0 +1,284 @@
+module MadderLib
+	#= 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
+	class Phrase
+		class << self
+			include Conditional::Registry::Static
+		end
+		include Conditional::Registry::Instance
+
+		#A refererence to the Builder which contains this Phrase
+		attr_reader :builder
+		#The (optional) id of the Phrase
+		attr_reader :id
+		#An Array of the Instructions used by this Phrase
+		attr_reader :instructions
+
+
+
+		#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.
+		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
+
+
+
+		#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
+		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
+		alias :says :say
+
+		#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) }
+		def alternately(*args, &block)
+			#	hold onto these until we say something
+			@or_likely = [args, block]
+			self
+		end
+		alias :or :alternately
+
+		#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
+		def nothing
+			#	say nothing
+			say
+		end
+
+
+
+		#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.
+		def instruction
+			raise Error, 'there is no current Instruction' if @instructions.empty?
+
+			#	whatever our current once is
+			@instructions.last
+		end
+
+
+
+		#Generates the list of words for this Phrase
+		#
+		#This is done by:
+		#* choosing a suitable Instruction
+		#* invoking Instruction#speak
+		#
+		#See:  Instruction#speak
+		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
+
+
+
+		include Conditional::Allowed::Phrase
+		include Conditional::Repeat::Phrase
+		include Conditional::Likely::Phrase
+	end
+
+
+
+	#= AnytimePhrase
+	#
+	#A Phrase constructed by Builder#anywhere
+	#
+	#Beyond what a standard Phrase can do, an AnytimePhrase can specify:
+	#
+	#* the range of positions where it can be inserted into the Builder result
+	#* recurring usage, via Conditional::Recur .\
+	#This is <i>not</i> the same as having a repeating Instruction. \
+	#The Phrase recurrance indicates how many times it is resolved and inserted into the Builder result. \
+	#For example, a recurring Phrase can contain a repeating Instruction.
+	class AnytimePhrase < Phrase
+		def initialize(*args)
+			super
+		end
+
+
+
+		#States that this Phrase should only appear before the referenced Phrase, by id
+		#
+		#If the referenced Phrase does not appear in the Builder result, it can appear anywhere
+		#
+		#Examples:
+		#  flag = true
+		#  builder = madderlib do
+		#    say 'top'
+		#    also(:limit).say('middle').if { flag }
+		#    say 'bottom'
+		#
+		#    anywhere.say('hello').before(:limit)
+		#  end
+		#
+		#  10.times do
+		#    words = builder.words
+		#    words.index('hello').should eql(1)
+		#  end
+		#
+		#  flag = false
+		#  10.times do
+		#    words = builder.words
+		#    (words.index('hello') < 2).should be_true
+		#  end
+		def before(ref=nil)
+			if ref
+				#	settter
+				@before = ref
+				self
+			else
+				#	getter
+				@before
+			end
+		end
+
+		#States that this Phrase should only appear before the referenced Phrase, by id
+		#
+		#If the referenced Phrase does not appear in the Builder result, it can appear anywhere
+		#
+		#Examples:
+		#  flag = true
+		#  builder = madderlib do
+		#    say 'top'
+		#    also(:limit).say('middle').if { flag }
+		#    say 'bottom'
+		#
+		#    anywhere.say('hello').after(:limit)
+		#  end
+		#
+		#  10.times do
+		#    words = builder.words
+		#    words.index('hello').should eql(2)
+		#  end
+		#
+		#  flag = false
+		#  10.times do
+		#    words = builder.words
+		#    (words.index('hello') > 0).should be_true
+		#  end
+		def after(ref=nil)
+			if ref
+				#	settter
+				@after = ref
+				self
+			else
+				#	getter
+				@after
+			end
+		end
+
+		#A shorthand for expression both after and before limits
+		#
+		#The first argument is for after, the second is for before
+		#
+		#Examples:
+		#  builder = madderlib do
+		#    say 'top'
+		#    also(:upper).say('upper')
+		#    also(:lower).say('lower')
+		#    say 'bottom'
+		#
+		#    anywhere.say('hello').between(:upper, :lower)
+		#  end
+		#
+		#  10.times do
+		#    words = builder.words
+		#    words.index('hello').should eql(2)
+		#  end
+		def between(a, b)
+			after a
+			before b
+			self
+		end
+
+
+
+		include Conditional::Recur::Phrase
+	end
+end