pushdown 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de5a87ff7d9744a6c71e977a4d5e2fbe03be08efc393d5fc8c84b7a9f4f720c2
-  data.tar.gz: 6a94eca59001d1640a5676e9a135b56690c6e20f2ec75e49740b68b036005870
+  metadata.gz: 07c713124675b07b3fdb91a1e7a9c2f0386899c2e37ca1b820ddbce6aaa5ea8e
+  data.tar.gz: f3c40b62850afe641934d6a77ffec9011809df10648c073242de1d65646f7578
 SHA512:
-  metadata.gz: 677caf47c2cebd2ac9023a72d16e99881b97be5cacd439aae7f472bdefb1d1e7d7ee75151211988f1b354bc1f9339d3ab4483dce83cec24740579562e48ee41c
-  data.tar.gz: e32e468403256a51c4683bff1bbf5f332461ed5fc22c43369509b8e241e4f0a102ba105cbfa925474b55e4420dfc8e3ff49af42a8abdd793b7e046e2f1810f69
+  metadata.gz: 7957d836aaf103e2e45da26ab088ff66709c3463f2e630f9d4e1cc14e07519cc147359db0a622c659d6dc5b02ef57b374434b7816cee5f519ca9a58d57a0d140
+  data.tar.gz: 5e1c5467df6a41e86a797d4b783e07684296cb252ca241f284360ee0d4677a1413fe9974e7f63ccd2cda1fdfae6a970fada1158ea9dcc108382fe1ac45bb33aa

data/History.md

@@ -1,6 +1,14 @@
 # Release History for pushdown
 
 ---
+## 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>
 

data/LICENSE.txt

@@ -1,20 +1,27 @@
-Copyright (c) 2019 Michael Granger
+Copyright (c) 2019-2021, Michael Granger
+All rights reserved.
 
-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:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
 
-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.
+* 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,18 +31,19 @@ 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)

data/lib/pushdown/state.rb

@@ -57,31 +57,46 @@ class Pushdown::State
 	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( data=nil )
+	def on_start
 		return nil # no-op
 	end
 
 
 	### Stack callback -- called when the state is removed from the stack.
-	def on_stop( data=nil )
+	def on_stop
 		return nil # no-op
 	end
 
 
 	### Stack callback -- called when another state is pushed over this one.
-	def on_pause( data=nil )
+	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( data=nil )
+	def on_resume
 		return nil # no-op
 	end
 
@@ -146,7 +161,10 @@ class Pushdown::State
 
 		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 )
+			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

data/lib/pushdown/transition/pop.rb

@@ -26,8 +26,8 @@ class Pushdown::Transition::Pop < Pushdown::Transition
 
 		self.log.debug "popping a state"
 		@popped_state = stack.pop
-		self.data = @popped_state.on_stop( self.data )
-		stack.last.on_resume( self.data )
+		@popped_state.on_stop
+		stack.last.on_resume
 
 		return stack
 	end

data/lib/pushdown/transition/push.rb

@@ -11,9 +11,11 @@ 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 )
+	def initialize( name, state_class, data=nil )
+		super( name )
+
 		@state_class = state_class
+		@data = data
 	end
 
 
@@ -25,15 +27,19 @@ class Pushdown::Transition::Push < Pushdown::Transition
 	# 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
+		state = self.state_class.new( self.data )
 
 		self.log.debug "pushing a new state: %p" % [ state ]
-		self.data = stack.last.on_pause( self.data ) if stack.last
+		stack.last.on_pause if stack.last
 		stack.push( state )
-		state.on_start( self.data )
+		state.on_start
 
 		return stack
 	end

data/lib/pushdown/transition/replace.rb

@@ -10,9 +10,11 @@ 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 )
+	def initialize( name, state_class, data=nil )
+		super( name )
+
 		@state_class = state_class
+		@data = data
 	end
 
 
@@ -24,18 +26,22 @@ class Pushdown::Transition::Replace < Pushdown::Transition
 	# 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
+		state = self.state_class.new( self.data )
 
 		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 )
+			old_state.on_stop
 		end
 
 		stack.push( state )
-		state.on_start( self.data )
+		state.on_start
 
 		return stack
 	end

data/lib/pushdown/transition/switch.rb

@@ -10,9 +10,11 @@ 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 )
+	def initialize( name, state_class, data=nil )
+		super( name )
+
 		@state_class = state_class
+		@data = data
 	end
 
 
@@ -24,16 +26,23 @@ class Pushdown::Transition::Switch < Pushdown::Transition
 	# 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
+		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
-		self.data = old_state.on_stop( self.data )
+		old_state.on_stop if old_state
+
 		stack.push( state )
-		state.on_start( self.data )
+		state.on_start
 
 		return stack
 	end

data/lib/pushdown/transition.rb

@@ -35,12 +35,9 @@ class Pushdown::Transition
 	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 )
