From 66b1f7ca2e846e024df9eaa46825944c4a711a60 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Ritzl?= <bjorn.ritzl@gmail.com>
Date: Mon, 4 Jun 2018 13:56:45 +0200
Subject: [PATCH] Added monarch.top() and bottom()

---
 README.md             | 20 ++++++++++++++++++++
 monarch/monarch.lua   | 19 +++++++++++++++++++
 test/test_monarch.lua | 27 ++++++++++++++++++++++++++-
 3 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 027e9cd..2b16648 100644
--- a/README.md
+++ b/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()```).
 
diff --git a/monarch/monarch.lua b/monarch/monarch.lua
index eb5d8fb..109c045 100644
--- a/monarch/monarch.lua
+++ b/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
diff --git a/test/test_monarch.lua b/test/test_monarch.lua
index d5464e2..dde2717 100644
--- a/test/test_monarch.lua
+++ b/test/test_monarch.lua
@@ -175,6 +175,31 @@ return function()
 			assert(wait_until_shown(SCREEN2), "Popup2 was never shown")
 			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