pushdown 0.1.0.pre.20210714190141 → 0.4.0

data/spec/pushdown/spec_helpers_spec.rb

@@ -0,0 +1,504 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative '../spec_helper'
+
+require 'pushdown/spec_helpers'
+
+
+RSpec.describe( Pushdown::SpecHelpers ) do
+
+	include Pushdown::SpecHelpers
+
+	#
+	# Expectation-failure Matchers (stolen from rspec-expectations)
+	# See the README for licensing information.
+	#
+
+	def fail
+		raise_error( RSpec::Expectations::ExpectationNotMetError )
+	end
+
+	def fail_with( message )
+		raise_error( RSpec::Expectations::ExpectationNotMetError, message )
+	end
+
+	def fail_matching( message )
+		if String === message
+			regexp = /#{Regexp.escape(message)}/
+		else
+			regexp = message
+		end
+		raise_error( RSpec::Expectations::ExpectationNotMetError, regexp )
+	end
+
+	def fail_including( *messages )
+		raise_error do |err|
+			expect( err ).to be_a( RSpec::Expectations::ExpectationNotMetError )
+			expect( err.message ).to include( *messages )
+		end
+	end
+
+	def dedent( string )
+		return string.gsub( /^\t+/, '' ).chomp
+	end
+
+
+	let( :state_class ) do
+		subclass = Class.new( Pushdown::State )
+	end
+
+	let( :seeking_state_class ) do
+		subclass = Class.new( Pushdown::State )
+		subclass.singleton_class.attr_accessor( :name )
+		subclass.name = 'Acme::State::Seeking'
+		return subclass
+	end
+
+
+
+	describe "transition matcher" do
+
+		it "passes if a Pushdown::Transition is returned" do
+			state_class.attr_accessor( :seeking_state_class )
+			state_class.define_method( :update ) do |*|
+				return Pushdown::Transition.create( :push, :change, self.seeking_state_class )
+			end
+
+			state = state_class.new
+			state.seeking_state_class = seeking_state_class # inject the "seeking" state class
+
+			expect {
+				expect( state ).to transition
+			}.to_not raise_error
+		end
+
+
+		it "passes if a Symbol that maps to a declared transition is returned" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :update ) do |*|
+				return :change
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition
+			}.to_not raise_error
+		end
+
+
+		it "fails if a Symbol that does not map to a declared transition is returned" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :update ) do |*|
+				return :something_else
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition
+			}.to fail_matching( /unmapped symbol/i )
+		end
+
+
+		it "fails if something other than a Transition or Symbol is returned" do
+			state_class.transition_push( :change, :other )
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition
+			}.to fail_matching( /expected to transition.*it did not/i )
+		end
+
+	end
+
+
+	describe "transition.via mutator" do
+
+		it "passes if the state returns a Symbol that maps to the specified kind of transition" do
+			state_class.transition_push( :seek, :seeking )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :push )
+			}.to_not raise_error
+		end
+
+
+		it "passes if the state returns a Pushdown::Transition of the correct type" do
+			state_class.attr_accessor( :seeking_state_class )
+			state_class.define_method( :update ) do |*|
+				return Pushdown::Transition.create( :push, :seek, self.seeking_state_class )
+			end
+
+			state = state_class.new
+			state.seeking_state_class = seeking_state_class # inject the "seeking" state class
+
+			expect {
+				expect( state ).to transition.via( :push )
+			}.to_not raise_error
+		end
+
+
+		it "fails with a detailed failure message if the state doesn't transition" do
+			state_class.transition_push( :seek, :seeking )
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :push )
+			}.to fail_matching( /expected to transition via push.*returned: nil/i )
+		end
+
+
+		it "fails if the state returns a different kind of Pushdown::Transition" do
+			state_class.define_method( :update ) do |*|
+				return Pushdown::Transition.create( :pop, :restart )
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :push )
+			}.to fail_matching( /transition via push.*pop/i )
+		end
+
+
+		it "fails if the state terutns a Symbol that maps to the wrong kind of transition" do
+			state_class.transition_pop( :seek )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :push )
+			}.to fail_matching( /transition via push.*it returned a pop/i )
+		end
+
+	end
+
+
+	describe "transition.to mutator" do
+
+		it "passes if the state returns a Symbol that maps to a transition to the specified state" do
+			state_class.transition_push( :seek, :seeking )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.to( :seeking )
+			}.to_not raise_error
+		end
+
+
+		it "passes if the state returns a Pushdown::Transition with the correct target state" do
+			state_class.attr_accessor( :seeking_state_class )
+			state_class.define_method( :update ) do |*|
+				return Pushdown::Transition.create( :push, :seek, self.seeking_state_class )
+			end
+
+			state = state_class.new
+			state.seeking_state_class = seeking_state_class # inject the "seeking" state class
+
+			expect {
+				expect( state ).to transition.to( :seeking )
+			}.to_not raise_error
+		end
+
+
+		it "fails if the state returns a Symbol that maps to a transition to a different state" do
+			state_class.transition_push( :seek, :seeking )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.to( :broadcasting )
+			}.to fail_matching( /broadcasting.*seeking/i )
+		end
+
+
+		it "fails with a detailed failure message if the state doesn't transition" do
+			state_class.transition_push( :seek, :seeking )
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.to( :seeking )
+			}.to fail_matching( /to seeking.*returned: nil/i )
+		end
+
+
+		it "fails if a Pushdown::Transition with a different target state is returned" do
+			state_class.attr_accessor( :seeking_state_class )
+			state_class.define_method( :update ) do |*|
+				return Pushdown::Transition.create( :push, :seek, self.seeking_state_class )
+			end
+
+			state = state_class.new
+			state.seeking_state_class = seeking_state_class # inject the "seeking" state class
+
+			expect {
+				expect( state ).to transition.to( :other )
+			}.to fail_matching( /other.*seeking/i )
+		end
+
+	end
+
+
+	describe "composed matcher" do
+
+		it "passes if both .to and .via are specified and match" do
+			state_class.transition_push( :seek, :seeking )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :push ).to( :seeking )
+			}.to_not raise_error
+		end
+
+
+		it "fails if both .to and .via are specified and .to doesn't match" do
+			state_class.transition_push( :seek, :broadcasting )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :push ).to( :seeking )
+			}.to fail_matching( /seeking.*broadcasting/i )
+		end
+
+
+		it "fails if both .to and .via are specified and .via doesn't match" do
+			state_class.transition_push( :seek, :broadcasting )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :switch ).to( :broadcasting )
+			}.to fail_matching( /switch.*push/i )
+		end
+
+
+		it "fails if both .to and .via are specified and neither match" do
+			state_class.transition_push( :seek, :broadcasting )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.via( :switch ).to( :seeking )
+			}.to fail_matching( /switch.*seeking.*push.*broadcasting/i )
+		end
+
+	end
+
+
+	describe "operation mutators" do
+
+		it "allows the #update operation to be explicitly specified" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :update ) do |*|
+				return :change
+			end
+			state_class.define_method( :on_event ) do |*|
+				return nil
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.on_update
+			}.to_not raise_error
+		end
+
+
+		it "allows the #on_event operation to be explicitly specified" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :on_event ) do |*|
+				return :change
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.on_an_event( :foo )
+			}.to_not raise_error
+		end
+
+
+		it "supports giving additional arguments to pass the #on_event operation" do
+			state_class.transition_push( :change, :other )
+
+			state = state_class.new
+			expect( state ).to receive( :on_event ).with( :foo, 1, "another arg" ).
+				and_return( :change )
+
+			expect {
+				expect( state ).to transition.on_an_event( :foo, 1, "another arg" )
+			}.to_not raise_error
+		end
+
+
+		it "adds the callback to the description if on_update is specified" do
+			state_class.transition_push( :change, :other )
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.on_update
+			}.to fail_matching( /transition when #update is called/i )
+		end
+
+
+		it "adds the callback to the description if on_an_event is specified" do
+			state_class.transition_push( :change, :other )
+
+			state = state_class.new
+
+			expect {
+				expect( state ).to transition.on_an_event( :foo )
+			}.to fail_matching( /transition when #on_event is called with :foo/i )
+		end
+
+
+		it "handles multiple callback arguments on failures" do
+			state_class.transition_push( :change, :other )
+
+			state = state_class.new
+			allow( state ).to receive( :on_event ).with( :foo, 18, "nebraska" ).
+				and_return( nil )
+
+			expect {
+				expect( state ).to transition.on_an_event( :foo, 18, "nebraska" )
+			}.to fail_matching( /#on_event is called with :foo, 18, "nebraska"/i )
+		end
+
+	end
+
+	describe "negated matcher" do
+
+		it "succeeds if a Symbol that does not map to a declared transition is returned" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :update ) do |*|
+				return :something_else
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).not_to transition
+			}.to_not raise_error
+		end
+
+
+		it "succeeds if something other than a Transition or Symbol is returned" do
+			state_class.transition_push( :change, :other )
+
+			state = state_class.new
+
+			expect {
+				expect( state ).not_to transition
+			}.to_not raise_error
+		end
+
+
+		it "succeeds if a specific transition is given, but a different one is returned" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :update ) do |*|
+				return :change
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).not_to transition.via( :switch )
+			}.to_not raise_error
+		end
+
+
+		it "succeeds if a target state is given, but a different one is returned" do
+			state_class.transition_push( :change, :broadcasting )
+			state_class.define_method( :update ) do |*|
+				return :change
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).not_to transition.via( :push ).to( :seeking )
+			}.to_not raise_error
+		end
+
+
+		it "fails if a Pushdown::Transition is returned" do
+			state_class.attr_accessor( :seeking_state_class )
+			state_class.define_method( :update ) do |*|
+				return Pushdown::Transition.create( :push, :change, self.seeking_state_class )
+			end
+
+			state = state_class.new
+			state.seeking_state_class = seeking_state_class # inject the "seeking" state class
+
+			expect {
+				expect( state ).not_to transition
+			}.to fail_matching( /not to transition, but it did/i )
+		end
+
+
+		it "fails if a Symbol that maps to a declared transition is returned" do
+			state_class.transition_push( :change, :other )
+			state_class.define_method( :update ) do |*|
+				return :change
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).not_to transition
+			}.to fail_matching( /not to transition, but it did/i )
+		end
+
+
+		it "fails if a type and state are specified and they describe the returned transition" do
+			state_class.transition_push( :seek, :seeking )
+			state_class.define_method( :update ) do |*|
+				return :seek
+			end
+
+			state = state_class.new
+
+			expect {
+				expect( state ).not_to transition.via( :push ).to( :seeking )
+			}.to fail_matching( /not.*via push to seeking, but it did/i )
+		end
+
+	end
+
+
+end

