5 Several common useful Lua functions
11 Copyright 2008 Steven Barth <steven@midlink.org>
13 Licensed under the Apache License, Version 2.0 (the "License");
14 you may not use this file except in compliance with the License.
15 You may obtain a copy of the License at
17 http://www.apache.org/licenses/LICENSE-2.0
19 Unless required by applicable law or agreed to in writing, software
20 distributed under the License is distributed on an "AS IS" BASIS,
21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 See the License for the specific language governing permissions and
23 limitations under the License.
27 -- LuCI utility functions.
28 module("luci.util", package.seeall)
31 -- Class helper routines
34 --- Creates a Class object (Python-style object model)
35 -- Creates a new class object which can be instantiated by calling itself.
36 -- Any class functions or shared parameters can be attached to this object.
37 -- Attaching a table to the class object makes this table shared between
38 -- all instances of this class. For object parameters use the __init__ function.
39 -- Classes can inherit member functions and values from a base class.
40 -- Class can be instantiated by calling them. All parameters will be passed
41 -- to the __init__ function of this class - if such a function exists.
42 -- The __init__ function must be used to set any object parameters that are not shared
43 -- with other objects of this class. Any return values will be ignored.
44 -- @param base The base class to inherit from (optional)
45 -- @return A class object
51 local create = function(class, ...)
53 setmetatable(inst, {__index = class})
56 local stat, err = copcall(inst.__init__, inst, ...)
65 local classmeta = {__call = create}
68 classmeta.__index = base
71 setmetatable(class, classmeta)
75 --- Test whether the given object is an instance of the given class.
76 -- @param object Object instance
77 -- @param class Class object to test against
78 -- @return Boolean indicating whether the object is an instance
81 function instanceof(object, class)
82 local meta = getmetatable(object)
83 while meta and meta.__index do
84 if meta.__index == class then
87 meta = getmetatable(meta.__index)
94 -- Scope manipulation routines
97 --- Replace a function scope with a shallow copy of itself.
98 -- This is useful if you want to get rid of several unwanted side effects
99 -- while changing the scope of a certain Lua function.
100 -- @param f Lua function
102 setfenv(f, clone(getfenv(f)))
105 --- Store given object associated with given key in the scope of a function.
106 -- @param f Lua function
107 -- @param key String value containg the key of the object to store
108 -- @param obj Object to store in the scope
109 -- @return Always nil
112 function extfenv(f, key, obj)
113 local scope = getfenv(f)
117 --- Extend the scope of a function with the contents of a table
118 -- @param f Lua function
119 -- @param key String value containg the key of the object to store
120 -- @param obj Object to store in the scope
121 -- @return Always nil
124 function updfenv(f, extscope)
125 update(getfenv(f), extscope)
128 --- Create a new or get an already existing thread local store associated with
129 -- the current active coroutine. A thread local store is private a table object
130 -- whose values can't be accessed from outside of the running coroutine.
131 -- @return Table value representing the corresponding thread local store
132 function threadlocal()
135 local function get(self, key)
136 local c = coroutine.running()
137 local thread = coxpt[c] or c or 0
138 if not rawget(self, thread) then
141 return rawget(self, thread)[key]
144 local function set(self, key, value)
145 local c = coroutine.running()
146 local thread = coxpt[c] or c or 0
147 if not rawget(self, thread) then
148 rawset(self, thread, {})
150 rawget(self, thread)[key] = value
153 setmetatable(tbl, {__index = get, __newindex = set, __mode = "k"})
160 -- Debugging routines
163 --- Write given object to stderr.
164 -- @param obj Value to write to stderr
165 -- @return Boolean indicating whether the write operation was successful
167 return io.stderr:write(tostring(obj) .. "\n")
170 --- Recursively dumps a table to stdout, useful for testing and debugging.
171 -- @param t Table value to dump
172 -- @param i Number of tabs to prepend to each line
173 -- @return Always nil
174 function dumptable(t, i)
176 for k,v in pairs(t) do
177 print(string.rep("\t", i) .. tostring(k), tostring(v))
178 if type(v) == "table" then
186 -- String and data manipulation routines
189 --- Escapes all occurences of the given character in given string.
190 -- @param s String value containing unescaped characters
191 -- @param c String value with character to escape (optional, defaults to "\")
192 -- @return String value with each occurence of character escaped with "\"
193 function escape(s, c)
195 return s:gsub(c, "\\" .. c)
198 --- Create valid XML PCDATA from given string.
199 -- @param value String value containing the data to escape
200 -- @return String value containing the escaped data
201 function pcdata(value)
202 value = value:gsub("&", "&")
203 value = value:gsub('"', """)
204 value = value:gsub("'", "'")
205 value = value:gsub("<", "<")
206 return value:gsub(">", ">")
209 --- Splits given string on a defined seperator sequence and return a table
210 -- containing the resulting substrings. The optional max parameter specifies
211 -- the number of bytes to process, regardless of the actual length of the given
212 -- string. The optional last parameter, regex, sepcifies whether the separator
213 -- sequence is interpreted as regular expression.
214 -- @param str String value containing the data to split up
215 -- @param pat String with separator pattern (optional, defaults to "\n")
216 -- @param max Num of bytes to process (optional, default is string length)
217 -- @param regexp Boolean indicating whether to interprete the separator
218 -- pattern as regular expression (optional, default is false)
219 -- @return Table containing the resulting substrings
220 function split(str, pat, max, regex)
240 local s, e = str:find(pat, c, not regex)
242 if s and max < 0 then
243 table.insert(t, str:sub(c))
245 table.insert(t, str:sub(c, s and s - 1))
247 c = e and e + 1 or #str + 1
248 until not s or max < 0
253 --- Remove leading and trailing whitespace from given string value.
254 -- @param str String value containing whitespace padded data
255 -- @return String value with leading and trailing space removed
257 local s = str:gsub("^%s*(.-)%s*$", "%1")
261 --- Parse certain units from the given string and return the canonical integer
262 -- value or 0 if the unit is unknown. Upper- or lowercase is irrelevant.
263 -- Recognized units are:
264 -- o "y" - one year (60*60*24*366)
265 -- o "m" - one month (60*60*24*31)
266 -- o "w" - one week (60*60*24*7)
267 -- o "d" - one day (60*60*24)
268 -- o "h" - one hour (60*60)
269 -- o "min" - one minute (60)
270 -- o "kb" - one kilobyte (1024)
271 -- o "mb" - one megabyte (1024*1024)
272 -- o "gb" - one gigabyte (1024*1024*1024)
273 -- o "kib" - one si kilobyte (1000)
274 -- o "mib" - one si megabyte (1000*1000)
275 -- o "gib" - one si gigabyte (1000*1000*1000)
276 -- @param ustr String containing a numerical value with trailing unit
277 -- @return Number containing the canonical value
278 function parse_units(ustr)
285 y = 60 * 60 * 24 * 366,
286 m = 60 * 60 * 24 * 31,
287 w = 60 * 60 * 24 * 7,
295 gb = 1024 * 1024 * 1024,
297 -- storage sizes (si)
300 gib = 1000 * 1000 * 1000
303 -- parse input string
304 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
306 local num = spec:gsub("[^0-9%.]+$","")
307 local spn = spec:gsub("^[0-9%.]+", "")
309 if map[spn] or map[spn:sub(1,1)] then
310 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
320 --- Combines two or more numerically indexed tables into one.
321 -- @param tbl1 Table value to combine
322 -- @param tbl2 Table value to combine
323 -- @param tblN More values to combine
324 -- @return Table value containing all values of given tables
325 function combine(...)
327 for i, a in ipairs(arg) do
328 for j, v in ipairs(a) do
329 table.insert(result, v)
335 --- Checks whether the given table contains the given value.
336 -- @param table Table value
337 -- @param value Value to search within the given table
338 -- @return Boolean indicating whether the given value occurs within table
339 function contains(table, value)
340 for k, v in pairs(table) do
348 --- Update values in given table with the values from the second given table.
349 -- Both table are - in fact - merged together.
350 -- @param t Table which should be updated
351 -- @param updates Table containing the values to update
352 -- @return Always nil
353 function update(t, updates)
354 for k, v in pairs(updates) do
359 --- Clones the given object and return it's copy.
360 -- @param object Table value to clone
361 -- @param deep Boolean indicating whether to do recursive cloning
362 -- @return Cloned table value
363 function clone(object, deep)
366 for k, v in pairs(object) do
367 if deep and type(v) == "table" then
373 setmetatable(copy, getmetatable(object))
378 -- Test whether the given table value is a numerically indexed table.
379 function _is_numeric_table(t)
380 local k = pairs(t)(t)
381 return ( tonumber(k) ~= nil )
384 -- Serialize the contents of a table value.
385 function _serialize_table(t)
387 if _is_numeric_table(t) then
388 for i, v in ipairs(t) do
389 v = serialize_data(v)
390 data = data .. ( #data > 0 and ", " or "" ) .. v
393 for k, v in pairs(t) do
394 k = serialize_data(k)
395 v = serialize_data(v)
396 data = data .. ( #data > 0 and "; " or "" ) ..
397 '[' .. k .. '] = ' .. v
403 --- Recursively serialize given data to lua code, suitable for restoring
404 -- with loadstring().
405 -- @param val Value containing the data to serialize
406 -- @return String value containing the serialized code
409 function serialize_data(val)
412 elseif type(val) == "number" then
414 elseif type(val) == "string" then
415 val = val:gsub("\\", "\\\\")
419 return '"' .. val .. '"'
420 elseif type(val) == "table" then
421 return "{ " .. _serialize_table(val) .. " }"
423 return '"[unhandled data type:' .. type(val) .. ']"'
427 --- Restore data previously serialized with serialize_data().
428 -- @param str String containing the data to restore
429 -- @return Value containing the restored data structure
430 -- @see serialize_data
432 function restore_data(str)
433 return loadstring("return " .. str)()
438 -- Byte code manipulation routines
441 --- Return the current runtime bytecode of the given data. The byte code
442 -- will be stripped before it is returned if the given value is a function.
443 -- @param val Value to return as bytecode
444 -- @return String value containing the bytecode of the given data
445 function get_bytecode(val)
446 if type(val) == "function" then
447 local code = string.dump(val)
448 return code and strip_bytecode(code)
450 return string.dump( loadstring( "return " .. serialize_data(val) ) )
454 --- Strips unnescessary lua bytecode from given string. Information like line
455 -- numbers and debugging numbers will be discarded. Original version by
456 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
457 -- @param code String value containing the original lua byte code
458 -- @return String value containing the stripped lua byte code
459 function strip_bytecode(code)
460 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
463 subint = function(code, i, l)
466 val = val * 256 + code:byte(i + n - 1)
471 subint = function(code, i, l)
474 val = val * 256 + code:byte(i + n - 1)
481 strip_function = function(code)
482 local count, offset = subint(code, 1, size)
483 local stripped, dirty = string.rep("\0", size), offset + count
484 offset = offset + count + int * 2 + 4
485 offset = offset + int + subint(code, offset, int) * ins
486 count, offset = subint(code, offset, int)
489 t, offset = subint(code, offset, 1)
493 offset = offset + size + subint(code, offset, size)
495 offset = offset + num
496 elseif t == 254 or t == 9 then
497 offset = offset + lnum
500 count, offset = subint(code, offset, int)
501 stripped = stripped .. code:sub(dirty, offset - 1)
503 local proto, off = strip_function(code:sub(offset, -1))
504 stripped, offset = stripped .. proto, offset + off - 1
506 offset = offset + subint(code, offset, int) * int + int
507 count, offset = subint(code, offset, int)
509 offset = offset + subint(code, offset, size) + size + int * 2
511 count, offset = subint(code, offset, int)
513 offset = offset + subint(code, offset, size) + size
515 stripped = stripped .. string.rep("\0", int * 3)
516 return stripped, offset
519 return code:sub(1,12) .. strip_function(code:sub(13,-1))
524 -- Sorting iterator functions
527 function _sortiter( t, f )
530 for k, v in pairs(t) do
531 table.insert( keys, k )
535 local _len = table.getn( keys )
537 table.sort( keys, f )
542 return keys[_pos], t[keys[_pos]]
547 --- Return a key, value iterator which returns the values sorted according to
548 -- the provided callback function.
549 -- @param t The table to iterate
550 -- @param f A callback function to decide the order of elements
551 -- @return Function value containing the corresponding iterator
553 return _sortiter( t, f )
556 --- Return a key, value iterator for the given table.
557 -- The table pairs are sorted by key.
558 -- @param t The table to iterate
559 -- @return Function value containing the corresponding iterator
561 return _sortiter( t )
564 --- Return a key, value iterator for the given table.
565 -- The table pairs are sorted by value.
566 -- @param t The table to iterate
567 -- @return Function value containing the corresponding iterator
569 return _sortiter( t, function (a,b) return t[a] < t[b] end )
574 -- Coroutine safe xpcall and pcall versions modified for Luci
576 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
579 local performResume, handleReturnValue
580 local oldpcall, oldxpcall = pcall, xpcall
582 setmetatable(coxpt, {__mode = "kv"})
584 -- Identity function for copcall
585 local function copcall_id(trace, ...)
589 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
590 -- @param f Lua function to be called protected
591 -- @param err Custom error handler
592 -- @param ... Parameters passed to the function
593 -- @return A boolean whether the function call succeeded and the return
594 -- values of either the function or the error handler
595 function coxpcall(f, err, ...)
596 local res, co = oldpcall(coroutine.create, f)
599 local newf = function() return f(unpack(params)) end
600 co = coroutine.create(newf)
602 local c = coroutine.running()
603 coxpt[co] = coxpt[c] or c or 0
605 return performResume(err, co, ...)
608 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
609 -- @param f Lua function to be called protected
610 -- @param ... Parameters passed to the function
611 -- @return A boolean whether the function call succeeded and the returns
612 -- values of the function or the error object
613 function copcall(f, ...)
614 return coxpcall(f, copcall_id, ...)
617 -- Handle return value of protected call
618 function handleReturnValue(err, co, status, ...)
620 return false, err(debug.traceback(co, (...)), ...)
622 if coroutine.status(co) == 'suspended' then
623 return performResume(err, co, coroutine.yield(...))
629 -- Resume execution of protected function call
630 function performResume(err, co, ...)
631 return handleReturnValue(err, co, coroutine.resume(co, ...))