pushdown 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf2b58a9924b03dc5e15d6c0fca42ebac8988fcdbf9e0b02f1ab3b1e2365de56
-  data.tar.gz: 7117970f25e2e310be68a2269dd77216cae26442d298e73dd1bb580a29752914
+  metadata.gz: de5a87ff7d9744a6c71e977a4d5e2fbe03be08efc393d5fc8c84b7a9f4f720c2
+  data.tar.gz: 6a94eca59001d1640a5676e9a135b56690c6e20f2ec75e49740b68b036005870
 SHA512:
-  metadata.gz: 9b41ba0c24de3f75fb91fbc02e3b20afc5d2d4a8aac8f43d9ae4237e354fcab2611d48eb885f2bef542d9d9da5bbb5c6686f98c78ea26287e84e9c7fb8242011
-  data.tar.gz: 1d84bef861cf31696148031a01a13fd04ef5a76d9bd45733f3a0043976e62a97aa56836b3c7bdcaf54d45bf798df9abe4c59b619ebd406f7d457442340d1ed5c
+  metadata.gz: 677caf47c2cebd2ac9023a72d16e99881b97be5cacd439aae7f472bdefb1d1e7d7ee75151211988f1b354bc1f9339d3ab4483dce83cec24740579562e48ee41c
+  data.tar.gz: e32e468403256a51c4683bff1bbf5f332461ed5fc22c43369509b8e241e4f0a102ba105cbfa925474b55e4420dfc8e3ff49af42a8abdd793b7e046e2f1810f69

data/History.md

@@ -2,6 +2,14 @@
 
 ---
 
+## v0.2.0 [2021-08-31] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Move responsibility for creating transitions into State.
+- Add spec helpers with a transition matcher.
+- Add missing event handler method to State
+
 
 ## v0.1.0 [2021-08-27] Michael Granger <ged@faeriemud.org>
 

data/README.md

@@ -49,9 +49,42 @@ and generate the API documentation.
 
 * Michael Granger <ged@faeriemud.org>
 
+While Pushdown does not contain any [Amethyst Game Engine][amethyst] source code, it does borrow heavily from its ideas and nomenclature. Many thanks to the Amethyst team for the inspiration.
+
+Thanks also to Alyssa Verkade for the initial idea.
+
 
 ## License
 
+This gem includes code from the rspec-expectations gem, used under the
+terms of the MIT License:
+
+    Copyright (c) 2012 David Chelimsky, Myron Marston
+    Copyright (c) 2006 David Chelimsky, The RSpec Development Team
+    Copyright (c) 2005 Steven Baker
+    
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+    
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+    
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+Pushdown itself is:
+
 Copyright (c) 2019-2021, Michael Granger
 All rights reserved.
 
@@ -80,6 +113,6 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-
+[amethyst]: https://amethyst.rs/
 [amethyst-state-manager]: https://book.amethyst.rs/stable/concepts/state.html#state-manager
 

data/lib/pushdown/automaton.rb

@@ -29,6 +29,57 @@ module Pushdown::Automaton
 	end
 
 
+	# A mixin to add instance methods for setting up pushdown states.
+	module InstanceMethods
+
+		### Overload the initializer to push the initial state object for any pushdown
+		### states.
+		def initialize( * )
+			super if defined?( super )
+
+			self.class.pushdown_states.each do |name, config|
+				self.log.debug "Pushing initial %s" % [ name ]
+
+				state_class = self.class.public_send( "initial_#{name}" ) or
+					raise "unset initial_%s while pushing initial state" % [ name ]
+
+				data = if self.respond_to?( "initial_#{name}_data" )
+						self.public_send( "initial_#{name}_data" )
+					else
+						nil
+					end
+
+				self.log.info "Pushing an instance of %p as the initial state." % [ state_class ]
+				transition = Pushdown::Transition.create( :push, :initial, state_class, data )
+				self.log.debug " applying %p to an new empty stack" % [ transition ]
+				stack = transition.apply( [] )
+				self.instance_variable_set( "@#{name}_stack", stack )
+			end
+		end
+
+
+		### The body of the event handler, called by the #handle_{name}_event.
+		def handle_pushdown_result( stack, result, name )
+			if result.is_a?( Symbol )
+				current_state = stack.last
+				result = current_state.transition( result, self, name )
+			end
+
+			if result.is_a?( Pushdown::Transition )
+				new_stack = result.apply( stack )
+				stack.replace( new_stack )
+			end
+
+			return result
+		end
+
+
+		# :TODO: Methods that call #update, #on_event, etc. and then manage the
+		# application of any transition(s) that are returned.
+
+	end # module InstanceMethods
+
+
 	### Generate the pushdown API methods for the pushdown automaton with the given
 	### +name+ and install them in the extending +object+.
 	def self::install_state_methods( name, object )