data/spec/pushdown/state_spec.rb

@@ -0,0 +1,154 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative '../spec_helper'
+
+# Let autoloads decide the order
+require 'pushdown'
+
+
+RSpec.describe( Pushdown::State ) do
+
+	let( :state_data ) { {} }
+	let( :subclass ) do
+		Class.new( described_class )
+	end
+
+	let( :starting_state_class ) do
+		Class.new( subclass )
+	end
+
+	let( :automaton_class ) do
+		extended_class = Class.new
+		extended_class.extend( Pushdown::Automaton )
+		extended_class.const_set( :Starting, starting_state_class )
+		extended_class.pushdown_state( :state, initial_state: :starting )
+
+		return extended_class
+	end
+
+
+	it "is an abstract class" do
+		expect { described_class.new }.to raise_error( NoMethodError, /\bnew\b/ )
+	end
+
+
+	it "knows what the name of its type is" do
+		starting_state_class.singleton_class.attr_accessor :name
+		starting_state_class.name = 'Acme::State::Starting'
+
+		state = starting_state_class.new
+
+		expect( state.type_name ).to eq( :starting )
+	end
+
+
+	it "handles anonymous classes for #type_name" do
+		transition = starting_state_class.new
+
+		expect( transition.type_name ).to eq( :anonymous )
+	end
+
+
+
+	describe "transition callbacks" do
+
+		it "has a default (no-op) callback for when it is added to the stack" do
+			instance = subclass.new
+			expect( instance.on_start ).to be_nil
+		end
+
+
+		it "has a default (no-op) callback for when it is removed from the stack" do
+			instance = subclass.new
+			expect( instance.on_stop ).to be_nil
+		end
+
+
+		it "has a default (no-op) callback for when it is pushed down on the stack" do
+			instance = subclass.new
+			expect( instance.on_pause ).to be_nil
+		end
+
+
+		it "has a default (no-op) callback for when the stack is popped and it becomes current again" do
+			instance = subclass.new
+			expect( instance.on_resume ).to be_nil
+		end
+
+	end
+
+
+	describe "event handlers" do
+
+		it "has a default (no-op) event callback" do
+			instance = subclass.new
+			expect( instance.on_event(:an_event) ).to be_nil
+		end
+
+	end
+
+
+	describe "interval event handlers" do
+
+		it "has a default (no-op) interval callback for when it is current" do
+			instance = subclass.new
+			expect( instance.update ).to be_nil
+		end
+
+
+		it "has a default (no-op) interval callback for when it is on the stack" do
+			instance = subclass.new
+			expect( instance.shadow_update ).to be_nil
+		end
+
+	end
+
+
+
+	describe "transition declaration" do
+
+		it "can declare a push transition" do
+			subclass.transition_push( :start, :starting )
+			expect( subclass.transitions[:start] ).to eq([ :push, :starting ])
+		end
+
+
+		it "can declare a pop transition" do
+			subclass.transition_pop( :undo )
+			expect( subclass.transitions[:undo] ).to eq([ :pop ])
+		end
+
+	end
+
+
+	describe "transition creation" do
+
+		it "can create a transition it has declared" do
+			subclass.transition_push( :start, :starting )
+			instance = subclass.new
+
+			automaton = automaton_class.new
+
+			result = instance.transition( :start, automaton, :state )
+			expect( result ).to be_a( Pushdown::Transition::Push )
+			expect( result.name ).to eq( :start )
+			expect( result.data ).to be_nil
+		end
+
+
+		it "can create a transition it has declared that doesn't take a state class" do
+			subclass.transition_pop( :quit )
+			instance = subclass.new
+
+			automaton = automaton_class.new
+
+			result = instance.transition( :quit, automaton, :state )
+			expect( result ).to be_a( Pushdown::Transition::Pop )
+			expect( result.name ).to eq( :quit )
+		end
+
+	end
+
+end
+

