pushdown 0.1.0.pre.20210714190141 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3aa15b901bc12dcc15430512e8ec06fdaa5bbc98afd222a62892fad5b1fa689
-  data.tar.gz: 5b4d53652f5a1d0df9c759d6b9226d4780c87cb4258d650295748e8ecd64ab01
+  metadata.gz: bf2b58a9924b03dc5e15d6c0fca42ebac8988fcdbf9e0b02f1ab3b1e2365de56
+  data.tar.gz: 7117970f25e2e310be68a2269dd77216cae26442d298e73dd1bb580a29752914
 SHA512:
-  metadata.gz: 5f3143596b9615ab3a538a2b5256fc43649b11ca1cf6a90fa33a616cee74c09d6ba39e4832ad417352fd15a1162a2698daca1aedcd069af4cf2d48b551dd1245
-  data.tar.gz: 7f1fd1112549fd7cf19c2a472678fbd5dc58d6d07178d7ce84d0a5d7b96293a3e272b691499624fd23de961aff1df50b742bdaeab640e4d0e4c065fa6771b5d7
+  metadata.gz: 9b41ba0c24de3f75fb91fbc02e3b20afc5d2d4a8aac8f43d9ae4237e354fcab2611d48eb885f2bef542d9d9da5bbb5c6686f98c78ea26287e84e9c7fb8242011
+  data.tar.gz: 1d84bef861cf31696148031a01a13fd04ef5a76d9bd45733f3a0043976e62a97aa56836b3c7bdcaf54d45bf798df9abe4c59b619ebd406f7d457442340d1ed5c

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+K�ŷ���▬�Vl��t3�x�����_Y6/o��"r�.�Xr��,�
�"k�Ƿ2�SH�Ո�є��+�u؂����yv��FF ��=r�S�����oE�	k�oEd���[����Q°���xz�/���2Хkp�2,�x�&��Mկˋ�l�C�8�����Hnu1(�����7�����
Cm��L�`?�5r�T��y�wv�V0
�R���DU�
+���9p鬭BD;7E�Î�4��*�cr~Ş��{���g�@j;ڸ�^˳�Aޒ���i�u�Ie�*z��c��i&�)�U����,� ��D%}/#)H��V��U�=9���

data/History.md

@@ -1,4 +1,9 @@
-## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+# Release History for pushdown
+
+---
+
+
+## v0.1.0 [2021-08-27] Michael Granger <ged@faeriemud.org>
 
 Initial release.
 

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2019 Michael Granger
+
+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.

data/lib/pushdown/automaton.rb

@@ -0,0 +1,236 @@
+# -*- 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
+
+
+	### 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
+
+
+	# 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 }
+
+		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/state.rb

@@ -0,0 +1,110 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'pluggability'
+require 'loggability'
+
+require 'pushdown' unless defined?( Pushdown )
+
+
+# A componented state object in a Pushdown automaton
+class Pushdown::State
+	extend Loggability
+
+	# Loggability API -- log to the pushdown logger
+	log_to :pushdown
+
+	# Don't allow instantation of the abstract class
+	private_class_method :new
+
+	##
+	# Allow introspection on declared transitions
+	singleton_class.attr_reader :transitions
+
+
+	### Inheritance callback -- allow subclasses to be instantiated, and add some
+	### class-instance data to them.
+	def self::inherited( subclass )
+		super
+
+		subclass.public_class_method( :new )
+		subclass.instance_variable_set( :@transitions, {} )
+	end
+
+
+	#
+	# Transition declarations
+	#
+
+	### Register a transition +type+ declaration method.
+	def self::register_transition( type )
+		type = type.to_sym
+		meth = lambda do |transition_name, *args|
+			self.transitions[ transition_name ] = [ type, *args ]
+		end
+
+		method_name = "transition_#{type}"
+		define_singleton_method( method_name, &meth )
+	end
+
+
+	#
+	# Stack callbacks
+	#
+
+	### Stack callback -- called when the state is added to the stack.
+	def on_start( data=nil )
+		return nil # no-op
+	end
+
+
+	### Stack callback -- called when the state is removed from the stack.
+	def on_stop( data=nil )
+		return nil # no-op
+	end
+
+
+	### Stack callback -- called when another state is pushed over this one.
+	def on_pause( data=nil )
+		return nil # no-op
+	end
+
+
+	### Stack callback -- called when another state is popped off from in front of
+	### this one, making it the current state.
+	def on_resume( data=nil )
+		return nil # no-op
+	end
+
+
+	#
+	# State callbacks
+	#
+
+	### State callback -- interval callback called when the state is the current one.
+	def update( *data )
+		return nil # no-op
+	end
+
+
+	### State callback -- interval callback called when the state is on the stack,
+	### even when the state is not the current one.
+	def shadow_update( *data )
+		return nil # no-op
+	end
+
+
+	#
+	# Introspection/information
+	#
+
+	### Return a description of the State as an engine phrase.
+	def description
+		return "%#x" % [ self.class.object_id ] unless self.class.name
+		return self.class.name.sub( /.*::/, '' ).
+			gsub( /([A-Z])([A-Z])/ ) { "#$1 #$2" }.
+			gsub( /([a-z])([A-Z])/ ) { "#$1 #$2" }.downcase
+	end
+
+end # class Pushdown::State
+

data/lib/pushdown/transition/pop.rb

@@ -0,0 +1,35 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'pushdown/transition' unless defined?( Pushdown::Transition )
+require 'pushdown/exceptions'
+
+
+# A push transition -- add an instance of a given State to the top of the state
+# stack.
+class Pushdown::Transition::Pop < Pushdown::Transition
+
+
+	######
+	public
+	######
+
+	##
+	# Return the state that was popped
+	attr_reader :popped_state
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		raise Pushdown::TransitionError, "can't pop from an empty stack" if stack.empty?
+		raise Pushdown::TransitionError, "can't pop the only state on the stack" if stack.length == 1
+
+		self.log.debug "popping a state"
+		@popped_state = stack.pop
+		self.data = @popped_state.on_stop( self.data )
+		stack.last.on_resume( self.data )
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Pop