@@ -127,65 +178,6 @@ module Pushdown::Automaton
 	end
 
 
-	# A mixin to add instance methods for setting up pushdown states.
-	module InstanceMethods
-
-		### Overload the initializer to push the initial state object for any pushdown
-		### states.
-		def initialize( * )
-			super if defined?( super )
-
-			self.class.pushdown_states.each do |name, config|
-				self.log.debug "Pushing initial %s" % [ name ]
-
-				state_class = self.class.public_send( "initial_#{name}" ) or
-					raise "unset initial_%s while pushing initial state" % [ name ]
-
-				data = if self.respond_to?( "initial_#{name}_data" )
-						self.public_send( "initial_#{name}_data" )
-					else
-						nil
-					end
-
-				transition = Pushdown::Transition.create( :push, :initial, state_class, data )
-				stack = transition.apply( [] )
-				self.instance_variable_set( "@#{name}_stack", stack )
-			end
-		end
-
-
-		### The body of the event handler, called by the #handle_{name}_event.
-		def handle_pushdown_result( stack, result, name )
-			if result.is_a?( Symbol )
-				transition_name = result
-				current_state = stack.last
-				self.log.debug "Looking up the %p transition for %p" % [ result, current_state ]
-				transition_type, state_class_name = current_state.class.transitions[ transition_name ]
-				raise "no such transition %p for %s" % [ transition_name, name ] unless transition_type
-
-				result = if state_class_name
-						state_class = self.class.pushdown_state_class( name, state_class_name )
-						Pushdown::Transition.create( transition_type, transition_name, state_class )
-					else
-						Pushdown::Transition.create( transition_type, transition_name )
-					end
-			end
-
-			if result.is_a?( Pushdown::Transition )
-				new_stack = result.apply( stack )
-				stack.replace( new_stack )
-			end
-
-			return result
-		end
-
-
-		# :TODO: Methods that call #update, #on_event, etc. and then manage the
-		# application of any transition(s) that are returned.
-
-	end # module InstanceMethods
-
-
 	### Declare a attribute +name+ which is a pushdown state.
 	def pushdown_state( name, initial_state:, states: nil )
 		@pushdown_states[ name ] = { initial_state: initial_state, states: states }

data/lib/pushdown/spec_helpers.rb

