Added monarch.top() and bottom()

README.md

@@ -261,6 +261,26 @@ Preload a Monarch screen. This will load but not enable the screen. This is usef
 * ```callback``` (function) - Optional function to call when the new screen is preloaded.
 
 
+### monarch.top([offset])
+Get the id of the screen at the top of the stack.
+
+**PARAMETERS**
+* ```offset``` (number) - Optional offset from the top of the stack, ie -1 to get the previous screen
+
+**RETURN**
+* ```screen_id``` (hash) - Id of the requested screen
+
+
+### monarch.bottom([offset])
+Get the id of the screen at the bottom of the stack.
+
+**PARAMETERS**
+* ```offset``` (number) - Optional offset from the bottom of the stack
+
+**RETURN**
+* ```screen_id``` (hash) - Id of the requested screen
+
+
 ### monarch.data(screen_id)
 Get the data associated with a screen (from a call to ```monarch.show()``` or ```monarch.back()```).
 

monarch/monarch.lua

@@ -491,6 +491,25 @@ function M.get_stack()
 	return s
 end
 
+
+--- Get the screen on top of the stack
+-- @param offset Optional offset from the top of the stack, (eg -1 for the previous screen)
+-- @return Id of the requested screen
+function M.top(offset)
+	local screen = stack[#stack + (offset or 0)]
+	return screen and screen.id
+end
+
+
+--- Get the screen at the bottom of the stack
+-- @param offset Optional offset from the bottom of the stack
+-- @return Id of the requested screen
+function M.bottom(offset)
+	local screen = stack[1 + (offset or 0)]
+	return screen and screen.id
+end
+
+
 function M.dump_stack()
 	local s = ""
 	for i, screen in ipairs(stack) do

test/test_monarch.lua

@@ -176,5 +176,30 @@ return function()
 			assert_stack({ SCREEN1, SCREEN2 })
 		end)
 
+
+		it("should be able to get the id of the screen at the top and bottom of the stack", function()
+			assert(monarch.top() == nil)
+			assert(monarch.bottom() == nil)
+			assert(monarch.top(1) == nil)
+			assert(monarch.bottom(-1) == nil)
+						
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(monarch.top() == SCREEN1)
+			assert(monarch.top(0) == SCREEN1)
+			assert(monarch.top(1) == nil)
+			assert(monarch.bottom() == SCREEN1)
+			assert(monarch.bottom(0) == SCREEN1)
+			assert(monarch.bottom(-1) == nil)
+									
+			monarch.show(SCREEN2)
+			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			assert_stack({ SCREEN1, SCREEN2 })
+			assert(monarch.top(0) == SCREEN2)
+			assert(monarch.top(-1) == SCREEN1)
+			assert(monarch.bottom(0) == SCREEN1)
+			assert(monarch.bottom(1) == SCREEN2)
+		end)
 	end)
 end