From f73d9ee704d423da474edb8c8ff6589cc16c1cf0 Mon Sep 17 00:00:00 2001
From: Pasi Kallinen <paxed@alt.org>
Date: Sun, 25 Jan 2026 15:18:45 +0200
Subject: [PATCH] Expose selection size description to lua

---
 doc/lua.adoc      | 10 ++++++++++
 src/nhlsel.c      | 14 ++++++++++++++
 test/test_sel.lua | 18 ++++++++++++++++++
 3 files changed, 42 insertions(+)

diff --git a/doc/lua.adoc b/doc/lua.adoc
index f040886ec..859cf922d 100644
--- a/doc/lua.adoc
+++ b/doc/lua.adoc
@@ -1145,6 +1145,16 @@ Example:
  local sel2 = selection.clone(sel);
 
 
+=== describe_size
+
+Return a text describing the size of the selection.
+
+Example:
+
+ local sel = selection.fillrect(1,1, 3,3);
+ local txt = sel:describe_size();
+
+
 === ellipse
 
 Example:
diff --git a/src/nhlsel.c b/src/nhlsel.c
index 306820cf9..3dad65bfb 100644
--- a/src/nhlsel.c
+++ b/src/nhlsel.c
@@ -33,6 +33,7 @@ staticfn int l_selection_circle(lua_State *);
 staticfn int l_selection_ellipse(lua_State *);
 staticfn int l_selection_gradient(lua_State *);
 staticfn int l_selection_iterate(lua_State *);
+staticfn int l_selection_size_description(lua_State *L);
 staticfn int l_selection_gc(lua_State *);
 staticfn int l_selection_not(lua_State *);
 staticfn int l_selection_and(lua_State *);
@@ -949,6 +950,18 @@ l_selection_iterate(lua_State *L)
     return 0;
 }
 
+/* local txt = sel:describe_size(); */
+/* gives a textual description of the selection size */
+staticfn int
+l_selection_size_description(lua_State *L)
+{
+    int argc = lua_gettop(L);
+    struct selectionvar *sel = l_selection_check(L, 1);
+    char buf[BUFSZ];
+
+    lua_pushstring(L, selection_size_description(sel, buf));
+    return 1;
+}
 
 static const struct luaL_Reg l_selection_methods[] = {
     { "new", l_selection_new },
@@ -974,6 +987,7 @@ static const struct luaL_Reg l_selection_methods[] = {
     { "iterate", l_selection_iterate },
     { "bounds", l_selection_getbounds },
     { "room", l_selection_room },
+    { "describe_size", l_selection_size_description },
     { NULL, NULL }
 };
 
diff --git a/test/test_sel.lua b/test/test_sel.lua
index 637b1b281..c5739e8fd 100644
--- a/test/test_sel.lua
+++ b/test/test_sel.lua
@@ -540,6 +540,23 @@ function test_sel_gradient()
    local selc = selection.gradient({ x = 3, y = 5, x2 = 10, y2 = 12, maxdist = 10});
 end
 
+function test_sel_describe_size()
+   local sela = selection.fillrect(1,1, 3,3);
+   if (sela:describe_size() ~= "square 3 by 3") then
+      error("selection.describe_size returned \"" .. sela:describe_size() "\", not \"square 3 by 3\"");
+   end
+
+   local selb = selection.fillrect(1,1, 4,3);
+   if (selb:describe_size() ~= "rectangular 4 by 3") then
+      error("selection.describe_size returned \"" .. selb:describe_size() "\", not \"rectangular 4 by 3\"");
+   end
+
+   sela:set(1,1, 0);
+   if (sela:describe_size() ~= "irregularly shaped 3 by 3") then
+      error("selection.describe_size returned \"" .. sela:describe_size() "\", not \"irregularly shaped 3 by 3\"");
+   end
+end
+
 nh.debug_flags({mongen = false, hunger = false, overwrite_stairs = true });
 test_selection_params();
 test_sel_negate();
@@ -563,3 +580,4 @@ test_sel_map();
 test_sel_numpoints();
 test_sel_room();
 test_sel_gradient();
+test_sel_describe_size();