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 local io = require "io"
28 local math = require "math"
29 local table = require "table"
30 local debug = require "debug"
31 local ldebug = require "luci.debug"
32 local string = require "string"
33 local coroutine = require "coroutine"
35 local getmetatable, setmetatable = getmetatable, setmetatable
36 local rawget, rawset, unpack = rawget, rawset, unpack
37 local tostring, type, assert = tostring, type, assert
38 local ipairs, pairs, loadstring = ipairs, pairs, loadstring
39 local require, pcall, xpcall = require, pcall, xpcall
40 local collectgarbage, get_memory_limit = collectgarbage, get_memory_limit
42 --- LuCI utility functions.
46 -- Pythonic string formatting extension
48 getmetatable("").__mod = function(a, b)
51 elseif type(b) == "table" then
52 for k, _ in pairs(b) do if type(b[k]) == "userdata" then b[k] = tostring(b[k]) end end
53 return a:format(unpack(b))
55 if type(b) == "userdata" then b = tostring(b) end
62 -- Class helper routines
65 -- Instantiates a class
66 local function _instantiate(class, ...)
67 local inst = setmetatable({}, {__index = class})
76 --- Create a Class object (Python-style object model).
77 -- The class object can be instantiated by calling itself.
78 -- Any class functions or shared parameters can be attached to this object.
79 -- Attaching a table to the class object makes this table shared between
80 -- all instances of this class. For object parameters use the __init__ function.
81 -- Classes can inherit member functions and values from a base class.
82 -- Class can be instantiated by calling them. All parameters will be passed
83 -- to the __init__ function of this class - if such a function exists.
84 -- The __init__ function must be used to set any object parameters that are not shared
85 -- with other objects of this class. Any return values will be ignored.
86 -- @param base The base class to inherit from (optional)
87 -- @return A class object
91 return setmetatable({}, {
92 __call = _instantiate,
97 --- Test whether the given object is an instance of the given class.
98 -- @param object Object instance
99 -- @param class Class object to test against
100 -- @return Boolean indicating whether the object is an instance
103 function instanceof(object, class)
104 local meta = getmetatable(object)
105 while meta and meta.__index do
106 if meta.__index == class then
109 meta = getmetatable(meta.__index)
116 -- Scope manipulation routines
122 __index = function(self, key)
123 local t = rawget(self, coxpt[coroutine.running()]
124 or coroutine.running() or 0)
128 __newindex = function(self, key, value)
129 local c = coxpt[coroutine.running()] or coroutine.running() or 0
130 if not rawget(self, c) then
131 rawset(self, c, { [key] = value })
133 rawget(self, c)[key] = value
138 --- Create a new or get an already existing thread local store associated with
139 -- the current active coroutine. A thread local store is private a table object
140 -- whose values can't be accessed from outside of the running coroutine.
141 -- @return Table value representing the corresponding thread local store
142 function threadlocal(tbl)
143 return setmetatable(tbl or {}, tl_meta)
148 -- Debugging routines
151 --- Write given object to stderr.
152 -- @param obj Value to write to stderr
153 -- @return Boolean indicating whether the write operation was successful
155 return io.stderr:write(tostring(obj) .. "\n")
158 --- Recursively dumps a table to stdout, useful for testing and debugging.
159 -- @param t Table value to dump
160 -- @param maxdepth Maximum depth
161 -- @return Always nil
162 function dumptable(t, maxdepth, i, seen)
164 seen = seen or setmetatable({}, {__mode="k"})
166 for k,v in pairs(t) do
167 perror(string.rep("\t", i) .. tostring(k) .. "\t" .. tostring(v))
168 if type(v) == "table" and (not maxdepth or i < maxdepth) then
171 dumptable(v, maxdepth, i+1, seen)
173 perror(string.rep("\t", i) .. "*** RECURSION ***")
181 -- String and data manipulation routines
184 --- Escapes all occurrences of the given character in given string.
185 -- @param s String value containing unescaped characters
186 -- @param c String value with character to escape (optional, defaults to "\")
187 -- @return String value with each occurrence of character escaped with "\"
188 function escape(s, c)
190 return s:gsub(c, "\\" .. c)
193 --- Create valid XML PCDATA from given string.
194 -- @param value String value containing the data to escape
195 -- @return String value containing the escaped data
196 local function _pcdata_repl(c)
197 local i = string.byte(c)
199 if ( i >= 0x00 and i <= 0x08 ) or ( i >= 0x0B and i <= 0x0C ) or
200 ( i >= 0x0E and i <= 0x1F ) or ( i == 0x7F )
204 elseif ( i == 0x26 ) or ( i == 0x27 ) or ( i == 0x22 ) or
205 ( i == 0x3C ) or ( i == 0x3E )
207 return string.format("&#%i;", i)
213 function pcdata(value)
214 return value and tostring(value):gsub("[&\"'<>%c]", _pcdata_repl)
217 --- Strip HTML tags from given string.
218 -- @param value String containing the HTML text
219 -- @return String with HTML tags stripped of
220 function striptags(s)
221 return pcdata(tostring(s):gsub("</?[A-Za-z][A-Za-z0-9:_%-]*[^>]*>", " "):gsub("%s+", " "))
224 --- Splits given string on a defined separator sequence and return a table
225 -- containing the resulting substrings. The optional max parameter specifies
226 -- the number of bytes to process, regardless of the actual length of the given
227 -- string. The optional last parameter, regex, specifies whether the separator
228 -- sequence is interpreted as regular expression.
229 -- @param str String value containing the data to split up
230 -- @param pat String with separator pattern (optional, defaults to "\n")
231 -- @param max Maximum times to split (optional)
232 -- @param regex Boolean indicating whether to interpret the separator
233 -- pattern as regular expression (optional, default is false)
234 -- @return Table containing the resulting substrings
235 function split(str, pat, max, regex)
255 local s, e = str:find(pat, c, not regex)
257 if s and max < 0 then
260 t[#t+1] = str:sub(c, s and s - 1)
262 c = e and e + 1 or #str + 1
263 until not s or max < 0
268 --- Remove leading and trailing whitespace from given string value.
269 -- @param str String value containing whitespace padded data
270 -- @return String value with leading and trailing space removed
272 return (str:gsub("^%s*(.-)%s*$", "%1"))
275 --- Count the occurences of given substring in given string.
276 -- @param str String to search in
277 -- @param pattern String containing pattern to find
278 -- @return Number of found occurences
279 function cmatch(str, pat)
281 for _ in str:gmatch(pat) do count = count + 1 end
285 --- Return a matching iterator for the given value. The iterator will return
286 -- one token per invocation, the tokens are separated by whitespace. If the
287 -- input value is a table, it is transformed into a string first. A nil value
288 -- will result in a valid interator which aborts with the first invocation.
289 -- @param val The value to scan (table, string or nil)
290 -- @return Iterator which returns one token per call
294 elseif type(v) == "table" then
295 v = table.concat(v, " ")
298 return v:gmatch("%S+")
301 --- Parse certain units from the given string and return the canonical integer
302 -- value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
303 -- Recognized units are:
304 -- o "y" - one year (60*60*24*366)
305 -- o "m" - one month (60*60*24*31)
306 -- o "w" - one week (60*60*24*7)
307 -- o "d" - one day (60*60*24)
308 -- o "h" - one hour (60*60)
309 -- o "min" - one minute (60)
310 -- o "kb" - one kilobyte (1024)
311 -- o "mb" - one megabyte (1024*1024)
312 -- o "gb" - one gigabyte (1024*1024*1024)
313 -- o "kib" - one si kilobyte (1000)
314 -- o "mib" - one si megabyte (1000*1000)
315 -- o "gib" - one si gigabyte (1000*1000*1000)
316 -- @param ustr String containing a numerical value with trailing unit
317 -- @return Number containing the canonical value
318 function parse_units(ustr)
325 y = 60 * 60 * 24 * 366,
326 m = 60 * 60 * 24 * 31,
327 w = 60 * 60 * 24 * 7,
335 gb = 1024 * 1024 * 1024,
337 -- storage sizes (si)
340 gib = 1000 * 1000 * 1000
343 -- parse input string
344 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
346 local num = spec:gsub("[^0-9%.]+$","")
347 local spn = spec:gsub("^[0-9%.]+", "")
349 if map[spn] or map[spn:sub(1,1)] then
350 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
360 -- also register functions above in the central string class for convenience
361 string.escape = escape
362 string.pcdata = pcdata
363 string.striptags = striptags
366 string.cmatch = cmatch
367 string.parse_units = parse_units
370 --- Appends numerically indexed tables or single objects to a given table.
371 -- @param src Target table
372 -- @param ... Objects to insert
373 -- @return Target table
374 function append(src, ...)
375 for i, a in ipairs({...}) do
376 if type(a) == "table" then
377 for j, v in ipairs(a) do
387 --- Combines two or more numerically indexed tables and single objects into one table.
388 -- @param tbl1 Table value to combine
389 -- @param tbl2 Table value to combine
390 -- @param ... More tables to combine
391 -- @return Table value containing all values of given tables
392 function combine(...)
393 return append({}, ...)
396 --- Checks whether the given table contains the given value.
397 -- @param table Table value
398 -- @param value Value to search within the given table
399 -- @return Boolean indicating whether the given value occurs within table
400 function contains(table, value)
401 for k, v in pairs(table) do
409 --- Update values in given table with the values from the second given table.
410 -- Both table are - in fact - merged together.
411 -- @param t Table which should be updated
412 -- @param updates Table containing the values to update
413 -- @return Always nil
414 function update(t, updates)
415 for k, v in pairs(updates) do
420 --- Retrieve all keys of given associative table.
421 -- @param t Table to extract keys from
422 -- @return Sorted table containing the keys
426 for k, _ in kspairs(t) do
433 --- Clones the given object and return it's copy.
434 -- @param object Table value to clone
435 -- @param deep Boolean indicating whether to do recursive cloning
436 -- @return Cloned table value
437 function clone(object, deep)
440 for k, v in pairs(object) do
441 if deep and type(v) == "table" then
447 return setmetatable(copy, getmetatable(object))
451 --- Create a dynamic table which automatically creates subtables.
452 -- @return Dynamic Table
454 return setmetatable({}, { __index =
456 return rawget(tbl, key)
457 or rawget(rawset(tbl, key, dtable()), key)
463 -- Serialize the contents of a table value.
464 function _serialize_table(t, seen)
465 assert(not seen[t], "Recursion detected.")
472 for k, v in pairs(t) do
473 if type(k) ~= "number" or k < 1 or math.floor(k) ~= k or ( k - #t ) > 3 then
474 k = serialize_data(k, seen)
475 v = serialize_data(v, seen)
476 data = data .. ( #data > 0 and ", " or "" ) ..
477 '[' .. k .. '] = ' .. v
484 local v = serialize_data(t[i], seen)
485 idata = idata .. ( #idata > 0 and ", " or "" ) .. v
488 return idata .. ( #data > 0 and #idata > 0 and ", " or "" ) .. data
491 --- Recursively serialize given data to lua code, suitable for restoring
492 -- with loadstring().
493 -- @param val Value containing the data to serialize
494 -- @return String value containing the serialized code
497 function serialize_data(val, seen)
498 seen = seen or setmetatable({}, {__mode="k"})
502 elseif type(val) == "number" then
504 elseif type(val) == "string" then
506 elseif type(val) == "boolean" then
507 return val and "true" or "false"
508 elseif type(val) == "function" then
509 return "loadstring(%q)" % get_bytecode(val)
510 elseif type(val) == "table" then
511 return "{ " .. _serialize_table(val, seen) .. " }"
513 return '"[unhandled data type:' .. type(val) .. ']"'
517 --- Restore data previously serialized with serialize_data().
518 -- @param str String containing the data to restore
519 -- @return Value containing the restored data structure
520 -- @see serialize_data
522 function restore_data(str)
523 return loadstring("return " .. str)()
528 -- Byte code manipulation routines
531 --- Return the current runtime bytecode of the given data. The byte code
532 -- will be stripped before it is returned.
533 -- @param val Value to return as bytecode
534 -- @return String value containing the bytecode of the given data
535 function get_bytecode(val)
538 if type(val) == "function" then
539 code = string.dump(val)
541 code = string.dump( loadstring( "return " .. serialize_data(val) ) )
544 return code -- and strip_bytecode(code)
547 --- Strips unnescessary lua bytecode from given string. Information like line
548 -- numbers and debugging numbers will be discarded. Original version by
549 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
550 -- @param code String value containing the original lua byte code
551 -- @return String value containing the stripped lua byte code
552 function strip_bytecode(code)
553 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
556 subint = function(code, i, l)
559 val = val * 256 + code:byte(i + n - 1)
564 subint = function(code, i, l)
567 val = val * 256 + code:byte(i + n - 1)
573 local function strip_function(code)
574 local count, offset = subint(code, 1, size)
575 local stripped = { string.rep("\0", size) }
576 local dirty = offset + count
577 offset = offset + count + int * 2 + 4
578 offset = offset + int + subint(code, offset, int) * ins
579 count, offset = subint(code, offset, int)
582 t, offset = subint(code, offset, 1)
586 offset = offset + size + subint(code, offset, size)
588 offset = offset + num
589 elseif t == 254 or t == 9 then
590 offset = offset + lnum
593 count, offset = subint(code, offset, int)
594 stripped[#stripped+1] = code:sub(dirty, offset - 1)
596 local proto, off = strip_function(code:sub(offset, -1))
597 stripped[#stripped+1] = proto
598 offset = offset + off - 1
600 offset = offset + subint(code, offset, int) * int + int
601 count, offset = subint(code, offset, int)
603 offset = offset + subint(code, offset, size) + size + int * 2
605 count, offset = subint(code, offset, int)
607 offset = offset + subint(code, offset, size) + size
609 stripped[#stripped+1] = string.rep("\0", int * 3)
610 return table.concat(stripped), offset
613 return code:sub(1,12) .. strip_function(code:sub(13,-1))
618 -- Sorting iterator functions
621 function _sortiter( t, f )
624 for k, v in pairs(t) do
630 table.sort( keys, f )
634 if _pos <= #keys then
635 return keys[_pos], t[keys[_pos]]
640 --- Return a key, value iterator which returns the values sorted according to
641 -- the provided callback function.
642 -- @param t The table to iterate
643 -- @param f A callback function to decide the order of elements
644 -- @return Function value containing the corresponding iterator
646 return _sortiter( t, f )
649 --- Return a key, value iterator for the given table.
650 -- The table pairs are sorted by key.
651 -- @param t The table to iterate
652 -- @return Function value containing the corresponding iterator
654 return _sortiter( t )
657 --- Return a key, value iterator for the given table.
658 -- The table pairs are sorted by value.
659 -- @param t The table to iterate
660 -- @return Function value containing the corresponding iterator
662 return _sortiter( t, function (a,b) return t[a] < t[b] end )
667 -- System utility functions
670 --- Test whether the current system is operating in big endian mode.
671 -- @return Boolean value indicating whether system is big endian
673 return string.byte(string.dump(function() end), 7) == 0
676 --- Execute given commandline and gather stdout.
677 -- @param command String containing command to execute
678 -- @return String containing the command's stdout
679 function exec(command)
680 local pp = io.popen(command)
681 local data = pp:read("*a")
687 --- Return a line-buffered iterator over the output of given command.
688 -- @param command String containing the command to execute
690 function execi(command)
691 local pp = io.popen(command)
693 return pp and function()
694 local line = pp:read()
705 function execl(command)
706 local pp = io.popen(command)
712 if (line == nil) then break end
720 --- Returns the absolute path to LuCI base directory.
721 -- @return String containing the directory path
723 return require "nixio.fs".dirname(ldebug.__file__)
728 -- Coroutine safe xpcall and pcall versions modified for Luci
730 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
732 -- Copyright © 2005 Kepler Project.
733 -- Permission is hereby granted, free of charge, to any person obtaining a
734 -- copy of this software and associated documentation files (the "Software"),
735 -- to deal in the Software without restriction, including without limitation
736 -- the rights to use, copy, modify, merge, publish, distribute, sublicense,
737 -- and/or sell copies of the Software, and to permit persons to whom the
738 -- Software is furnished to do so, subject to the following conditions:
740 -- The above copyright notice and this permission notice shall be
741 -- included in all copies or substantial portions of the Software.
743 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
744 -- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
745 -- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
746 -- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
747 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
748 -- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
749 -- OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
751 local performResume, handleReturnValue
752 local oldpcall, oldxpcall = pcall, xpcall
754 setmetatable(coxpt, {__mode = "kv"})
756 -- Identity function for copcall
757 local function copcall_id(trace, ...)
761 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
762 -- @param f Lua function to be called protected
763 -- @param err Custom error handler
764 -- @param ... Parameters passed to the function
765 -- @return A boolean whether the function call succeeded and the return
766 -- values of either the function or the error handler
767 function coxpcall(f, err, ...)
768 local res, co = oldpcall(coroutine.create, f)
771 local newf = function() return f(unpack(params)) end
772 co = coroutine.create(newf)
774 local c = coroutine.running()
775 coxpt[co] = coxpt[c] or c or 0
777 return performResume(err, co, ...)
780 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
781 -- @param f Lua function to be called protected
782 -- @param ... Parameters passed to the function
783 -- @return A boolean whether the function call succeeded and the returns
784 -- values of the function or the error object
785 function copcall(f, ...)
786 return coxpcall(f, copcall_id, ...)
789 -- Handle return value of protected call
790 function handleReturnValue(err, co, status, arg1, arg2, arg3, arg4, arg5)
792 return false, err(debug.traceback(co, arg1), arg1, arg2, arg3, arg4, arg5)
795 if coroutine.status(co) ~= 'suspended' then
796 return true, arg1, arg2, arg3, arg4, arg5
799 return performResume(err, co, coroutine.yield(arg1, arg2, arg3, arg4, arg5))
802 -- Resume execution of protected function call
803 function performResume(err, co, arg1, arg2, arg3, arg4, arg5)
804 return handleReturnValue(err, co, coroutine.resume(co, arg1, arg2, arg3, arg4, arg5))