pushdown 0.1.0.pre.20210714190141 → 0.4.0

data/lib/pushdown/state.rb

@@ -0,0 +1,174 @@
+# -*- 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_%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
+
+
+	### Set up new States with an optional +data+ object.
+	def initialize( data=nil )
+		@data = data
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The state data object that was used to create the State (if any)
+	attr_reader :data
+
+
+	#
+	# Stack callbacks
+	#
+
+	### Stack callback -- called when the state is added to the stack.
+	def on_start
+		return nil # no-op
+	end
+
+
+	### Stack callback -- called when the state is removed from the stack.
+	def on_stop
+		return nil # no-op
+	end
+
+
+	### Stack callback -- called when another state is pushed over this one.
+	def on_pause
+		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
+		return nil # no-op
+	end
+
+
+	#
+	# 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, *args )
+		return nil # no-op
+	end
+
+
+	#
+	# Interval callbacks
+	#
+
+	### 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
+
+
+	### 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 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
+		return self.class.name.sub( /.*::/, '' ).
+			gsub( /([A-Z])([A-Z])/ ) { "#$1 #$2" }.
+			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 )
+			state_data = self.data
+
+			return Pushdown::Transition.
+				create( transition_type, transition_name, state_class, state_data )
+		else
+			return Pushdown::Transition.create( transition_type, transition_name )
+		end
+	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
+		@popped_state.on_stop
+		stack.last.on_resume
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Pop

data/lib/pushdown/transition/push.rb

@@ -0,0 +1,47 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'pushdown/transition' unless defined?( Pushdown::Transition )
+
+
+# A push transition -- add an instance of a given State to the top of the state
+# stack.
+class Pushdown::Transition::Push < Pushdown::Transition
+
+
+	### Create a transition that will Push an instance of the given +state_class+ to
+	### the stack.
+	def initialize( name, state_class, data=nil )
+		super( name )
+
+		@state_class = state_class
+		@data = data
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The State to push to.
+	attr_reader :state_class
+
+	##
+	# The data object to pass to the #state_class's constructor
+	attr_reader :data
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		state = self.state_class.new( self.data )
+
+		self.log.debug "pushing a new state: %p" % [ state ]
+		stack.last.on_pause if stack.last
+		stack.push( state )
+		state.on_start
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Push

data/lib/pushdown/transition/replace.rb

@@ -0,0 +1,49 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'pushdown/transition' unless defined?( Pushdown::Transition )
+
+
+# A replace transition -- remove all currents states from the stack and add a
+# different one.
+class Pushdown::Transition::Replace < Pushdown::Transition
+
+	### Create a transition that will Replace all the states on the current stack
+	### with an instance of the given +state_class+.
+	def initialize( name, state_class, data=nil )
+		super( name )
+
+		@state_class = state_class
+		@data = data
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The State to replace the stack members with.
+	attr_reader :state_class
+
+	##
+	# The data object to pass to the #state_class's constructor
+	attr_reader :data
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		state = self.state_class.new( self.data )
+
+		self.log.debug "replacing current state with a new state: %p" % [ state ]
+		while ( old_state = stack.pop )
+			old_state.on_stop
+		end
+
+		stack.push( state )
+		state.on_start
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Replace

data/lib/pushdown/transition/switch.rb

@@ -0,0 +1,50 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'pushdown/transition' unless defined?( Pushdown::Transition )
+
+
+# A switch transition -- remove the current state from the stack and add a
+# different one.
+class Pushdown::Transition::Switch < Pushdown::Transition
+
+	### Create a transition that will Switch the current State with an instance of
+	### the given +state_class+ on the stack.
+	def initialize( name, state_class, data=nil )
+		super( name )
+
+		@state_class = state_class
+		@data = data
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The State to push to.
+	attr_reader :state_class
+
+	##
+	# The data object to pass to the #state_class's constructor
+	attr_reader :data
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		raise Pushdown::TransitionError, "can't switch on an empty stack" if stack.empty?
+
+		state = self.state_class.new( self.data )
+
+		self.log.debug "switching current state with a new state: %p" % [ state ]
+		old_state = stack.pop
+		old_state.on_stop if old_state
+
+		stack.push( state )
+		state.on_start
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Switch

data/lib/pushdown/transition.rb

@@ -0,0 +1,68 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+require 'pluggability'
+
+require 'pushdown' unless defined?( Pushdown )
+require 'pushdown/state'
+
+
+# A transition in a Pushdown automaton
+class Pushdown::Transition
+	extend Loggability,
+		Pluggability
+
+	# Loggability API -- log to the pushdown logger
+	log_to :pushdown
+
+	# Pluggability API -- concrete types live in lib/pushdown/transition/
+	plugin_prefixes 'pushdown/transition'
+	plugin_exclusions 'spec/**/*'
+
+
+	# Don't allow direct instantiation (abstract class)
+	private_class_method :new
+
+
+	### Inheritance hook -- enable instantiation.
+	def self::inherited( subclass )
+		super
+		subclass.public_class_method( :new )
+		if (( type_name = subclass.name&.sub( /.*::/, '' )&.downcase ))
+			Pushdown::State.register_transition( type_name )
+		end
+	end
+
+
+	### Create a new Transition with the given +name+.
+	def initialize( name )
+		@name = name
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The name of the transition; mostly for human consumption
+	attr_reader :name
+
+
+	### 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.0.1'
+	VERSION = '0.4.0'
 
 
 	# Loggability API -- create a logger for Pushdown classes and modules
 	log_as :pushdown
 