+	### Create a new Transition with the given +name+.
+	def initialize( name )
 		@name = name
-		@data = data
 	end
 
 
@@ -52,10 +49,6 @@ class Pushdown::Transition
 	# 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 )

data/lib/pushdown.rb

@@ -15,7 +15,7 @@ module Pushdown
 	extend Loggability
 
 	# Package version
-	VERSION = '0.2.0'
+	VERSION = '0.3.0'
 
 
 	# Loggability API -- create a logger for Pushdown classes and modules

data/spec/pushdown/automaton_spec.rb

@@ -137,7 +137,7 @@ RSpec.describe( Pushdown::Automaton ) do
 				return self.state_data ||= {}
 			end
 
-			starting_state.define_method( :on_start ) do |data|
+			starting_state.define_method( :on_start ) do
 				data[:starting_started] = true
 			end
 

data/spec/pushdown/state_spec.rb

@@ -55,25 +55,25 @@ RSpec.describe( Pushdown::State ) 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
+			expect( instance.on_start ).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
+			expect( instance.on_stop ).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
+			expect( instance.on_pause ).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
+			expect( instance.on_resume ).to be_nil
 		end
 
 	end
@@ -93,13 +93,13 @@ RSpec.describe( Pushdown::State ) 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
+			expect( instance.update ).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
+			expect( instance.shadow_update ).to be_nil
 		end
 
 	end
@@ -136,6 +136,18 @@ RSpec.describe( Pushdown::State ) do
 			expect( result.data ).to be_nil
 		end
 
+
+		it "can create a transition it has declared that doesn't take a state class" do
+			subclass.transition_pop( :quit )
+			instance = subclass.new
+
+			automaton = automaton_class.new
+
+			result = instance.transition( :quit, automaton, :state )
+			expect( result ).to be_a( Pushdown::Transition::Pop )
+			expect( result.name ).to eq( :quit )
+		end
+
 	end
 
 end

data/spec/pushdown/transition/pop_spec.rb

@@ -17,8 +17,6 @@ RSpec.describe( Pushdown::Transition::Pop ) do
 	let( :state_b ) { state_class.new }
 	let( :state_c ) { state_class.new }
 
-	let( :state_data ) { Object.new }
-
 	let( :stack ) do
 		return [ state_a, state_b, state_c ]
 	end
@@ -35,11 +33,10 @@ RSpec.describe( Pushdown::Transition::Pop ) do
 
 
 	it "passes state data through the transition callbacks" do
-		transition = described_class.new( :pop_test, state_data )
+		transition = described_class.new( :pop_test )
 
-		expect( state_c ).to receive( :on_stop ).with( state_data ).
-			and_return( state_data ).once.ordered
-		expect( state_b ).to receive( :on_resume ).with( state_data ).once.ordered
+		expect( state_c ).to receive( :on_stop ).with( no_args ).once.ordered
+		expect( state_b ).to receive( :on_resume ).with( no_args ).once.ordered
 
 		transition.apply( stack )
 	end

data/spec/pushdown/transition/push_spec.rb

@@ -16,18 +16,12 @@ RSpec.describe( Pushdown::Transition::Push ) do
 		Class.new( Pushdown::State )
 	end
 
-	let( :state_a ) { state_class.new }
-	let( :state_b ) { state_class.new }
-	let( :state_c ) { other_state_class.new }
-
-	let( :stack ) do
-		return [ state_a, state_b ]
-	end
-
 	let( :state_data ) { Object.new }
 
 
+
 	it "pushes a new state onto the stack when applied" do
+		stack = [ state_class.new, state_class.new ]
 		transition = described_class.new( :push_test, other_state_class )
 
 		new_stack = transition.apply( stack )
@@ -35,17 +29,31 @@ RSpec.describe( Pushdown::Transition::Push ) do
 		expect( new_stack ).to be_an( Array )
 		expect( new_stack.length ).to eq( 3 )
 		expect( new_stack.last ).to be_a( other_state_class )
+		expect( new_stack.last.data ).to be_nil
 	end
 
 
-	it "passes state data through the transition callbacks" do
-		transition = described_class.new( :push_test, other_state_class, state_data )
+	it "passes on state data to the new state if given" do
+		stack = []
+		transition = described_class.new( :push_test, state_class, state_data )
+
+		new_stack = transition.apply( stack )
+
+		expect( new_stack.last.data ).to be( state_data )
+	end
 
-		expect( state_b ).to receive( :on_pause ).
-			with( state_data ).once.and_return( state_data ).ordered
 
-		expect( other_state_class ).to receive( :new ).and_return( state_c )
-		expect( state_c ).to receive( :on_start ).with( state_data ).once.ordered
+	it "calls the transition callbacks of the former current state and the new state" do
+		new_state = instance_double( other_state_class )
+		stack = [
+			state_class.new,
+			state_class.new
+		]
+		transition = described_class.new( :push_test, other_state_class )
+
+		expect( stack.last ).to receive( :on_pause )
+		expect( other_state_class ).to receive( :new ).and_return( new_state )
+		expect( new_state ).to receive( :on_start )
 
 		transition.apply( stack )
 	end

