pushdown 0.1.0.pre.20210714190141 → 0.1.0

data/lib/pushdown/transition/push.rb

@@ -0,0 +1,41 @@
+# -*- 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, *args )
+		super( name, *args )
+		@state_class = state_class
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The State to push to.
+	attr_reader :state_class
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		state = self.state_class.new
+
+		self.log.debug "pushing a new state: %p" % [ state ]
+		self.data = stack.last.on_pause( self.data ) if stack.last
+		stack.push( state )
+		state.on_start( self.data )
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Push

data/lib/pushdown/transition/replace.rb

@@ -0,0 +1,43 @@
+# -*- 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, *args )
+		super( name, *args )
+		@state_class = state_class
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The State to replace the stack members with.
+	attr_reader :state_class
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		state = self.state_class.new
+
+		self.log.debug "replacing current state with a new state: %p" % [ state ]
+		while ( old_state = stack.pop )
+			self.data = old_state.on_stop( self.data )
+		end
+
+		stack.push( state )
+		state.on_start( self.data )
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Replace

data/lib/pushdown/transition/switch.rb

@@ -0,0 +1,41 @@
+# -*- 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, *args )
+		super( name, *args )
+		@state_class = state_class
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The State to push to.
+	attr_reader :state_class
+
+
+	### Apply the transition to the given +stack+.
+	def apply( stack )
+		state = self.state_class.new
+
+		self.log.debug "switching current state with a new state: %p" % [ state ]
+		old_state = stack.pop
+		self.data = old_state.on_stop( self.data )
+		stack.push( state )
+		state.on_start( self.data )
+
+		return stack
+	end
+
+end # class Pushdown::Transition::Switch

data/lib/pushdown/transition.rb

@@ -0,0 +1,85 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+require 'pluggability'
+
+require 'pushdown' unless defined?( Pushdown )
+
+# 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
+	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+. 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 )
+		@name = name
+		@data = data
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The name of the transition; mostly for human consumption
+	attr_reader :name
+
+	##
+	# Data to pass to the transition callbacks when applying this Transition.
+	attr_accessor :data
+
+
+	### 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
+
+end # class Pushdown::Transition
+

data/lib/pushdown.rb

@@ -15,17 +15,17 @@ module Pushdown
 	extend Loggability
 
 	# Package version
-	VERSION = '0.0.1'
+	VERSION = '0.1.0'
 
 
 	# Loggability API -- create a logger for Pushdown classes and modules
 	log_as :pushdown
 
-
-	autoload :Automaton, 'pushdown/automaton'
-	autoload :State, 'pushdown/state'
 	autoload :Transition, 'pushdown/transition'
-
+	autoload :State, 'pushdown/state'
+	autoload :Automaton, '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,151 @@
+#!/usr/bin/env rspec -cfd
+
+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|
+				data[:starting_started] = true
+			end
+
+			instance = extended_class.new
+
+			expect( instance.state_data ).to eq({ starting_started: true })
+		end
+
+	end
+
+end
+

data/spec/pushdown/state_spec.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env rspec -cfd
+
+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( described_class )
+	end
+
+
+	it "is an abstract class" do
+		expect { described_class.new }.to raise_error( NoMethodError, /\bnew\b/ )
+	end
+
+
+	describe "event handlers" do
+
+		it "has a default (no-op) callback for when it is added to the stack" do
+			instance = subclass.new
+			expect( instance.on_start(state_data) ).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(state_data) ).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(state_data) ).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(state_data) ).to be_nil
+		end
+
+	end
+
+
+	describe "update handlers" do
+
+		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
+
+
+		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
+
+	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
+
+
+end
+