succubus 0.0.0

data/README.md

@@ -0,0 +1,85 @@
+_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)
+
+**Succubus** is a generator which takes stochastic paths through a 
+generalised Backus-Naur Form grammar to produce random text. For instance, the following:
+
+    grammar = Succubus::Grammar.new do
+      add_rule :base, "I have a <colour> <pet>"
+      add_rule :colour, "black", "brown", "white"
+      add_rule :pet, "cat", "dog", "rabbit"
+    end
+    puts grammar.execute :base
+    
+...might output `I have a black dog`. Or `I have a brown rabbit`. Or any of the other 7 possible combinations of colour and animal.
+
+See the `examples/` folder for more sample generators!
+
+Installation
+============
+Succubus is a RubyGem. That means it's really easy to install. Simply run:
+
+    gem install succubus
+    
+and you're done.
+
+Compatability
+=============
+Succubus is tested against Ruby 1.9.3 and Ruby 2.0 (by Travis - see the little widget up to check we're still passing).
+I know of no reason it shouldn't work with Ruby 1.8.7 or 1.9.2 - I just haven't got a test environment that works there yet!
+
+Usage
+=====
+Everything you need to make and run your own generators is defined in the `Succubus::Grammar` class.
+
+To get started:
+
+1. Require in Succubus:
+
+        require 'succubus'
+    
+2. Create a new instance of `Succubus::Grammar`, passing it a block:
+
+        require 'succubus'
+        grammar = Succubus::Grammar.new do
+          # See step 3 for what goes here
+        end
+        
+3. Call `add_rule` within the block. `add_rule` takes a symbol which names the rule, followed by one or more
+    strings. When the rule is invoked during grammar execution, exactly one of the strings will be chosen and
+    included in the result text. Text in each string is treated literally, except for instances of `<foo>`, which
+    instead paste in the result of invoking the rule `:foo`. Rules can be nested as far as you like!
+    
+        require 'succubus'
+        grammar = Succubus::Grammar.new do
+          add_rule :silly_name, "<title> <adjective><noun>"
+          add_rule :title, "Mr.", "Mrs.", "Professor", "Little Miss"
+          add_rule :adjective "<smelladj>", "<colour>", "Smarty"
+          add_rule :smelladj, "Smelly", "Poopy", "Floral"
+          add_rule :colour, "Green", "Purple"
+          add_rule :noun, "pants", "brain", "banana", "nose"
+        end
+        
+4. Call `execute(<rule>)` on your grammar, where `<rule>` is the symbol naming the top-level rule you want to invoke:
+
+        require 'succubus'
+        grammar = Succubus::Grammar.new do
+          add_rule :silly_name, "<title> <adjective><noun>"
+          add_rule :title, "Mr.", "Mrs.", "Professor", "Little Miss"
+          add_rule :adjective, "<smelladj>", "<colour>", "Smarty"
+          add_rule :smelladj, "Smelly", "Poopy", "Floral"
+          add_rule :colour, "Green", "Purple"
+          add_rule :noun, "pants", "brain", "banana", "nose"
+        end
+        
+        puts grammar.execute(:silly_name)
+        # Professor Purplepants
+        
+About that name...?
+===================
+Oh, why **Succubus**? Well, Backus-Naur is usually used to describe or verify legal sentences; 
+what you have here is something that uses Backup-Naur to _generate_ sentences. Which is kinda backwards. 
+"Backus", backwards, is "Sukcab"; it's just a short hop from there to Succubus.
+
+I did consider "Bacchus" - a sort of drunken Backus - but the gem name was taken.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb', 'spec/**/*_spec.rb']
+  t.warning = true
+end
+
+task :default => :test

data/lib/succubus.rb

@@ -0,0 +1,77 @@
+module Succubus
+  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
+
+    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
+    end
+  end
+  
+  class Generator
+    attr_reader :result
+    attr_reader :errors
+    
+    def initialize(rules)
+      @result = ""
+      @rules = rules
+      @errors = []
+    end
+    
+    def run(rule)
+      @result = invoke(rule)
+    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
+    end
+  end
+end

data/lib/succubus/version.rb

@@ -0,0 +1,3 @@
+module Succubus
+  VERSION = "0.0.0"
+end

data/spec/grammar_spec.rb

@@ -0,0 +1,91 @@
+require 'minitest/autorun'
+require File.dirname(__FILE__) + '/../test/support/fixed_random'
+require 'succubus'
+
+describe Succubus::Grammar do
+  describe "creating grammar" do
+    it "should accept valid grammar" do
+      Succubus::Grammar.new do
+        add_rule :base, "I have a <colour> <pet>"
+        add_rule :colour, "black", "white"
+        add_rule :pet, "cat", "dog"
+      end
+    end
+    
+    it "should reject invalid grammar" do
+      proc do
+        Succubus::Grammar.new do
+          add_rule :base, "I have a <colour> <pet>"
+          add_rule :colour, "black", "white"
+          add_rule :colour, "cat", "dog"
+        end
+      end.must_raise Succubus::ParseError
+    end
+  end
+  
+  describe "trivial grammar" do
+    before do
+      @grammar = Succubus::Grammar.new do
+        add_rule :base, "Just a single fixed string"
+      end
+    end
+    
+    it "should always produce the fixed string" do
+      1000.times { @grammar.execute(:base).must_equal "Just a single fixed string" }
+    end
+  end
+  
+  describe "simple grammar" do
+    before do
+      @grammar = Succubus::Grammar.new do
+        add_rule :base, "I have a <colour> <pet>", "<pet>s look best in <colour>"
+        add_rule :colour, "black", "white"
+        add_rule :pet, "cat", "dog"
+        add_rule :unreachable, "No-one likes animals anyway"
+      end
+    end
+    
+    it "should always produce a valid string" do
+      1000.times { @grammar.execute(:base).must_match(/(I have a (black|white) (cat|dog))|((cat|dog)s look best in (black|white))/) }
+    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"
+      
+      @grammar.execute(:base).must_equal "cats look best in black"
+      
+      samples_must_be_used
+    end
+  end
+  
+  describe "failure cases" do
+    it "should fail to parse duplicate rules" do
+      bad_parse = proc do
+        Succubus::Grammar.new do
+          add_rule :base, "I have a <colour> <pet>"
+          add_rule :colour, "black", "white"
+          add_rule :colour, "cat", "dog"
+          add_rule :base, "are belong to us"
+        end
+      end
+      
+      ex = bad_parse.must_raise Succubus::ParseError
+      ex.errors.must_have_same_elements_as ["Duplicate rule definition: colour", "Duplicate rule definition: base"]
+    end
+    
+    it "should fail to execute when rules are missing" do
+      grammar = Succubus::Grammar.new do
+        add_rule :base, "I have a <size> <colour> <pet>"
+        add_rule :colour, "black", "white"
+      end
+      
+      expect_sample %w<black white>, "black"
+      
+      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.partial.must_equal "I have a !!size!! black !!pet!!"
+    end
+  end
+end

data/test/support/fixed_random.rb

@@ -0,0 +1,40 @@
+require File.dirname(__FILE__) + '/subset_asserts'
+
+module MiniTest::Assertions
+  @@queued_samples = []
+  
+  def self.queued_samples; @@queued_samples; end
+  def self.next_sample; @@queued_samples.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}
+  end
+  
+  def samples_must_be_used
+    assert_empty @@queued_samples, "Expected to have used all queued samples: #{@@queued_samples.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
+      else
+        if n
+          sample_without_predefined_values(n, &block)
+        else
+          sample_without_predefined_values(&block)
+        end
+      end
+    end
+    alias_method :sample_without_predefined_values, :sample
+    alias_method :sample, :sample_with_predefined_values
+    
+  end
+end

data/test/support/subset_asserts.rb

@@ -0,0 +1,49 @@
+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

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: succubus
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Chris Howlett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+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"
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/succubus/version.rb
+- lib/succubus.rb
+- Rakefile
+- README.md
+- test/support/fixed_random.rb
+- test/support/subset_asserts.rb
+- spec/grammar_spec.rb
+homepage: https://github.com/asilano/succubus
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+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