data/spec/pushdown/transition/pop_spec.rb

@@ -0,0 +1,65 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative '../../spec_helper'
+
+require 'pushdown/transition/pop'
+require 'pushdown/state'
+
+
+RSpec.describe( Pushdown::Transition::Pop ) do
+
+	let( :state_class ) do
+		Class.new( Pushdown::State )
+	end
+
+	let( :state_a ) { state_class.new }
+	let( :state_b ) { state_class.new }
+	let( :state_c ) { state_class.new }
+
+	let( :stack ) do
+		return [ state_a, state_b, state_c ]
+	end
+
+
+	it "pops the last state from the stack when applied" do
+		stack = [ state_a, state_b, state_c ]
+		transition = described_class.new( :pop_test )
+
+		new_stack = transition.apply( stack )
+
+		expect( new_stack ).to eq([ state_a, state_b ])
+	end
+
+
+	it "passes state data through the transition callbacks" do
+		transition = described_class.new( :pop_test )
+
+		expect( state_c ).to receive( :on_stop ).with( no_args ).once.ordered
+		expect( state_b ).to receive( :on_resume ).with( no_args ).once.ordered
+
+		transition.apply( stack )
+	end
+
+
+	it "errors if applied to a stack that has only one state" do
+		stack = [ state_a ]
+		transition = described_class.new( :pop_test )
+
+		expect {
+			transition.apply( stack )
+		}.to raise_error( Pushdown::TransitionError, /can't pop/i )
+	end
+
+
+	it "errors if applied to an empty stack" do
+		stack = []
+		transition = described_class.new( :pop_test )
+
+		expect {
+			transition.apply( stack )
+		}.to raise_error( Pushdown::TransitionError, /can't pop/i )
+	end
+
+end
+