@@ -0,0 +1,263 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'rspec'
+require 'rspec/matchers'
+
+require 'loggability'
+
+require 'pushdown' unless defined?( Pushdown )
+
+
+module Pushdown::SpecHelpers
+
+
+	# RSpec matcher for matching transitions of Pushdown::States
+	class StateTransitionMatcher
+		extend Loggability
+		include RSpec::Matchers
+
+		DEFAULT_CALLBACK = [ :update ]
+
+		log_to :pushdown
+
+
+		### Create a new matcher that expects a transition to occur.
+		def initialize
+			@expected_type = nil
+			@target_state = nil
+			@callback = nil
+			@additional_expectations = []
+			@state = nil
+			@result = nil
+			@failure_description = nil
+		end
+
+
+		attr_reader :expected_type,
+			:target_state,
+			:callback,
+			:additional_expectations,
+			:state,
+			:result,
+			:failure_description
+
+
+		### RSpec matcher API -- returns +true+ if all expectations are met after calling
+		### #update on the specified +state+.
+		def matches?( state )
+			@state = state
+
+			return self.update_ran_without_error? &&
+				self.update_returned_transition? &&
+				self.correct_transition_type? &&
+				self.correct_target_state? &&
+				self.matches_additional_expectations?
+		end
+
+
+		### RSpec matcher API -- return a message describing an expectation failure.
+		def failure_message
+			return "%p: %s" % [ self.state, self.describe_failure ]
+		end
+
+
+		### RSpec matcher API -- return a message describing an expectation being met
+		### when the matcher was used in a negated context.
+		def failure_message_when_negated
+			return "%p: %s" % [ self.state, self.describe_negated_failure ]
+		end
+
+
+		#
+		# Mutators
+		#
+
+		### Add an additional expectation that the transition that occurs be of the specified
+		### +transition_type+.
+		def via_transition_type( transition_type )
+			@expected_type = transition_type
+			return self
+		end
+		alias_method :via, :via_transition_type
+
+
+		### Add an additional expectation that the state that is transitioned to be of
+		### the given +state_name+. This only applies to transitions that take a target
+		### state type. Expecting a particular state_name in transitions which do not take
+		### a state is undefined behavior.
+		def to_state( state_name )
+			@target_state = state_name
+			return self
+		end
+		alias_method :to, :to_state
+
+
+		### Specify that the operation that should cause the transition is the #update callback.
+		### This is the default.
+		def on_update
+			raise ScriptError, "can't specify more than one callback" if self.callback
+			@callback = [ :update ]
+			return self
+		end
+
+
+		### Specify that the operation that should cause the transition is the #on_event callback.
+		def on_an_event( event )
+			raise ScriptError, "can't specify more than one callback" if self.callback
+			@callback = [ :on_event, event ]
+			return self
+		end
+		alias_method :on_event, :on_an_event
+
+
+		#########
+		protected
+		#########
+
+		### Call the state's update callback and record the result, then return +true+
+		### if no exception was raised.
+		def update_ran_without_error?
+			operation = self.callback || DEFAULT_CALLBACK
+
+			@result = begin
+					self.state.public_send( *operation )
+				rescue => err
+					err
+				end
+
+			return !@result.is_a?( Exception )
+		end
+
+
+		### Returns +true+ if the result of calling #update was a Transition or a Symbol
+		### that corresponds with a valid transition.
+		def update_returned_transition?
+			case self.result
+			when Pushdown::Transition
+				return true
+			when Symbol
+				return self.state.class.transitions.include?( self.result )
+			else
+				return false
+			end
+		end
+
+
+		### Returns +true+ if a transition type was specified and the transition which
+		### occurred was of that type.
+		def correct_transition_type?
+			type = self.expected_type or return true
+
+			case self.result
+			when Pushdown::Transition
+				self.result.type_name == type
+			when Symbol
+				self.state.class.transitions[ self.result ].first == type
+			else
+				raise "unexpected transition result type %p" % [ self.result ]
+			end
+		end
+
+
+		### Returns +true+ if a target state was specified and the transition which
+		### occurred was to that state.
+		def correct_target_state?
+			state_name = self.target_state or return true
+
+			case self.result
+			when Pushdown::Transition
+				return self.result.respond_to?( :state_class ) &&
+					self.result.state_class.type_name == state_name
+			when Symbol
+				self.state.class.transitions[ self.result ][ 1 ] == state_name
+			end
+		end
+
+
+		### Build an appropriate failure messages for the matcher.
+		def describe_failure
+			desc = String.new( "expected to transition" )
+			desc << " via %s" % [ self.expected_type ] if self.expected_type
+			desc << " to %s" % [ self.target_state ] if self.target_state
+
+			if self.callback
+				methname, arg = self.callback
+				desc << " when #%s is called" % [ methname ]
+				desc << " with %p" % [ arg ] if arg
+			end
+
+			desc << ', but '
+
+			case self.result
+			when Exception
+				err = self.result
+				desc << "got %p: %s" % [ err.class, err.message ]
+			when Symbol
+				transition = self.state.class.transitions[ self.result ]
+
+				if transition
+					desc << "it returned a %s transition " % [ transition.first ]
+					desc << "to %s " % [ transition[1] ] if transition[1]
+					desc << " instead"
+				else
+					desc << "it returned an unmapped Symbol (%p)" % [ self.result ]
+				end
+			when Pushdown::Transition
+				desc << "it returned a %s transition" % [ self.result.type_name ]
+				desc << " to %s" % [ self.result.state_class.type_name ] if
+					self.result.respond_to?( :state_class )
+				desc << " instead"
+			else
+				desc << "it did not (returned: %p)" % [ self.result ]
+			end
+
+			return desc
+		end
+
+
+		### Build an appropriate failure message for the matcher.
+		def describe_negated_failure
+			desc = String.new( "expected not to transition" )
+			desc << " via %s" % [ self.expected_type ] if self.expected_type
+			desc << " to %s" % [ self.target_state ] if self.target_state
+
+			desc << ', but it did.'
+
+			return desc
+		end
+
+
+		### Return an Array of descriptions of the members that were expected to be included in the
+		### state body, if any were specified. If none were specified, returns an empty
+		### Array.
+		def describe_additional_expectations
+			return self.additional_expectations.map( &:description )
+		end
+
+
+		### Check that any additional matchers registered via the `.and` mutator also
+		### match the parsed state body.
+		def matches_additional_expectations?
+			return self.additional_expectations.all? do |matcher|
+				matcher.matches?( self.parsed_state_body ) or
+					fail_with( matcher.failure_message )
+			end
+		end
+
+	end # class HaveJSONBodyMatcher
+
+
+	###############
+	module_function
+	###############
+
+	### Set up an expectation that a transition or valid Symbol will be returned.
+	def transition
+		return StateTransitionMatcher.new
+	end
+
+
+end # module Pushdown::SpecHelpers
+
+