+end # module Pushdown
 
-	autoload :Automaton, 'pushdown/automaton'
-	autoload :State, 'pushdown/state'
-	autoload :Transition, 'pushdown/transition'
-
+require 'pushdown/transition'
+require 'pushdown/state'
+require 'pushdown/automaton'
 
-end # module Pushdown
+Pushdown::Transition.plugin_exclusions( '**/spec/pushdown/transition/**' )
+Pushdown::Transition.load_all
 

data/spec/pushdown/automaton_spec.rb

@@ -0,0 +1,152 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative '../spec_helper'
+
+require 'pushdown/automaton'
+
+
+RSpec.describe( Pushdown::Automaton ) do
+
+	let( :extended_class ) do
+		the_class = Class.new
+		the_class.extend( described_class )
+		the_class
+	end
+
+	let( :starting_state ) do
+		Class.new( Pushdown::State ) do
+			transition_push :run, :running
+			def on_event( event, * )
+				return :run if event == :run
+				return nil
+			end
+		end
+	end
+	let( :off_state ) do
+		Class.new( Pushdown::State ) do
+			transition_push :start, :starting
+			def update( * )
+				return :start
+			end
+		end
+	end
+	let( :running_state ) { Class.new(Pushdown::State) }
+
+	let( :state_class_registry ) {{
+		starting: starting_state,
+		off: off_state,
+		running: running_state,
+	}}
+
+
+	it "allows a state attribute to be declared" do
+		extended_class.pushdown_state( :state, initial_state: :idle )
+		extended_class.const_set( :Idle, starting_state )
+
+		instance = extended_class.new
+
+		expect( instance.state ).to be_a( starting_state )
+	end
+
+
+	it "allows a state class registry to be inferred" do
+		extended_class.pushdown_state( :state, initial_state: :starting )
+		extended_class.const_set( :Starting, starting_state )
+
+		expect( extended_class.initial_state ).to be( starting_state )
+	end
+
+
+	it "allows a state registry to be passed as a Hash-alike" do
+		extended_class.pushdown_state( :status, initial_state: :starting, states: state_class_registry )
+
+		expect( extended_class.initial_status ).to be( starting_state )
+	end
+
+
+	context "for each pushdown state" do
+
+		it "allows a state registry to be passed as a (pluggable) Pushdown::State subclass" do
+			state_baseclass = Class.new( Pushdown::State ) do
+				singleton_class.attr_accessor :subclasses
+				def self::get_subclass( classname )
+					return subclasses[ classname ]
+				end
+				def self::create( class_name, *args )
+					return self.get_subclass( class_name ).new( *args )
+				end
+			end
+
+			state_baseclass.subclasses = state_class_registry
+			extended_class.pushdown_state( :state, initial_state: :starting, states: state_baseclass )
+
+			expect( extended_class.initial_state ).to be( starting_state )
+		end
+
+
+		it "generates an event method that applies transitions returned from #on_event" do
+			extended_class.pushdown_state( :state, initial_state: :starting )
+			extended_class.const_set( :Starting, starting_state )
+			extended_class.const_set( :Off, off_state )
+			extended_class.const_set( :Running, running_state )
+
+			instance = extended_class.new
+			result = instance.handle_state_event( :run )
+
+			expect( result ).to be_a( Pushdown::Transition::Push )
+			expect( instance.state ).to be_a( running_state )
+		end
+
+
+		it "generates an periodic update method that applies transitions returned from #update on the current state" do
+			extended_class.pushdown_state( :status, initial_state: :off )
+			extended_class.const_set( :Starting, starting_state )
+			extended_class.const_set( :Off, off_state )
+			extended_class.const_set( :Running, running_state )
+
+			instance = extended_class.new
+			result = instance.update_status
+
+			expect( result ).to be_a( Pushdown::Transition::Push )
+			expect( instance.status ).to be_a( starting_state )
+		end
+
+
+		it "generates an periodic update method that is called on every state in the stack" do
+			extended_class.pushdown_state( :status, initial_state: :off )
+			extended_class.const_set( :Starting, starting_state )
+			extended_class.const_set( :Off, off_state )
+			extended_class.const_set( :Running, running_state )
+
+			instance = extended_class.new
+			result = instance.shadow_update_status
+
+			expect( result ).to be_nil
+			expect( instance.status ).to be_a( off_state )
+		end
+
+
+		it "fetches initial state data if the extended class defines a method for doing so" do
+			extended_class.pushdown_state( :state, initial_state: :starting )
+			extended_class.const_set( :Starting, starting_state )
+			extended_class.const_set( :Off, off_state )
+			extended_class.const_set( :Running, running_state )
+			extended_class.attr_accessor :state_data
+			extended_class.define_method( :initial_state_data ) do
+				return self.state_data ||= {}
+			end
+
+			starting_state.define_method( :on_start ) do
+				data[:starting_started] = true
+			end
+
+			instance = extended_class.new
+
+			expect( instance.state_data ).to eq({ starting_started: true })
+		end
+
+	end
+
+end
+