pushdown 0.1.0.pre.20210714190141 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3aa15b901bc12dcc15430512e8ec06fdaa5bbc98afd222a62892fad5b1fa689
-  data.tar.gz: 5b4d53652f5a1d0df9c759d6b9226d4780c87cb4258d650295748e8ecd64ab01
+  metadata.gz: 07f7a5dfc7c5783cd2fe4e7e610467519ef85ed1a7ff857bce91c58805f6f457
+  data.tar.gz: 02a41fb1852f955d282834ea9ff397d98bb66681f3a7f38b26e13d00503a89dc
 SHA512:
-  metadata.gz: 5f3143596b9615ab3a538a2b5256fc43649b11ca1cf6a90fa33a616cee74c09d6ba39e4832ad417352fd15a1162a2698daca1aedcd069af4cf2d48b551dd1245
-  data.tar.gz: 7f1fd1112549fd7cf19c2a472678fbd5dc58d6d07178d7ce84d0a5d7b96293a3e272b691499624fd23de961aff1df50b742bdaeab640e4d0e4c065fa6771b5d7
+  metadata.gz: 537d7f75b6265b4a08b20b67d9f547a42b27514e18d46a7dc9d3bd0f2066ae8161424bf92f39d2c25ad8dca2762a3731deb368c259f26c65004e26244a388f54
+  data.tar.gz: b5398fee7bc5fe436f39c8ad760118fd6178baadf13362e85402b442fd609d10b5a5b6d73c2b04a49700ab30641be4d4d190d156e5622c0de9ffe19d9557b965

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+���� ��D
����u^DA9�k��;�"z�@�Ÿ?��HD���2u.�E3/w^�`�
+�R�d�p��WbɢzXC�`���UDJ-g��c˸�*OZ�yDPc���c��&���ב�������J8��Z�Un�M��	-�|K��G@B��n��fW��̊�1�B�����

data/History.md

@@ -1,4 +1,33 @@
-## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+# Release History for pushdown
+
+---
+## v0.4.0 [2021-09-21] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Report operator arguments in the spec matcher failure output.
+- Allow the State event callback to accept additional arguments.
+
+
+## v0.3.0 [2021-09-01] Michael Granger <ged@faeriemud.org>
+
+Change:
+
+- Rework how state data is passed around. Instead of passing it through the
+  transition callbacks, which proved to be a terrible idea, the States
+  themselves take an optional state argument to their constructor.
+
+
+## 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>
 
 Initial release.
 

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2019-2021, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+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.

data/README.md

@@ -31,27 +31,61 @@ It's still mostly experimental.
     $ gem install pushdown
 
 
-## Contributing
+## Development
 
-You can check out the current development source with Mercurial via its
-[project page](http://bitbucket.org/ged/pushdown). Or if you prefer
-Git, via [its Github mirror](https://github.com/ged/pushdown).
+You can check out the current source with Git via Gitlab:
+
+    $ hg clone http://hg.sr.ht/~ged/Pushdown
+    $ cd Pushdown
 
 After checking out the source, run:
 
-    $ rake newb
+    $ gem install -Ng
+    $ rake setup
 
-This task will install any missing dependencies, run the tests/specs,
-and generate the API documentation.
+This task will install dependencies, and do any other necessary setup for development.
 
 
 ## Author(s)
 
 * 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 +114,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

@@ -0,0 +1,228 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'pushdown' unless defined?( Pushdown )
+
+
+# A mixin that adds pushdown-automaton functionality to another module/class.
+module Pushdown::Automaton
+	extend Loggability
+
+	# Loggability API -- log to the pushdown logger
+	log_to :pushdown
+
+
+	### Extension callback -- add some stuff to extending objects.
+	def self::extended( object )
+		super
+
+		unless object.respond_to?( :log )
+			object.extend( Loggability )
+			object.log_to( :pushdown )
+		end
+
+		object.instance_variable_set( :@pushdown_states, {} )
+		object.singleton_class.attr_reader( :pushdown_states )
+		object.include( Pushdown::Automaton::InstanceMethods )
+	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 )
+		self.log.debug "Installing pushdown methods for %p in %p" % [ name, object ]
+		object.attr_reader( "#{name}_stack" )
+
+		# Relies on the above method having already been declared
+		state_method = self.generate_state_method( name, object )
+		object.define_method( name, &state_method )
+
+		event_method = self.generate_event_method( name, object )
+		object.define_method( "handle_#{name}_event", &event_method )
+
+		update_method = self.generate_update_method( name, object )
+		object.define_method( "update_#{name}", &update_method )
+
+		update_method = self.generate_shadow_update_method( name, object )
+		object.define_method( "shadow_update_#{name}", &update_method )
+
+		initial_state_method = self.generate_initial_state_method( name )
+		object.define_singleton_method( "initial_#{name}", &initial_state_method )
+	end
+
+
+	### Generate the method used to access the current state object.
+	def self::generate_state_method( name, object )
+		self.log.debug "Generating current state method for %p: %p" % [ object, name ]
+		stack_method = object.instance_method( "#{name}_stack" )
+		meth = lambda { stack_method.bind(self).call&.last }
+
+		return meth
+	end
+
+
+	### Generate the external event handler method for the pushdown state named +name+
+	### on the specified +object+.
+	def self::generate_event_method( name, object )
+		self.log.debug "Generating event method for %p: handle_%s_event" % [ object, name ]
+
+		stack_method = object.instance_method( "#{name}_stack" )
+		meth = lambda do |event, *args|
+			stack = stack_method.bind( self ).call
+			current_state = stack.last
+
+			result = current_state.on_event( event, *args )
+			return self.handle_pushdown_result( stack, result, name )
+		end
+	end
+
+
+	### Generate the timed update method for the active pushdown state named +name+
+	### on the specified +object+.
+	def self::generate_update_method( name, object )
+		self.log.debug "Generating update method for %p: update_%s" % [ object, name ]
+
+		stack_method = object.instance_method( "#{name}_stack" )
+		meth = lambda do |*args|
+			stack = stack_method.bind( self ).call
+			current_state = stack.last
+
+			result = current_state.update( *args )
+			return self.handle_pushdown_result( stack, result, name )
+		end
+	end
+
+
+	### Generate the timed update method for every pushdown state named +name+
+	### on the specified +object+.
+	def self::generate_shadow_update_method( name, object )
+		self.log.debug "Generating shadow update method for %p: shadow_update_%s" % [ object, name ]
+
+		stack_method = object.instance_method( "#{name}_stack" )
+		meth = lambda do |*args|
+			stack = stack_method.bind( self ).call
+			stack.each do |state|
+				state.shadow_update( *args )
+			end
+
+			# :TODO: Calling/return convention? Could do something like #flat_map the
+			# results? Or map to a hash keyed by state object? Is it useful enough to justify
+			# the object churn of a method that might potentionally be in a hot loop?
+			return nil
+		end
+	end
+
+
+	### Generate the method that returns the initial state class for a pushdown
+	### state named +name+.
+	def self::generate_initial_state_method( name )
+		self.log.debug "Generating initial state method for %p" % [ name ]
+		return lambda do
+			config = self.pushdown_states[ name ]
+			class_name = config[ :initial_state ]
+			return self.pushdown_state_class( name, class_name )
+		end
+	end
+
+
+	### 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 }
+
+		Pushdown::Automaton.install_state_methods( name, self )
+	end
+
+
+	### Return the Class object for the class named +class_name+ of the pushdown state
+	### +state_name+.
+	def pushdown_state_class( state_name, class_name )
+		config = self.pushdown_states[ state_name ] or
+			raise "No pushdown state named %p" % [ state_name ]
+		states = config[ :states ]
+
+		case states
+		when NilClass
+			return self.pushdown_inferred_state_class( class_name )
+		when Class
+			return self.pushdown_pluggable_state_class( states, class_name )
+		when Hash
+			return states[ class_name ]
+		else
+			raise "don't know how to derive a state class from %p (%p)" % [ states, states.class ]
+		end
+	end
+
+
+	### Return the state class with the name inferred from the given +class_name+.
+	def pushdown_inferred_state_class( class_name )
+		constant_name = class_name.to_s.capitalize.gsub( /_(\p{Alnum})/ ) do |match|
+			match[ 1 ].capitalize
+		end
+		self.log.debug "Inferred state class for %p is: %s" % [ class_name, constant_name ]
+
+		return self.const_get( constant_name )
+	end
+
+
+	### Derive a state class object named +class_name+ via the (pluggable)
+	### +state_base_class+.
+	def pushdown_pluggable_state_class( state_base_class, class_name )
+		return state_base_class.get_subclass( class_name )
+	end
+
+end # module Pushdown::Automaton
+
+

data/lib/pushdown/exceptions.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'pushdown' unless defined?( Pushdown )
+require 'e2mmap'
+
+module Pushdown
+	extend Exception2MessageMapper
+
+
+	def_exception :Error, "pushdown error"
+
+	def_exception :StateError, "error in state machine", Pushdown::Error
+	def_exception :TransitionError, "error while transitioning", Pushdown::Error
+
+
+end # module Pushdown
+

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, *args )
+			raise ScriptError, "can't specify more than one callback" if self.callback
+			@callback = [ :on_event, event, *args ]
+			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, *args = self.callback
+				desc << " when #%s is called" % [ methname ]
+				desc << " with %s" % [ args.map(&:inspect).join(', ') ] if !args.empty?
+			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
+
+