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 -- Pythonic string formatting extension
33 getmetatable("").__mod = function(a, b)
36 elseif type(b) == "table" then
37 return a:format(unpack(b))
45 -- Class helper routines
48 --- Create a Class object (Python-style object model).
49 -- The class object can be instantiated by calling itself.
50 -- Any class functions or shared parameters can be attached to this object.
51 -- Attaching a table to the class object makes this table shared between
52 -- all instances of this class. For object parameters use the __init__ function.
53 -- Classes can inherit member functions and values from a base class.
54 -- Class can be instantiated by calling them. All parameters will be passed
55 -- to the __init__ function of this class - if such a function exists.
56 -- The __init__ function must be used to set any object parameters that are not shared
57 -- with other objects of this class. Any return values will be ignored.
58 -- @param base The base class to inherit from (optional)
59 -- @return A class object
65 local create = function(class, ...)
67 setmetatable(inst, {__index = class})
70 local stat, err = copcall(inst.__init__, inst, ...)
79 local classmeta = {__call = create}
82 classmeta.__index = base
85 setmetatable(class, classmeta)
89 --- Test whether the given object is an instance of the given class.
90 -- @param object Object instance
91 -- @param class Class object to test against
92 -- @return Boolean indicating whether the object is an instance
95 function instanceof(object, class)
96 local meta = getmetatable(object)
97 while meta and meta.__index do
98 if meta.__index == class then
101 meta = getmetatable(meta.__index)
108 -- Scope manipulation routines
111 --- Replace a function scope with a shallow copy of itself.
112 -- This is useful if you want to get rid of several unwanted side effects
113 -- while changing the scope of a certain Lua function.
114 -- @param f Lua function
116 setfenv(f, clone(getfenv(f)))
119 --- Store given object associated with given key in the scope of a function.
120 -- @param f Lua function
121 -- @param key String value containg the key of the object to store
122 -- @param obj Object to store in the scope
123 -- @return Always nil
126 function extfenv(f, key, obj)
127 local scope = getfenv(f)
131 --- Extend the scope of a function with the contents of a table
132 -- @param f Lua function
133 -- @param key String value containg the key of the object to store
134 -- @param obj Object to store in the scope
135 -- @return Always nil
138 function updfenv(f, extscope)
139 update(getfenv(f), extscope)
142 --- Create a new or get an already existing thread local store associated with
143 -- the current active coroutine. A thread local store is private a table object
144 -- whose values can't be accessed from outside of the running coroutine.
145 -- @return Table value representing the corresponding thread local store
146 function threadlocal()
149 local function get(self, key)
150 local c = coroutine.running()
151 local thread = coxpt[c] or c or 0
152 if not rawget(self, thread) then
155 return rawget(self, thread)[key]
158 local function set(self, key, value)
159 local c = coroutine.running()
160 local thread = coxpt[c] or c or 0
161 if not rawget(self, thread) then
162 rawset(self, thread, {})
164 rawget(self, thread)[key] = value
167 setmetatable(tbl, {__index = get, __newindex = set, __mode = "k"})
174 -- Debugging routines
177 --- Write given object to stderr.
178 -- @param obj Value to write to stderr
179 -- @return Boolean indicating whether the write operation was successful
181 return io.stderr:write(tostring(obj) .. "\n")
184 --- Recursively dumps a table to stdout, useful for testing and debugging.
185 -- @param t Table value to dump
186 -- @param maxdepth Maximum depth
187 -- @return Always nil
188 function dumptable(t, maxdepth, i, seen)
190 seen = seen or setmetatable({}, {__mode="k"})
192 for k,v in pairs(t) do
193 perror(string.rep("\t", i) .. tostring(k) .. "\t" .. tostring(v))
194 if type(v) == "table" and (not maxdepth or i < maxdepth) then
197 dumptable(v, maxdepth, i+1, seen)
199 perror(string.rep("\t", i) .. "*** RECURSION ***")
207 -- String and data manipulation routines
210 --- Escapes all occurrences of the given character in given string.
211 -- @param s String value containing unescaped characters
212 -- @param c String value with character to escape (optional, defaults to "\")
213 -- @return String value with each occurrence of character escaped with "\"
214 function escape(s, c)
216 return s:gsub(c, "\\" .. c)
219 --- Create valid XML PCDATA from given string.
220 -- @param value String value containing the data to escape
221 -- @return String value containing the escaped data
222 function pcdata(value)
223 if not value then return end
224 value = tostring(value)
225 value = value:gsub("&", "&")
226 value = value:gsub('"', """)
227 value = value:gsub("'", "'")
228 value = value:gsub("<", "<")
229 return value:gsub(">", ">")
232 --- Strip HTML tags from given string.
233 -- @param value String containing the HTML text
234 -- @return String with HTML tags stripped of
235 function striptags(s)
236 return pcdata(s:gsub("</?[A-Za-z][A-Za-z0-9:_%-]*[^>]*>", " "):gsub("%s+", " "))
239 --- Splits given string on a defined separator sequence and return a table
240 -- containing the resulting substrings. The optional max parameter specifies
241 -- the number of bytes to process, regardless of the actual length of the given
242 -- string. The optional last parameter, regex, specifies whether the separator
243 -- sequence is interpreted as regular expression.
244 -- @param str String value containing the data to split up
245 -- @param pat String with separator pattern (optional, defaults to "\n")
246 -- @param max Maximum times to split (optional)
247 -- @param regex Boolean indicating whether to interpret the separator
248 -- pattern as regular expression (optional, default is false)
249 -- @return Table containing the resulting substrings
250 function split(str, pat, max, regex)
270 local s, e = str:find(pat, c, not regex)
272 if s and max < 0 then
273 table.insert(t, str:sub(c))
275 table.insert(t, str:sub(c, s and s - 1))
277 c = e and e + 1 or #str + 1
278 until not s or max < 0
283 --- Remove leading and trailing whitespace from given string value.
284 -- @param str String value containing whitespace padded data
285 -- @return String value with leading and trailing space removed
287 local s = str:gsub("^%s*(.-)%s*$", "%1")
291 --- Parse certain units from the given string and return the canonical integer
292 -- value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
293 -- Recognized units are:
294 -- o "y" - one year (60*60*24*366)
295 -- o "m" - one month (60*60*24*31)
296 -- o "w" - one week (60*60*24*7)
297 -- o "d" - one day (60*60*24)
298 -- o "h" - one hour (60*60)
299 -- o "min" - one minute (60)
300 -- o "kb" - one kilobyte (1024)
301 -- o "mb" - one megabyte (1024*1024)
302 -- o "gb" - one gigabyte (1024*1024*1024)
303 -- o "kib" - one si kilobyte (1000)
304 -- o "mib" - one si megabyte (1000*1000)
305 -- o "gib" - one si gigabyte (1000*1000*1000)
306 -- @param ustr String containing a numerical value with trailing unit
307 -- @return Number containing the canonical value
308 function parse_units(ustr)
315 y = 60 * 60 * 24 * 366,
316 m = 60 * 60 * 24 * 31,
317 w = 60 * 60 * 24 * 7,
325 gb = 1024 * 1024 * 1024,
327 -- storage sizes (si)
330 gib = 1000 * 1000 * 1000
333 -- parse input string
334 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
336 local num = spec:gsub("[^0-9%.]+$","")
337 local spn = spec:gsub("^[0-9%.]+", "")
339 if map[spn] or map[spn:sub(1,1)] then
340 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
350 --- Combines two or more numerically indexed tables into one.
351 -- @param tbl1 Table value to combine
352 -- @param tbl2 Table value to combine
353 -- @param ... More tables to combine
354 -- @return Table value containing all values of given tables
355 function combine(...)
357 for i, a in ipairs(arg) do
358 for j, v in ipairs(a) do
359 table.insert(result, v)
365 --- Checks whether the given table contains the given value.
366 -- @param table Table value
367 -- @param value Value to search within the given table
368 -- @return Boolean indicating whether the given value occurs within table
369 function contains(table, value)
370 for k, v in pairs(table) do
378 --- Update values in given table with the values from the second given table.
379 -- Both table are - in fact - merged together.
380 -- @param t Table which should be updated
381 -- @param updates Table containing the values to update
382 -- @return Always nil
383 function update(t, updates)
384 for k, v in pairs(updates) do
389 --- Retrieve all keys of given associative table.
390 -- @param t Table to extract keys from
391 -- @return Sorted table containing the keys
395 for k, _ in kspairs(t) do
396 table.insert( keys, k )
402 --- Clones the given object and return it's copy.
403 -- @param object Table value to clone
404 -- @param deep Boolean indicating whether to do recursive cloning
405 -- @return Cloned table value
406 function clone(object, deep)
409 for k, v in pairs(object) do
410 if deep and type(v) == "table" then
416 setmetatable(copy, getmetatable(object))
422 --- Create a dynamic table which automatically creates subtables.
423 -- @return Dynamic Table
425 return setmetatable({}, { __index =
427 return rawget(tbl, key)
428 or rawget(rawset(tbl, key, dtable()), key)
434 -- Serialize the contents of a table value.
435 function _serialize_table(t, seen)
436 assert(not seen[t], "Recursion detected.")
443 for k, v in pairs(t) do
444 if type(k) ~= "number" or k < 1 or math.floor(k) ~= k or ( k - #t ) > 3 then
445 k = serialize_data(k, seen)
446 v = serialize_data(v, seen)
447 data = data .. ( #data > 0 and ", " or "" ) ..
448 '[' .. k .. '] = ' .. v
455 local v = serialize_data(t[i], seen)
456 idata = idata .. ( #idata > 0 and ", " or "" ) .. v
459 return idata .. ( #data > 0 and #idata > 0 and ", " or "" ) .. data
462 --- Recursively serialize given data to lua code, suitable for restoring
463 -- with loadstring().
464 -- @param val Value containing the data to serialize
465 -- @return String value containing the serialized code
468 function serialize_data(val, seen)
469 seen = seen or setmetatable({}, {__mode="k"})
473 elseif type(val) == "number" then
475 elseif type(val) == "string" then
476 return string.format("%q", val)
477 elseif type(val) == "boolean" then
478 return val and "true" or "false"
479 elseif type(val) == "function" then
480 return string.format("loadstring(%q)", get_bytecode(val))
481 elseif type(val) == "table" then
482 return "{ " .. _serialize_table(val, seen) .. " }"
484 return '"[unhandled data type:' .. type(val) .. ']"'
488 --- Restore data previously serialized with serialize_data().
489 -- @param str String containing the data to restore
490 -- @return Value containing the restored data structure
491 -- @see serialize_data
493 function restore_data(str)
494 return loadstring("return " .. str)()
499 -- Byte code manipulation routines
502 --- Return the current runtime bytecode of the given data. The byte code
503 -- will be stripped before it is returned.
504 -- @param val Value to return as bytecode
505 -- @return String value containing the bytecode of the given data
506 function get_bytecode(val)
509 if type(val) == "function" then
510 code = string.dump(val)
512 code = string.dump( loadstring( "return " .. serialize_data(val) ) )
515 return code and strip_bytecode(code)
518 --- Strips unnescessary lua bytecode from given string. Information like line
519 -- numbers and debugging numbers will be discarded. Original version by
520 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
521 -- @param code String value containing the original lua byte code
522 -- @return String value containing the stripped lua byte code
523 function strip_bytecode(code)
524 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
527 subint = function(code, i, l)
530 val = val * 256 + code:byte(i + n - 1)
535 subint = function(code, i, l)
538 val = val * 256 + code:byte(i + n - 1)
545 strip_function = function(code)
546 local count, offset = subint(code, 1, size)
547 local stripped, dirty = string.rep("\0", size), offset + count
548 offset = offset + count + int * 2 + 4
549 offset = offset + int + subint(code, offset, int) * ins
550 count, offset = subint(code, offset, int)
553 t, offset = subint(code, offset, 1)
557 offset = offset + size + subint(code, offset, size)
559 offset = offset + num
560 elseif t == 254 or t == 9 then
561 offset = offset + lnum
564 count, offset = subint(code, offset, int)
565 stripped = stripped .. code:sub(dirty, offset - 1)
567 local proto, off = strip_function(code:sub(offset, -1))
568 stripped, offset = stripped .. proto, offset + off - 1
570 offset = offset + subint(code, offset, int) * int + int
571 count, offset = subint(code, offset, int)
573 offset = offset + subint(code, offset, size) + size + int * 2
575 count, offset = subint(code, offset, int)
577 offset = offset + subint(code, offset, size) + size
579 stripped = stripped .. string.rep("\0", int * 3)
580 return stripped, offset
583 return code:sub(1,12) .. strip_function(code:sub(13,-1))
588 -- Sorting iterator functions
591 function _sortiter( t, f )
594 for k, v in pairs(t) do
595 table.insert( keys, k )
599 local _len = table.getn( keys )
601 table.sort( keys, f )
606 return keys[_pos], t[keys[_pos]]
611 --- Return a key, value iterator which returns the values sorted according to
612 -- the provided callback function.
613 -- @param t The table to iterate
614 -- @param f A callback function to decide the order of elements
615 -- @return Function value containing the corresponding iterator
617 return _sortiter( t, f )
620 --- Return a key, value iterator for the given table.
621 -- The table pairs are sorted by key.
622 -- @param t The table to iterate
623 -- @return Function value containing the corresponding iterator
625 return _sortiter( t )
628 --- Return a key, value iterator for the given table.
629 -- The table pairs are sorted by value.
630 -- @param t The table to iterate
631 -- @return Function value containing the corresponding iterator
633 return _sortiter( t, function (a,b) return t[a] < t[b] end )
638 -- System utility functions
641 --- Test whether the current system is operating in big endian mode.
642 -- @return Boolean value indicating whether system is big endian
644 return string.byte(string.dump(function() end), 7) == 0
647 --- Execute given commandline and gather stdout.
648 -- @param command String containing command to execute
649 -- @return String containing the command's stdout
650 function exec(command)
651 local pp = io.popen(command)
652 local data = pp:read("*a")
658 --- Return a line-buffered iterator over the output of given command.
659 -- @param command String containing the command to execute
661 function execi(command)
662 local pp = io.popen(command)
664 return pp and function()
665 local line = pp:read()
676 function execl(command)
677 local pp = io.popen(command)
683 if (line == nil) then break end
684 table.insert(data, line)
691 --- Returns the absolute path to LuCI base directory.
692 -- @return String containing the directory path
694 return luci.fs.dirname(require("luci.debug").__file__)
699 -- Coroutine safe xpcall and pcall versions modified for Luci
701 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
703 -- Copyright © 2005 Kepler Project.
704 -- Permission is hereby granted, free of charge, to any person obtaining a
705 -- copy of this software and associated documentation files (the "Software"),
706 -- to deal in the Software without restriction, including without limitation
707 -- the rights to use, copy, modify, merge, publish, distribute, sublicense,
708 -- and/or sell copies of the Software, and to permit persons to whom the
709 -- Software is furnished to do so, subject to the following conditions:
711 -- The above copyright notice and this permission notice shall be
712 -- included in all copies or substantial portions of the Software.
714 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
715 -- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
716 -- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
717 -- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
718 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
719 -- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
720 -- OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
722 local performResume, handleReturnValue
723 local oldpcall, oldxpcall = pcall, xpcall
725 setmetatable(coxpt, {__mode = "kv"})
727 -- Identity function for copcall
728 local function copcall_id(trace, ...)
732 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
733 -- @param f Lua function to be called protected
734 -- @param err Custom error handler
735 -- @param ... Parameters passed to the function
736 -- @return A boolean whether the function call succeeded and the return
737 -- values of either the function or the error handler
738 function coxpcall(f, err, ...)
739 local res, co = oldpcall(coroutine.create, f)
742 local newf = function() return f(unpack(params)) end
743 co = coroutine.create(newf)
745 local c = coroutine.running()
746 coxpt[co] = coxpt[c] or c or 0
748 return performResume(err, co, ...)
751 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
752 -- @param f Lua function to be called protected
753 -- @param ... Parameters passed to the function
754 -- @return A boolean whether the function call succeeded and the returns
755 -- values of the function or the error object
756 function copcall(f, ...)
757 return coxpcall(f, copcall_id, ...)
760 -- Handle return value of protected call
761 function handleReturnValue(err, co, status, ...)
763 return false, err(debug.traceback(co, (...)), ...)
765 if coroutine.status(co) == 'suspended' then
766 return performResume(err, co, coroutine.yield(...))
772 -- Resume execution of protected function call
773 function performResume(err, co, ...)
774 return handleReturnValue(err, co, coroutine.resume(co, ...))