data/lib/pushdown/state.rb

@@ -43,11 +43,20 @@ class Pushdown::State
 			self.transitions[ transition_name ] = [ type, *args ]
 		end
 
-		method_name = "transition_#{type}"
+		method_name = "transition_%s" % [ type ]
+		self.log.info "Setting up transition declaration method %p" % [ method_name ]
 		define_singleton_method( method_name, &meth )
 	end
 
 
+	### Return the transition's type as a lowercase Symbol, such as that specified
+	### in transition declarations.
+	def self::type_name
+		class_name = self.name or return :anonymous
+		return class_name.sub( /.*::/, '' ).downcase.to_sym
+	end
+
+
 	#
 	# Stack callbacks
 	#
@@ -78,10 +87,22 @@ class Pushdown::State
 
 
 	#
-	# State callbacks
+	# Event callbacks
+	#
+
+	### Event callback -- called by the automaton when its #on_<stackname>_event method
+	### is called. This method can return a Transition or a Symbol which maps to one.
+	def on_event( event )
+		return nil # no-op
+	end
+
+
+	#
+	# Interval callbacks
 	#
 
-	### State callback -- interval callback called when the state is the current one.
+	### State callback -- interval callback called when the state is the current
+	### one. This method can return a Transition or a Symbol which maps to one.
 	def update( *data )
 		return nil # no-op
 	end
@@ -98,6 +119,13 @@ class Pushdown::State
 	# Introspection/information
 	#
 
+	### Return the transition's type as a lowercase Symbol, such as that specified
+	### in transition declarations.
+	def type_name
+		return self.class.type_name
+	end
+
+
 	### Return a description of the State as an engine phrase.
 	def description
 		return "%#x" % [ self.class.object_id ] unless self.class.name
