From 8dd212fc71ec08c196d5db22b239f496b97b1862 Mon Sep 17 00:00:00 2001
From: PhatPhuckDave <david.majdandzic@hotmail.com>
Date: Fri, 19 Dec 2025 13:24:44 +0100
Subject: [PATCH] Code polish

---
 processor/luahelper.lua | 52 +++++++++++++++++++++++++++++++++++++----
 processor/processor.go  | 11 ++++++---
 2 files changed, 56 insertions(+), 7 deletions(-)

diff --git a/processor/luahelper.lua b/processor/luahelper.lua
index 3aadee1..d9e7389 100644
--- a/processor/luahelper.lua
+++ b/processor/luahelper.lua
@@ -1,26 +1,61 @@
 -- Custom Lua helpers for math operations
+
+--- Returns the minimum of two numbers
+--- @param a number First number
+--- @param b number Second number
+--- @return number Minimum value
 function min(a, b) return math.min(a, b) end
 
+--- Returns the maximum of two numbers
+--- @param a number First number
+--- @param b number Second number
+--- @return number Maximum value
 function max(a, b) return math.max(a, b) end
 
+--- Rounds a number to n decimal places
+--- @param x number Number to round
+--- @param n number? Number of decimal places (default: 0)
+--- @return number Rounded number
 function round(x, n)
 	if n == nil then n = 0 end
 	return math.floor(x * 10 ^ n + 0.5) / 10 ^ n
 end
 
+--- Returns the floor of a number
+--- @param x number Number to floor
+--- @return number Floored number
 function floor(x) return math.floor(x) end
 
+--- Returns the ceiling of a number
+--- @param x number Number to ceil
+--- @return number Ceiled number
 function ceil(x) return math.ceil(x) end
 
+--- Converts string to uppercase
+--- @param s string String to convert
+--- @return string Uppercase string
 function upper(s) return string.upper(s) end
 
+--- Converts string to lowercase
+--- @param s string String to convert
+--- @return string Lowercase string
 function lower(s) return string.lower(s) end
 
+--- Formats a string using Lua string.format
+--- @param s string Format string
+--- @param ... any Values to format
+--- @return string Formatted string
 function format(s, ...) return string.format(s, ...) end
 
+--- Removes leading and trailing whitespace from string
+--- @param s string String to trim
+--- @return string Trimmed string
 function trim(s) return string.gsub(s, "^%s*(.-)%s*$", "%1") end
 
--- String split helper
+--- Splits a string by separator
+--- @param inputstr string String to split
+--- @param sep string? Separator pattern (default: whitespace)
+--- @return table Array of string parts
 function strsplit(inputstr, sep)
 	if sep == nil then sep = "%s" end
 	local t = {}
@@ -328,15 +363,24 @@ function toCSV(rows, options)
 	return table.concat(rowStrings, "\n")
 end
 
--- String to number conversion helper
+--- Converts string to number, returns 0 if invalid
+--- @param str string String to convert
+--- @return number Numeric value or 0
 function num(str) return tonumber(str) or 0 end
 
--- Number to string conversion
+--- Converts number to string
+--- @param num number Number to convert
+--- @return string String representation
 function str(num) return tostring(num) end
 
--- Check if string is numeric
+--- Checks if string is numeric
+--- @param str string String to check
+--- @return boolean True if string is numeric
 function is_number(str) return tonumber(str) ~= nil end
 
+--- Checks if table is a sequential array (1-indexed with no gaps)
+--- @param t table Table to check
+--- @return boolean True if table is an array
 function isArray(t)
 	if type(t) ~= "table" then return false end
 	local max = 0
diff --git a/processor/processor.go b/processor/processor.go
index 365b057..83c4255 100644
--- a/processor/processor.go
+++ b/processor/processor.go
@@ -470,7 +470,8 @@ TABLE FUNCTIONS:
   isArray(t)         - Returns true if table is a sequential array
 
 XML HELPER FUNCTIONS:
-  findElements(root, tagName)           - Find all elements with specific tag name
+  findElements(root, tagName)           - Find all elements with specific tag name (recursive)
+  findFirstElement(parent, tagName)     - Find first direct child with specific tag name
   visitElements(root, callback)         - Visit all elements recursively
     callback(element, depth, path)
   filterElements(root, predicate)       - Find elements matching condition
@@ -484,11 +485,15 @@ XML HELPER FUNCTIONS:
   setAttr(element, attrName, value)     - Set attribute value
   getText(element)                      - Get element text content
   setText(element, text)                - Set element text content
+  addChild(parent, child)               - Add child element to parent
+  removeChildren(parent, tagName)       - Remove all children with specific tag name
+  getChildren(parent, tagName)          - Get all direct children with specific tag name
+  countChildren(parent, tagName)        - Count direct children with specific tag name
 
 JSON HELPER FUNCTIONS:
-  visitJSON(data, callback)             - Visit all values in JSON structure
+  visitJSON(data, callback)                    - Visit all values in JSON structure
     callback(value, key, parent)
-  findInJSON(data, predicate)           - Find values matching condition
+  findInJSON(data, predicate)                  - Find values matching condition
     predicate(value, key, parent) returns true/false
   modifyJSONNumbers(data, predicate, modifier) - Modify numeric values
     predicate(value, key, parent) returns true/false