succubus 0.0.0 → 0.1.0

data/README.md

@@ -1,6 +1,6 @@
 _A random generator based on a generalised Backus-Naur Form grammar_
 
-[![Build Status](https://travis-ci.org/asilano/succubus.png?branch=master)](https://travis-ci.org/asilano/succubus)
+[![Build Status](https://travis-ci.org/asilano/succubus.png?branch=master)](https://travis-ci.org/asilano/succubus)[![Coverage Status](https://coveralls.io/repos/asilano/succubus/badge.png?branch=master)](https://coveralls.io/r/asilano/succubus)
 
 **Succubus** is a generator which takes stochastic paths through a 
 generalised Backus-Naur Form grammar to produce random text. For instance, the following:

data/Rakefile

@@ -3,7 +3,9 @@ require 'bundler/gem_tasks'
 
 Rake::TestTask.new do |t|
   t.test_files = FileList['test/**/*_test.rb', 'spec/**/*_spec.rb']
-  t.warning = true
+
+  # Disable warnings - coveralls spews out a bunch
+  # t.warning = true
 end
 
 task :default => :test

data/lib/succubus.rb

@@ -1,77 +1,43 @@
+require 'succubus/grammar'
+require 'succubus/generator'
+require 'succubus/result'
+
+# @author Chris Howlett
 module Succubus
+  # Raised by {Grammar#initialize Grammar.new} if the grammar defined in the 
+  # supplied block cannot be parsed.
+  #
+  # @!attribute [r] errors
+  #   @return [Array<String>] the errors encountered during parsing
   class ParseError < RuntimeError
-    attr_accessor :errors
-  end
-  
-  class ExecuteError < RuntimeError
-    attr_accessor :errors, :partial
-  end
-  
-  class Grammar
-    def initialize(&block)
-      @rules = {}      
-      @errors = []
-      define_singleton_method(:create, block)
-      create
-      class << self ; undef_method :create ; end
-      
-      unless @errors.empty?
-        pe = ParseError.new("Errors found parsing")
-        pe.errors = @errors
-        raise pe
-      end
-    end
+    attr_reader :errors
 
-    def add_rule(name, *choices, &block)
-      name = name.to_sym
-      @errors << "Duplicate rule definition: #{name}" if @rules.include? name
-      @rules[name] = choices
-    end
-    
-    def execute(start)
-      gen = Generator.new(@rules)
-      gen.run(start)
-      
-      unless gen.errors.empty?
-        ee = ExecuteError.new("Errors found executing")
-        ee.errors = gen.errors
-        ee.partial = gen.result
-        raise ee
-      end
-      
-      gen.result
+    # @private
+    def set_errors(errors)
+      @errors = errors
     end
   end
-  
-  class Generator
-    attr_reader :result
-    attr_reader :errors
-    
-    def initialize(rules)
-      @result = ""
-      @rules = rules
-      @errors = []
-    end
-    
-    def run(rule)
-      @result = invoke(rule)
+
+  # Raised by {Grammar#execute} if the {Generator} encountered any errors
+  # while executing the grammar.
+  #
+  # @!attribute [r] errors
+  #   @return [Array<String>] the errors encountered during execution
+  # @!attribute [r] partial
+  #   @return [Result] as much of the result as the {Generator} was able
+  #     to produce. Typically, this will be a string with missing rules
+  #     surrounded by +!!missing!!+. For instance, +"My !!pet!! is nice"+
+  class ExecuteError < RuntimeError
+    attr_reader :errors, :partial
+
+    # @private
+    def set_errors(errors)
+      @errors = errors
     end
-    
-    def invoke(rule)
-      unless @rules.include? rule
-        @errors << "No such rule: #{rule}"
-        return "!!#{rule}!!"
-      end
-      
-      local_res = ""
-      @rules[rule].sample.scan(/(.*?(?<!\\)(?:\\\\)*)(<.*?>|$)/) do |match|
-        local_res << match[0]
-        unless match[1].empty?
-          local_res << invoke(match[1].match(/<(.*?)>/)[1].to_sym)
-        end
-      end
-      
-      return local_res
+
+    # @private
+    def set_partial(partial)
+      @partial = partial
     end
   end
-end
+end

data/lib/succubus/generator.rb

@@ -0,0 +1,82 @@
+module Succubus
+  # Class which handles running through a {Grammar} and producing a
+  # {Result} string.
+  #
+  # @private
+  class Generator
+  
+    # Run through a given {Grammar}, starting at a given rule. Optionally
+    # use a given random seed.
+    #
+    # @param [Grammar] grammar the {Grammar} to generate a string from
+    # @param [Symbol] rule the name of the rule to start generation from
+    # @param [Integer] seed optional random seed. Defaults to +nil+, which will
+    #   make the {Generator} use a random seed
+    def self.run(grammar, rule, seed=nil)
+      new(grammar, seed).run(rule)
+    end
+
+    # Create a new {Generator}, ready to run through the supplied {Grammar},
+    # optionally with the given random seed.
+    #
+    # @param [Grammar] grammar the {Grammar} to generate a string from
+    # @param [Integer] seed optional random seed. Defaults to +nil+, which will
+    #   make the {Generator} use a random seed
+    def initialize(grammar, seed=nil)
+      @rules = grammar.rules
+
+      @seed = seed
+      unless @seed
+        srand()
+        @seed = rand(0xffffffff)
+      end
+      srand(@seed)
+
+      @errors = []
+    end
+
+    # Produce a random {Result} string from the Generator's {Grammar}
+    #
+    # @param [Symbol] rule the name of the rule to start generation from
+    # @return [Result] the {Result} string produced
+    def run(rule)
+      @result = Result.new(@seed, invoke(rule))
+      @result.set_errors(@errors)
+
+      return @result
+    end
+
+  private
+    # Execute a single rule all the way down, returning the +String+ randomly
+    # produced from it
+    #
+    # @param [Symbol] rule the name of the rule to execute
+    # @return [String] the string produced
+    def invoke(rule)
+      # Check the rule is defined; error if so
+      unless @rules.include? rule
+        @errors << "No such rule: #{rule}"
+        return "!!#{rule}!!"
+      end
+
+      local_res = ""
+      
+      # Pick an option. We can't use Array#sample, as its implementation differs
+      # between Ruby versions, so random seeds aren't portable.
+      choices = @rules[rule]
+      choice = choices[rand(choices.length)]
+      
+      # Scan it for all instances of (unescaped) <rules>
+      # Each match will be an array containing the portion of string before
+      # the <rule>; and the <rule> itself (which may be empty on the last match)
+      choice.scan(/(.*?(?<!\\)(?:\\\\)*)(<.*?>|$)/) do |match|
+        local_res << match[0]
+        unless match[1].empty?
+          local_res << invoke(match[1].match(/<(.*?)>/)[1].to_sym)
+        end
+      end
+
+      return local_res
+    end
+  end
+end

data/lib/succubus/grammar.rb

@@ -0,0 +1,79 @@
+module Succubus
+  # Class which contains the rules describing a grammar from
+  # which to generate random strings.
+  #
+  # {Grammar} provides the vast majority of the user interface
+  # to Succubus.
+  #
+  # @!attribute [r] last_seed
+  #   @return [Integer] the random seed used by the last call to {#execute}
+  # @!attribute [r] rules
+  #   @return [Hash<Symbol => String>] the rules describing this grammar
+  class Grammar
+    attr_reader :last_seed
+    attr_reader :rules
+
+    # Create a new {Grammar} object. {#initialize Grammar.new} should be passed
+    # a block defining the rules for the grammar. +self+ in the block will be
+    # the newly-created {Grammar} instance
+    #
+    # @yield Block defining the grammar. +self+ is the newly-created {Grammar},
+    #   so bare calls to {#add_rule} work as expected.
+    # @raise [ParseError] if errors were encountered parsing the grammar in the
+    #   supplied block
+    def initialize(&block)
+      @rules = {}      
+      @errors = []
+      define_singleton_method(:create, block)
+      create
+      class << self ; undef_method :create ; end
+
+      unless @errors.empty?
+        pe = ParseError.new("Errors found parsing")
+        pe.set_errors(@errors)
+        raise pe
+      end
+    end
+
+    # Define a new rule into the {Grammar}.
+    #
+    # {#add_rule} is usually called from the block parameter of {#initialize Grammar.new};
+    # however, it can be called on an existing {Grammar} object. Errors encountered by
+    # {#add_rule} will only be reported when called via {#initialize Grammar.new}.
+    #
+    # @param [#to_sym] name name of the rule
+    # @param [Array<String>] choices possible replacements for the rule. When +<name>+ is
+    #   encountered during execution of the {Grammar}, +<name>+ will be replaced by one of 
+    #   the strings in +choices+ chosen uniformly at random.
+    def add_rule(name, *choices)
+      name = name.to_sym
+      @errors << "Duplicate rule definition: #{name}" if @rules.include? name
+      @rules[name] = choices
+    end
+
+    # Execute the grammar, producing a random {Result} string.
+    #
+    # The rule named +start+ is examined, and one of that rule's choices chosen. Then, for each
+    # rule reference tag +<name>+ in that choice, the tag is recursively replaced with one of 
+    # the choices for the rule named +name+.
+    #
+    # @param [#to_sym] start name of the rule to start execution at
+    # @param [Integer] seed optional random seed. Defaults to +nil+, which will
+    #   cause a random seed to be used
+    #
+    # @raise [ExecuteError] if errors were encountered while executing the grammar
+    def execute(start, seed=nil)
+      result = Generator.run(self, start.to_sym, seed)
+
+      unless result.errors.empty?
+        ee = ExecuteError.new("Errors found executing")
+        ee.set_errors(result.errors)
+        ee.set_partial(result)
+        raise ee
+      end
+
+      @last_seed = result.random_seed
+      result
+    end
+  end
+end

data/lib/succubus/result.rb

@@ -0,0 +1,39 @@
+module Succubus
+  # Class containing the result of executing a {Grammar}.
+  #
+  # Result is a subclass of String, so it can be used exactly as if it were a String.
+  # Its main purpose is to provide access to metadata about the execution that
+  # produced it - namely the +random_seed+ used, and any +errors+ produced.
+  #
+  # @!attribute [r] random_seed 
+  #   @return [Integer] The random seed used to generate this Result.
+  #     {#random_seed} can be passed to {Grammar#execute} to exactly repeat the process
+  #     that generated this {Result} (for possible debugging purposes, or reporting issues)
+  # @!attribute [r] errors
+  #   @return [Array<String>] Any errors that occurred during the generation
+  #     of this {Result}.
+  class Result < String
+    attr_reader :random_seed, :errors
+
+    # Create a new Result
+    #
+    # @private
+    #
+    # @param [Integer] seed The random seed used to generate this result
+    # @param [Array] args Passed through to +super+
+    # @param [Proc] block Passed through to +super+
+    def initialize(seed, *args, &block)
+      @random_seed = seed
+      super(*args, &block)
+    end
+
+    # Set the errors encountered creating this Result
+    #
+    # @private
+    #
+    # @param [Array<String>] errors the errors encountered
+    def set_errors(errors)
+      @errors = errors
+    end
+  end
+end

data/lib/succubus/version.rb

@@ -1,3 +1,4 @@
 module Succubus
-  VERSION = "0.0.0"
+  # The gem version
+  VERSION = "0.1.0"
 end

data/spec/grammar_spec.rb

@@ -1,5 +1,4 @@
-require 'minitest/autorun'
-require File.dirname(__FILE__) + '/../test/support/fixed_random'
+require File.dirname(__FILE__) + '/spec_helper'
 require 'succubus'
 
 describe Succubus::Grammar do
@@ -50,13 +49,27 @@ describe Succubus::Grammar do
     end
     
     it "should produce a known string given pre-chosen randomness" do
-      expect_sample ["I have a <colour> <pet>", "<pet>s look best in <colour>"], "<pet>s look best in <colour>"
-      expect_sample ["cat", "dog"], "cat"
-      expect_sample ["black", "white"], "black"
+      # From ["I have a <colour> <pet>", "<pet>s look best in <colour>"], choose "<pet>s look best in <colour>"
+      expect_random 2, 1
+      # From ["cat", "dog"], choose "cat"
+      expect_random 2, 0
+      # From ["black", "white"], choose "black"
+      expect_random 2, 0
       
       @grammar.execute(:base).must_equal "cats look best in black"
       
-      samples_must_be_used
+      queue_must_be_used
+    end
+    
+    it "should always produce the same string given a known seed" do
+      result = @grammar.execute(:base)
+      result.random_seed.wont_be_nil
+      
+      seed = result.random_seed
+      100.times { @grammar.execute(:base, seed).must_equal result }
+      
+      # We know from manual runs that the seed 42 produces "I have a white cat"
+      100.times { @grammar.execute(:base, 42).must_equal "I have a white cat" }
     end
   end
   
@@ -72,7 +85,7 @@ describe Succubus::Grammar do
       end
       
       ex = bad_parse.must_raise Succubus::ParseError
-      ex.errors.must_have_same_elements_as ["Duplicate rule definition: colour", "Duplicate rule definition: base"]
+      ex.errors.must_equal_contents ["Duplicate rule definition: colour", "Duplicate rule definition: base"]
     end
     
     it "should fail to execute when rules are missing" do
@@ -81,10 +94,11 @@ describe Succubus::Grammar do
         add_rule :colour, "black", "white"
       end
       
-      expect_sample %w<black white>, "black"
+      # From ["black", "white"], choose "black"
+      expect_random 2, 0
       
       ex = proc {grammar.execute(:base)}.must_raise Succubus::ExecuteError
-      ex.errors.must_have_same_elements_as ["No such rule: size", "No such rule: pet"]
+      ex.errors.must_equal_contents ["No such rule: size", "No such rule: pet"]
       ex.partial.must_equal "I have a !!size!! black !!pet!!"
     end
   end

data/spec/spec_helper.rb

@@ -0,0 +1,27 @@
+require 'coveralls'
+Coveralls.wear! do
+	add_filter '/test/'
+	add_filter '/spec/'
+	add_filter '/examples/'
+end
+require 'minitest/autorun'
+require 'minitest/great_expectations'
+
+if false
+require 'turn'
+Turn.config do |c|
+ # use one of output formats:
+ # :outline  - turn's original case/test outline mode [default]
+ # :progress - indicates progress with progress bar
+ # :dotted   - test/unit's traditional dot-progress mode
+ # :pretty   - new pretty reporter
+ # :marshal  - dump output as YAML (normal run mode only)
+ # :cue      - interactive testing
+ c.format  = :outline
+ # turn on invoke/execute tracing, enable full backtrace
+ c.trace   = true
+ # use humanized test names (works only with :outline format)
+ c.natural = true
+end
+end
+require File.dirname(__FILE__) + '/../test/support/fixed_random'

data/test/support/fixed_random.rb

@@ -1,40 +1,39 @@
-require File.dirname(__FILE__) + '/subset_asserts'
-
 module MiniTest::Assertions
-  @@queued_samples = []
+  @@queued_random = []
   
-  def self.queued_samples; @@queued_samples; end
-  def self.next_sample; @@queued_samples.shift; end
+  def self.queued_random; @@queued_random; end
+  def self.next_random; @@queued_random.shift; end
   
-  def expect_sample(options, *choice)
-    assert_subset choice, options, "Can't queue #{options.inspect}.sample => #{choice}; choice not in options"
-    @@queued_samples << {:options => options, :choice => choice}
+  def expect_random(max, choice)
+    assert_includes (0...max), choice, "Can't queue rand(#{max.inspect}) => #{choice}; choice not in [0-1)"
+    unless max.nil?
+      assert_kind_of Integer, choice, "Can't queue rand(#{max}) => #{choice}; choice not an integer"
+    end
+    @@queued_random << {:max => max, :choice => choice}
   end
   
-  def samples_must_be_used
-    assert_empty @@queued_samples, "Expected to have used all queued samples: #{@@queued_samples.length} left"
+  def queue_must_be_used
+    assert_empty @@queued_random, "Expected to have used all queued random choices: #{@@queued_random.length} left"
   end
 end
 
-unless Array.method_defined? :sample_with_predefined_values
-  class Array
-    def sample_with_predefined_values(n = nil, &block)
-      queued = MiniTest::Assertions.queued_samples
-      if !queued.empty? && queued[0][:options] == self && queued[0][:choice].length == (n || 1)
-        expected = MiniTest::Assertions.next_sample
-        ret = expected[:choice]
-        ret = ret[0] if n.nil?
-        return ret
+unless Kernel.method_defined? :rand_with_predefined_values
+  module Kernel
+    def rand_with_predefined_values(max=nil, &block)
+      queued = MiniTest::Assertions.queued_random
+      if !queued.empty? && queued[0][:max] == max
+        expected = MiniTest::Assertions.next_random
+        return expected[:choice]
       else
-        if n
-          sample_without_predefined_values(n, &block)
+        if max
+          rand_without_predefined_values(max, &block)
         else
-          sample_without_predefined_values(&block)
+          rand_without_predefined_values(&block)
         end
       end
     end
-    alias_method :sample_without_predefined_values, :sample
-    alias_method :sample, :sample_with_predefined_values
+    alias_method :rand_without_predefined_values, :rand
+    alias_method :rand, :rand_with_predefined_values
     
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: succubus
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-11 00:00:00.000000000 Z
+date: 2013-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &20243712 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,15 +21,32 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  version_requirements: *20243712
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &20243460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20243460
 - !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
+  name: minitest-great_expectations
+  requirement: &20243208 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20243208
+- !ruby/object:Gem::Dependency
+  name: turn
+  requirement: &20242956 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -37,12 +54,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  version_requirements: *20242956
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: &20242704 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *20242704
 description: ! "    Succubus is a generator which takes stochastic paths through a
   \n    generalised Backus-Naur Form grammar to produce random text.\n\n    See the
   examples for details.\n"
@@ -51,13 +74,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/succubus/generator.rb
+- lib/succubus/grammar.rb
+- lib/succubus/result.rb
 - lib/succubus/version.rb
 - lib/succubus.rb
 - Rakefile
 - README.md
 - test/support/fixed_random.rb
-- test/support/subset_asserts.rb
 - spec/grammar_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/asilano/succubus
 licenses: []
 post_install_message: 
@@ -78,11 +104,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.16
 signing_key: 
 specification_version: 3
 summary: A random generator based on a generalised Backus-Naur Form grammar
 test_files:
 - test/support/fixed_random.rb
-- test/support/subset_asserts.rb
 - spec/grammar_spec.rb
+- spec/spec_helper.rb

data/test/support/subset_asserts.rb

@@ -1,49 +0,0 @@
-module MiniTest::Assertions
-  def assert_subset(subset, superset, msg = nil)
-    sub = subset.to_a.dup
-    supe = superset.to_a.dup
-    msg ||= "#{sub.inspect} is not a subset of #{supe.inspect}"
-    failed = false
-    sub.each do |elem|
-      if supe.index(elem)
-        supe.delete_at(supe.index(elem) || li.length)
-      else
-        failed = true
-        break
-      end
-    end
-
-    assert(!failed, msg)
-  end
-
-  def assert_disjoint(left, right, msg = nil)
-    left_a = left.to_a.dup
-    right_a = right.to_a.dup
-    msg ||= "#{left_a.inspect} and #{right_a.inspect} are not disjoint"
-    failed = false
-    left_a.each do |elem|
-      if right_a.index(elem)
-        failed = true
-        break
-      end
-    end
-
-    assert(!failed, msg)
-  end
-  
-  def assert_same_elements(a1, a2, msg = nil)
-    [:select, :inject, :size].each do |m|
-      [a1, a2].each {|a| assert_respond_to(a, m, "Are you sure that #{a.inspect} is an array? It doesn't respond to #{m}.") }
-    end
-
-    assert a1h = a1.inject({}) { |h,e| h[e] = a1.select { |i| i == e }.size; h }
-    assert a2h = a2.inject({}) { |h,e| h[e] = a2.select { |i| i == e }.size; h }
-
-    assert_equal(a1h, a2h, msg)
-  end
-end
-
-module MiniTest::Expectations
-  infect_an_assertion :assert_subset, :must_be_subset_of
-  infect_an_assertion :assert_same_elements, :must_have_same_elements_as
-end