@@ -106,5 +134,23 @@ class Pushdown::State
 			gsub( /([a-z])([A-Z])/ ) { "#$1 #$2" }.downcase
 	end
 
+
+	### Create a new instance of Pushdown::Transition named +transition_name+ that
+	### has been declared using one of the Transition Declaration methods.
+	def transition( transition_name, automaton, stack_name )
+		self.log.debug "Looking up the %p transition for %p via %p" %
+			[ transition_name, self, automaton ]
+
+		transition_type, state_class_name = self.class.transitions[ transition_name ]
+		raise "no such transition %p for %p" % [ transition_name, self.class ] unless transition_type
+
+		if state_class_name
+			state_class = automaton.class.pushdown_state_class( stack_name, state_class_name )
+			return Pushdown::Transition.create( transition_type, transition_name, state_class )
+		else
+			return Pushdown::Transition.create( transition_type, transition_name )
+		end
+	end
+
 end # class Pushdown::State
 

data/lib/pushdown/transition.rb

@@ -5,26 +5,8 @@ require 'loggability'
 require 'pluggability'
 
 require 'pushdown' unless defined?( Pushdown )
+require 'pushdown/state'
 
-# pub enum Trans<T, E> {
-#     /// Continue as normal.
-#     None,
-#     /// Remove the active state and resume the next state on the stack or stop
-#     /// if there are none.
-#     Pop,
-#     /// Pause the active state and push a new state onto the stack.
-#     Push(Box<dyn State<T, E>>),
-#     /// Remove the current state on the stack and insert a different one.
-#     Switch(Box<dyn State<T, E>>),
-#     /// Remove all states on the stack and insert a different one.
-#     Replace(Box<dyn State<T, E>>),
-#     /// Remove all states on the stack and insert new stack.
-#     NewStack(Vec<Box<dyn State<T, E>>>),
-#     /// Execute a series of Trans's.
-#     Sequence(Vec<Trans<T, E>>),
-#     /// Stop and remove all states and shut down the engine.
-#     Quit,
-# }
 
 # A transition in a Pushdown automaton
 class Pushdown::Transition
@@ -35,7 +17,7 @@ class Pushdown::Transition
 	log_to :pushdown
 
 	# Pluggability API -- concrete types live in lib/pushdown/transition/
-	plugin_prefixes 'pushdown/transition/'
+	plugin_prefixes 'pushdown/transition'
 	plugin_exclusions 'spec/**/*'
 
 
@@ -53,7 +35,7 @@ class Pushdown::Transition
 	end
 
 
-	### Create a new Transition with the given +name+. If +data+ is specified, it will be passed 
+	### Create a new Transition with the given +name+. If +data+ is specified, it will be passed
 	### through the transition callbacks on State (State#on_start, State#on_stop, State#on_pause,
 	### State#on_resume) as it is applied.
 	def initialize( name, data=nil )
@@ -75,11 +57,19 @@ class Pushdown::Transition
 	attr_accessor :data
 
 
-	### Return a state +stack+ after the transition has been applied. 
+	### Return a state +stack+ after the transition has been applied.
 	def apply( stack )
 		raise NotImplementedError, "%p doesn't implement required method #%p" %
 			[ self.class, __method__ ]
 	end
 
+
+	### Return the transition's type as a lowercase Symbol, such as that specified
+	### in transition declarations.
+	def type_name
+		class_name = self.class.name or return :anonymous
+		return class_name.sub( /.*::/, '' ).downcase.to_sym
+	end
+
 end # class Pushdown::Transition
 

data/lib/pushdown.rb

@@ -15,17 +15,18 @@ module Pushdown
 	extend Loggability
 
 	# Package version
-	VERSION = '0.1.0'
+	VERSION = '0.2.0'
 
 
 	# Loggability API -- create a logger for Pushdown classes and modules
 	log_as :pushdown
 
-	autoload :Transition, 'pushdown/transition'
-	autoload :State, 'pushdown/state'
-	autoload :Automaton, 'pushdown/automaton'
-
 end # module Pushdown
 
+require 'pushdown/transition'
+require 'pushdown/state'
+require 'pushdown/automaton'
+
 Pushdown::Transition.plugin_exclusions( '**/spec/pushdown/transition/**' )
 Pushdown::Transition.load_all
+

data/spec/pushdown/automaton_spec.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../spec_helper'
 

data/spec/pushdown/spec_helpers_spec.rb

@@ -0,0 +1,478 @@
+# -*- 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 "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
+
+	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

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../spec_helper'
 
@@ -14,7 +15,16 @@ RSpec.describe( Pushdown::State ) do
 	end
 
 	let( :starting_state_class ) do
-		Class.new( described_class )
+		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
 
 
@@ -23,7 +33,25 @@ RSpec.describe( Pushdown::State ) do
 	end
 
 
-	describe "event handlers" do
+	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
@@ -51,19 +79,29 @@ RSpec.describe( Pushdown::State ) do
 	end
 
 
-	describe "update handlers" do
+	describe "event handlers" do
 
-		it "has a default (no-op) interval callback for when it is on the stack" do
+		it "has a default (no-op) event callback" do
 			instance = subclass.new
-			expect( instance.shadow_update(state_data) ).to be_nil
+			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(state_data) ).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(state_data) ).to be_nil
+		end
+
 	end
 
 
@@ -84,5 +122,21 @@ RSpec.describe( Pushdown::State ) do
 	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
+
+	end
+
 end
 

data/spec/pushdown/transition/pop_spec.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../../spec_helper'
 

data/spec/pushdown/transition/push_spec.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../../spec_helper'
 

data/spec/pushdown/transition/replace_spec.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../../spec_helper'
 

data/spec/pushdown/transition/switch_spec.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../../spec_helper'
 

data/spec/pushdown/transition_spec.rb

@@ -1,4 +1,5 @@
-#!/usr/bin/env rspec -cfd
+# -*- ruby -*-
+# frozen_string_literal: true
 
 require_relative '../spec_helper'
 
@@ -68,6 +69,23 @@ RSpec.describe( Pushdown::Transition ) do
 			expect( result.last ).to be_a( state_class )
 		end
 
+
+		it "knows what the name of its type is" do
+			subclass.singleton_class.attr_accessor :name
+			subclass.name = 'Acme::Transition::Frobnicate'
+
+			transition = subclass.new( :rejigger, state_class )
+
+			expect( transition.type_name ).to eq( :frobnicate )
+		end
+
+
+		it "handles anonymous classes for #type_name" do
+			transition = subclass.new( :rejigger, state_class )
+
+			expect( transition.type_name ).to eq( :anonymous )
+		end
+
 	end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pushdown
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Granger
@@ -33,7 +33,7 @@ cert_chain:
   MCh97sQ/Z/MOusb5+QddBmB+k8EicXyGNl4b5L4XpL7fIQu+Y96TB3JEJlShxFD9
   k9FjI4d9EP54gS/4
   -----END CERTIFICATE-----
-date: 2021-08-27 00:00:00.000000000 Z
+date: 2021-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -105,6 +105,7 @@ files:
 - lib/pushdown.rb
 - lib/pushdown/automaton.rb
 - lib/pushdown/exceptions.rb
+- lib/pushdown/spec_helpers.rb
 - lib/pushdown/state.rb
 - lib/pushdown/transition.rb
 - lib/pushdown/transition/pop.rb
@@ -112,6 +113,7 @@ files:
 - lib/pushdown/transition/replace.rb
 - lib/pushdown/transition/switch.rb
 - spec/pushdown/automaton_spec.rb
+- spec/pushdown/spec_helpers_spec.rb
 - spec/pushdown/state_spec.rb
 - spec/pushdown/transition/pop_spec.rb
 - spec/pushdown/transition/push_spec.rb