data/spec/pushdown/transition/replace_spec.rb

@@ -28,6 +28,7 @@ RSpec.describe( Pushdown::Transition::Replace ) do
 
 
 	it "replaces the current stack members with a single new instance of a state when applied" do
+		stack = [ state_class.new, state_class.new ]
 		transition = described_class.new( :replace_test, other_state_class )
 
 		new_stack = transition.apply( stack )
@@ -38,18 +39,31 @@ RSpec.describe( Pushdown::Transition::Replace ) do
 	end
 
 
-	it "passes state data through the transition callbacks" do
-		transition = described_class.new( :replace_test, other_state_class, state_data )
+	it "passes on state data to the new state if given" do
+		stack = []
+		transition = described_class.new( :replace_test, state_class, state_data )
 
-		expect( state_c ).to receive( :on_stop ).
-			with( state_data ).once.and_return( state_data ).ordered
-		expect( state_b ).to receive( :on_stop ).
-			with( state_data ).once.and_return( state_data ).ordered
-		expect( state_a ).to receive( :on_stop ).
-			with( state_data ).once.and_return( state_data ).ordered
+		new_stack = transition.apply( stack )
+
+		expect( new_stack.last.data ).to be( state_data )
+	end
+
+
+	it "calls the transition callbacks of all the former states and the new state" do
+		new_state = instance_double( other_state_class )
+		stack = [
+			state_class.new,
+			state_class.new,
+			other_state_class.new
+		]
+		transition = described_class.new( :replace_test, other_state_class )
+
+		expect( stack[2] ).to receive( :on_stop ).ordered
+		expect( stack[1] ).to receive( :on_stop ).ordered
+		expect( stack[0] ).to receive( :on_stop ).ordered
 
-		expect( other_state_class ).to receive( :new ).and_return( state_c )
-		expect( state_c ).to receive( :on_start ).with( state_data ).once.ordered
+		expect( other_state_class ).to receive( :new ).and_return( new_state )
+		expect( new_state ).to receive( :on_start ).ordered
 
 		transition.apply( stack )
 	end

data/spec/pushdown/transition/switch_spec.rb

@@ -15,18 +15,12 @@ RSpec.describe( Pushdown::Transition::Switch ) do
 		Class.new( Pushdown::State )
 	end
 
-	let( :state_a ) { state_class.new }
-	let( :state_b ) { state_class.new }
-	let( :state_c ) { other_state_class.new }
-
-	let( :stack ) do
-		return [ state_a, state_b ]
-	end
-
 	let( :state_data ) { Object.new }
 
 
-	it "pops the current state off the stack and adds a new state when applied" do
+
+	it "switches the current state the stack with a new one when applied" do
+		stack = [ state_class.new, state_class.new ]
 		transition = described_class.new( :switch_test, other_state_class )
 
 		new_stack = transition.apply( stack )
@@ -34,20 +28,44 @@ RSpec.describe( Pushdown::Transition::Switch ) do
 		expect( new_stack ).to be_an( Array )
 		expect( new_stack.length ).to eq( 2 )
 		expect( new_stack.last ).to be_a( other_state_class )
+		expect( new_stack.last.data ).to be_nil
 	end
 
 
-	it "passes state data through the transition callbacks" do
-		transition = described_class.new( :switch_test, other_state_class, state_data )
+	it "passes on state data to the new state if given" do
+		stack = [ state_class.new ]
+		transition = described_class.new( :switch_test, state_class, state_data )
 
-		expect( state_b ).to receive( :on_stop ).
-			with( state_data ).once.and_return( state_data ).ordered
+		new_stack = transition.apply( stack )
+
+		expect( new_stack.last.data ).to be( state_data )
+	end
 
-		expect( other_state_class ).to receive( :new ).and_return( state_c )
-		expect( state_c ).to receive( :on_start ).with( state_data ).once.ordered
+
+	it "calls the transition callbacks of the former current state and the new state" do
+		new_state = instance_double( other_state_class )
+		stack = [
+			state_class.new,
+			state_class.new
+		]
+		transition = described_class.new( :switch_test, other_state_class )
+
+		expect( stack.last ).to receive( :on_stop )
+		expect( other_state_class ).to receive( :new ).and_return( new_state )
+		expect( new_state ).to receive( :on_start )
 
 		transition.apply( stack )
 	end
 
+
+	it "errors if applied to an empty stack" do
+		stack = []
+		transition = described_class.new( :switch_test, other_state_class )
+
+		expect {
+			transition.apply( stack )
+		}.to raise_error( Pushdown::TransitionError, /can't switch/i )
+	end
+
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pushdown
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.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-31 00:00:00.000000000 Z
+date: 2021-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability