@@ -120,6 +120,189 @@ end
120120** Returns:**
121121- ` [string] ` : Array of relative file paths, or ` nil ` and error message on failure
122122
123+ ### Utils Module
124+
125+ Functions available in Lua as ` utils.* `
126+
127+ #### merge
128+
129+ ``` lua
130+ utils .merge (destination , source , strategy ) -> table , error
131+ ```
132+
133+ Performs a deep merge of two tables, combining their contents recursively.
134+
135+ ** Parameters:**
136+ - ` destination ` (table): The target table to merge into
137+ - ` source ` (table): The source table to merge from
138+ - ` strategy ` (string, optional): Merge strategy - "override" (default) or "append"
139+
140+ ** Returns:**
141+ - ` table ` : Merged table, or ` nil ` on error
142+ - ` string ` : Error message if merging fails
143+
144+ ** Merge Strategies:**
145+ - ` "override" ` : Source values replace destination values (default behavior)
146+ - ` "append" ` : For arrays/slices, append source items to destination instead of replacing
147+
148+ ** Example:**
149+ ``` lua
150+ local base = {
151+ server = {
152+ host = " localhost"
153+ port = 8080 ,
154+ ssl = {enabled = false }
155+ },
156+ features = {" auth" " logging"
157+ }
158+
159+ local override = {
160+ server = {
161+ host = " 0.0.0.0"
162+ ssl = {enabled = true , cert = " prod.crt"
163+ },
164+ features = {" metrics"
165+ }
166+
167+ -- Override merge (default)
168+ local merged = utils .merge (base , override )
169+ -- Result: server.host = "0.0.0.0", features = {"metrics"}
170+
171+ -- Append merge for arrays
172+ local appended = utils .merge (base , override , " append"
173+ -- Result: features = {"auth", "logging", "metrics"}
174+ ```
175+
176+ #### splitString
177+
178+ ``` lua
179+ utils .splitString (string , delimiter ) -> [string ]
180+ ```
181+
182+ Splits a string into an array of substrings using the specified delimiter.
183+
184+ ** Parameters:**
185+ - ` string ` (string): The string to split
186+ - ` delimiter ` (string): The delimiter to split on
187+
188+ ** Returns:**
189+ - ` [string] ` : Array of string parts
190+
191+ ** Example:**
192+ ``` lua
193+ local path = " user/config/settings.json"
194+ local parts = utils .splitString (path , " /"
195+ -- Result: {"user", "config", "settings.json"}
196+
197+ local csv = " apple,banana,cherry"
198+ local fruits = utils .splitString (csv , " ,"
199+ -- Result: {"apple", "banana", "cherry"}
200+
201+ values [" pathParts" = parts
202+ values [" fruits" = fruits
203+ ```
204+
205+ #### pathJoin
206+
207+ ``` lua
208+ utils .pathJoin (parts ) -> string
209+ ```
210+
211+ Joins an array of path components into a single path using the OS-appropriate path separator.
212+
213+ ** Parameters:**
214+ - ` parts ` (table): Array of path components as strings
215+
216+ ** Returns:**
217+ - ` string ` : Joined path
218+
219+ ** Example:**
220+ ``` lua
221+ local pathParts = {" user" " config" " settings.json"
222+ local fullPath = utils .pathJoin (pathParts )
223+ -- Result: "user/config/settings.json" (Unix) or "user\config\settings.json" (Windows)
224+
225+ -- Useful for building file paths dynamically
226+ local baseDir = " templates"
227+ local category = " emails"
228+ local filename = " welcome.html"
229+ local templatePath = utils .pathJoin ({baseDir , category , filename })
230+ -- Result: "templates/emails/welcome.html"
231+
232+ values [" templatePath" = templatePath
233+ valuesFiles = {templatePath }
234+ ```
235+
236+ ## Error Handling
237+
238+ All functions return errors in a consistent format:
239+ - File operations return ` nil ` and error message on failure
240+ - Encoding operations return ` nil ` and error message on failure
241+ - Path security violations return descriptive error messages
242+ - Merge operations return ` nil ` and error message on failure
243+
244+ When running Lua code from Go using GopherLua, safe error handling is important to prevent your application from
245+ panicking due to unhandled Lua runtime errors. What is ` pcall ` in Lua? The ` pcall ` stands for ` protected call ` .
246+
247+ ``` lua
248+ ok , result = pcall (function ()
249+ error (" fail"
250+ end )
251+ ```
252+ - ok: true if no error occurred, false otherwise
253+
254+ - result: the function’s return value or the error message
255+
256+ This prevents Lua from throwing a hard error that would propagate up and crash the engine.
257+
258+ ### Example
259+ Simple Error Handling and Throwing Example
260+
261+ ``` lua
262+
263+ values = values or {}
264+ valuesFiles = valuesFiles or {}
265+
266+ -- Example 1: Basic Error Throwing
267+ function validatePort (port )
268+ if not port then
269+ error (" Port is required"
270+ end
271+
272+ if type (port ) ~= " number" then
273+ error (" Port must be a number, got " .. type (port ))
274+ end
275+
276+ if port < 1 or port > 65535 then
277+ error (" Port must be between 1 and 65535, got " .. port )
278+ end
279+
280+ return true
281+ end
282+
283+ -- Example 2: Safe Error Handling with pcall
284+ function safeValidatePort (port )
285+ local success , result = pcall (validatePort , port )
286+ if success then
287+ return true , nil -- Valid port
288+ else
289+ return false , result -- Invalid port with error message
290+ end
291+ end
292+
293+ -- Test different port values
294+ local testPorts = {8080 , " invalid" - 1 , 99999 , nil }
295+ local portResults = {}
296+
297+ for i , port in ipairs (testPorts ) do
298+ local isValid , errorMsg = safeValidatePort (port )
299+ table.insert (portResults , {
300+ port = port ,
301+ valid = isValid ,
302+ error = errorMsg
303+ })
304+ end
305+ ```
123306
124307## Basic Usage
125308
0 commit comments