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"
34 local tparser = require "luci.template.parser"
36 local getmetatable, setmetatable = getmetatable, setmetatable
37 local rawget, rawset, unpack = rawget, rawset, unpack
38 local tostring, type, assert = tostring, type, assert
39 local ipairs, pairs, next, loadstring = ipairs, pairs, next, loadstring
40 local require, pcall, xpcall = require, pcall, xpcall
41 local collectgarbage, get_memory_limit = collectgarbage, get_memory_limit
43 --- LuCI utility functions.
47 -- Pythonic string formatting extension
49 getmetatable("").__mod = function(a, b)
52 elseif type(b) == "table" then
53 for k, _ in pairs(b) do if type(b[k]) == "userdata" then b[k] = tostring(b[k]) end end
54 return a:format(unpack(b))
56 if type(b) == "userdata" then b = tostring(b) end
63 -- Class helper routines
66 -- Instantiates a class
67 local function _instantiate(class, ...)
68 local inst = setmetatable({}, {__index = class})
77 --- Create a Class object (Python-style object model).
78 -- The class object can be instantiated by calling itself.
79 -- Any class functions or shared parameters can be attached to this object.
80 -- Attaching a table to the class object makes this table shared between
81 -- all instances of this class. For object parameters use the __init__ function.
82 -- Classes can inherit member functions and values from a base class.
83 -- Class can be instantiated by calling them. All parameters will be passed
84 -- to the __init__ function of this class - if such a function exists.
85 -- The __init__ function must be used to set any object parameters that are not shared
86 -- with other objects of this class. Any return values will be ignored.
87 -- @param base The base class to inherit from (optional)
88 -- @return A class object
92 return setmetatable({}, {
93 __call = _instantiate,
98 --- Test whether the given object is an instance of the given class.
99 -- @param object Object instance
100 -- @param class Class object to test against
101 -- @return Boolean indicating whether the object is an instance
104 function instanceof(object, class)
105 local meta = getmetatable(object)
106 while meta and meta.__index do
107 if meta.__index == class then
110 meta = getmetatable(meta.__index)
117 -- Scope manipulation routines
123 __index = function(self, key)
124 local t = rawget(self, coxpt[coroutine.running()]
125 or coroutine.running() or 0)
129 __newindex = function(self, key, value)
130 local c = coxpt[coroutine.running()] or coroutine.running() or 0
131 if not rawget(self, c) then
132 rawset(self, c, { [key] = value })
134 rawget(self, c)[key] = value
139 --- Create a new or get an already existing thread local store associated with
140 -- the current active coroutine. A thread local store is private a table object
141 -- whose values can't be accessed from outside of the running coroutine.
142 -- @return Table value representing the corresponding thread local store
143 function threadlocal(tbl)
144 return setmetatable(tbl or {}, tl_meta)
149 -- Debugging routines
152 --- Write given object to stderr.
153 -- @param obj Value to write to stderr
154 -- @return Boolean indicating whether the write operation was successful
156 return io.stderr:write(tostring(obj) .. "\n")
159 --- Recursively dumps a table to stdout, useful for testing and debugging.
160 -- @param t Table value to dump
161 -- @param maxdepth Maximum depth
162 -- @return Always nil
163 function dumptable(t, maxdepth, i, seen)
165 seen = seen or setmetatable({}, {__mode="k"})
167 for k,v in pairs(t) do
168 perror(string.rep("\t", i) .. tostring(k) .. "\t" .. tostring(v))
169 if type(v) == "table" and (not maxdepth or i < maxdepth) then
172 dumptable(v, maxdepth, i+1, seen)
174 perror(string.rep("\t", i) .. "*** RECURSION ***")
182 -- String and data manipulation routines
185 --- Escapes all occurrences of the given character in given string.
186 -- @param s String value containing unescaped characters
187 -- @param c String value with character to escape (optional, defaults to "\")
188 -- @return String value with each occurrence of character escaped with "\"
189 function escape(s, c)
191 return s:gsub(c, "\\" .. c)
194 --- Create valid XML PCDATA from given string.
195 -- @param value String value containing the data to escape
196 -- @return String value containing the escaped data
197 function pcdata(value)
198 return value and tparser.sanitize_pcdata(tostring(value))
201 --- Strip HTML tags from given string.
202 -- @param value String containing the HTML text
203 -- @return String with HTML tags stripped of
204 function striptags(s)
205 return pcdata(tostring(s):gsub("</?[A-Za-z][A-Za-z0-9:_%-]*[^>]*>", " "):gsub("%s+", " "))
208 --- Splits given string on a defined separator sequence and return a table
209 -- containing the resulting substrings. The optional max parameter specifies
210 -- the number of bytes to process, regardless of the actual length of the given
211 -- string. The optional last parameter, regex, specifies whether the separator
212 -- sequence is interpreted as regular expression.
213 -- @param str String value containing the data to split up
214 -- @param pat String with separator pattern (optional, defaults to "\n")
215 -- @param max Maximum times to split (optional)
216 -- @param regex Boolean indicating whether to interpret the separator
217 -- pattern as regular expression (optional, default is false)
218 -- @return Table containing the resulting substrings
219 function split(str, pat, max, regex)
239 local s, e = str:find(pat, c, not regex)
241 if s and max < 0 then
244 t[#t+1] = str:sub(c, s and s - 1)
246 c = e and e + 1 or #str + 1
247 until not s or max < 0
252 --- Remove leading and trailing whitespace from given string value.
253 -- @param str String value containing whitespace padded data
254 -- @return String value with leading and trailing space removed
256 return (str:gsub("^%s*(.-)%s*$", "%1"))
259 --- Count the occurences of given substring in given string.
260 -- @param str String to search in
261 -- @param pattern String containing pattern to find
262 -- @return Number of found occurences
263 function cmatch(str, pat)
265 for _ in str:gmatch(pat) do count = count + 1 end
269 --- Return a matching iterator for the given value. The iterator will return
270 -- one token per invocation, the tokens are separated by whitespace. If the
271 -- input value is a table, it is transformed into a string first. A nil value
272 -- will result in a valid interator which aborts with the first invocation.
273 -- @param val The value to scan (table, string or nil)
274 -- @return Iterator which returns one token per call
276 if type(v) == "table" then
283 elseif type(v) == "number" or type(v) == "boolean" then
292 elseif type(v) == "userdata" or type(v) == "string" then
293 return tostring(v):gmatch("%S+")
296 return function() end
299 --- Parse certain units from the given string and return the canonical integer
300 -- value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
301 -- Recognized units are:
302 -- o "y" - one year (60*60*24*366)
303 -- o "m" - one month (60*60*24*31)
304 -- o "w" - one week (60*60*24*7)
305 -- o "d" - one day (60*60*24)
306 -- o "h" - one hour (60*60)
307 -- o "min" - one minute (60)
308 -- o "kb" - one kilobyte (1024)
309 -- o "mb" - one megabyte (1024*1024)
310 -- o "gb" - one gigabyte (1024*1024*1024)
311 -- o "kib" - one si kilobyte (1000)
312 -- o "mib" - one si megabyte (1000*1000)
313 -- o "gib" - one si gigabyte (1000*1000*1000)
314 -- @param ustr String containing a numerical value with trailing unit
315 -- @return Number containing the canonical value
316 function parse_units(ustr)
323 y = 60 * 60 * 24 * 366,
324 m = 60 * 60 * 24 * 31,
325 w = 60 * 60 * 24 * 7,
333 gb = 1024 * 1024 * 1024,
335 -- storage sizes (si)
338 gib = 1000 * 1000 * 1000
341 -- parse input string
342 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
344 local num = spec:gsub("[^0-9%.]+$","")
345 local spn = spec:gsub("^[0-9%.]+", "")
347 if map[spn] or map[spn:sub(1,1)] then
348 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
358 -- also register functions above in the central string class for convenience
359 string.escape = escape
360 string.pcdata = pcdata
361 string.striptags = striptags
364 string.cmatch = cmatch
365 string.parse_units = parse_units
368 --- Appends numerically indexed tables or single objects to a given table.
369 -- @param src Target table
370 -- @param ... Objects to insert
371 -- @return Target table
372 function append(src, ...)
373 for i, a in ipairs({...}) do
374 if type(a) == "table" then
375 for j, v in ipairs(a) do
385 --- Combines two or more numerically indexed tables and single objects into one table.
386 -- @param tbl1 Table value to combine
387 -- @param tbl2 Table value to combine
388 -- @param ... More tables to combine
389 -- @return Table value containing all values of given tables
390 function combine(...)
391 return append({}, ...)
394 --- Checks whether the given table contains the given value.
395 -- @param table Table value
396 -- @param value Value to search within the given table
397 -- @return Boolean indicating whether the given value occurs within table
398 function contains(table, value)
399 for k, v in pairs(table) do
407 --- Update values in given table with the values from the second given table.
408 -- Both table are - in fact - merged together.
409 -- @param t Table which should be updated
410 -- @param updates Table containing the values to update
411 -- @return Always nil
412 function update(t, updates)
413 for k, v in pairs(updates) do
418 --- Retrieve all keys of given associative table.
419 -- @param t Table to extract keys from
420 -- @return Sorted table containing the keys
424 for k, _ in kspairs(t) do
431 --- Clones the given object and return it's copy.
432 -- @param object Table value to clone
433 -- @param deep Boolean indicating whether to do recursive cloning
434 -- @return Cloned table value
435 function clone(object, deep)
438 for k, v in pairs(object) do
439 if deep and type(v) == "table" then
445 return setmetatable(copy, getmetatable(object))
449 --- Create a dynamic table which automatically creates subtables.
450 -- @return Dynamic Table
452 return setmetatable({}, { __index =
454 return rawget(tbl, key)
455 or rawget(rawset(tbl, key, dtable()), key)
461 -- Serialize the contents of a table value.
462 function _serialize_table(t, seen)
463 assert(not seen[t], "Recursion detected.")
470 for k, v in pairs(t) do
471 if type(k) ~= "number" or k < 1 or math.floor(k) ~= k or ( k - #t ) > 3 then
472 k = serialize_data(k, seen)
473 v = serialize_data(v, seen)
474 data = data .. ( #data > 0 and ", " or "" ) ..
475 '[' .. k .. '] = ' .. v
482 local v = serialize_data(t[i], seen)
483 idata = idata .. ( #idata > 0 and ", " or "" ) .. v
486 return idata .. ( #data > 0 and #idata > 0 and ", " or "" ) .. data
489 --- Recursively serialize given data to lua code, suitable for restoring
490 -- with loadstring().
491 -- @param val Value containing the data to serialize
492 -- @return String value containing the serialized code
495 function serialize_data(val, seen)
496 seen = seen or setmetatable({}, {__mode="k"})
500 elseif type(val) == "number" then
502 elseif type(val) == "string" then
504 elseif type(val) == "boolean" then
505 return val and "true" or "false"
506 elseif type(val) == "function" then
507 return "loadstring(%q)" % get_bytecode(val)
508 elseif type(val) == "table" then
509 return "{ " .. _serialize_table(val, seen) .. " }"
511 return '"[unhandled data type:' .. type(val) .. ']"'
515 --- Restore data previously serialized with serialize_data().
516 -- @param str String containing the data to restore
517 -- @return Value containing the restored data structure
518 -- @see serialize_data
520 function restore_data(str)
521 return loadstring("return " .. str)()
526 -- Byte code manipulation routines
529 --- Return the current runtime bytecode of the given data. The byte code
530 -- will be stripped before it is returned.
531 -- @param val Value to return as bytecode
532 -- @return String value containing the bytecode of the given data
533 function get_bytecode(val)
536 if type(val) == "function" then
537 code = string.dump(val)
539 code = string.dump( loadstring( "return " .. serialize_data(val) ) )
542 return code -- and strip_bytecode(code)
545 --- Strips unnescessary lua bytecode from given string. Information like line
546 -- numbers and debugging numbers will be discarded. Original version by
547 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
548 -- @param code String value containing the original lua byte code
549 -- @return String value containing the stripped lua byte code
550 function strip_bytecode(code)
551 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
554 subint = function(code, i, l)
557 val = val * 256 + code:byte(i + n - 1)
562 subint = function(code, i, l)
565 val = val * 256 + code:byte(i + n - 1)
571 local function strip_function(code)
572 local count, offset = subint(code, 1, size)
573 local stripped = { string.rep("\0", size) }
574 local dirty = offset + count
575 offset = offset + count + int * 2 + 4
576 offset = offset + int + subint(code, offset, int) * ins
577 count, offset = subint(code, offset, int)
580 t, offset = subint(code, offset, 1)
584 offset = offset + size + subint(code, offset, size)
586 offset = offset + num
587 elseif t == 254 or t == 9 then
588 offset = offset + lnum
591 count, offset = subint(code, offset, int)
592 stripped[#stripped+1] = code:sub(dirty, offset - 1)
594 local proto, off = strip_function(code:sub(offset, -1))
595 stripped[#stripped+1] = proto
596 offset = offset + off - 1
598 offset = offset + subint(code, offset, int) * int + int
599 count, offset = subint(code, offset, int)
601 offset = offset + subint(code, offset, size) + size + int * 2
603 count, offset = subint(code, offset, int)
605 offset = offset + subint(code, offset, size) + size
607 stripped[#stripped+1] = string.rep("\0", int * 3)
608 return table.concat(stripped), offset
611 return code:sub(1,12) .. strip_function(code:sub(13,-1))
616 -- Sorting iterator functions
619 function _sortiter( t, f )
622 for k, v in pairs(t) do
628 table.sort( keys, f )
632 if _pos <= #keys then
633 return keys[_pos], t[keys[_pos]]
638 --- Return a key, value iterator which returns the values sorted according to
639 -- the provided callback function.
640 -- @param t The table to iterate
641 -- @param f A callback function to decide the order of elements
642 -- @return Function value containing the corresponding iterator
644 return _sortiter( t, f )
647 --- Return a key, value iterator for the given table.
648 -- The table pairs are sorted by key.
649 -- @param t The table to iterate
650 -- @return Function value containing the corresponding iterator
652 return _sortiter( t )
655 --- Return a key, value iterator for the given table.
656 -- The table pairs are sorted by value.
657 -- @param t The table to iterate
658 -- @return Function value containing the corresponding iterator
660 return _sortiter( t, function (a,b) return t[a] < t[b] end )
665 -- System utility functions
668 --- Test whether the current system is operating in big endian mode.
669 -- @return Boolean value indicating whether system is big endian
671 return string.byte(string.dump(function() end), 7) == 0
674 --- Execute given commandline and gather stdout.
675 -- @param command String containing command to execute
676 -- @return String containing the command's stdout
677 function exec(command)
678 local pp = io.popen(command)
679 local data = pp:read("*a")
685 --- Return a line-buffered iterator over the output of given command.
686 -- @param command String containing the command to execute
688 function execi(command)
689 local pp = io.popen(command)
691 return pp and function()
692 local line = pp:read()
703 function execl(command)
704 local pp = io.popen(command)
710 if (line == nil) then break end
718 --- Returns the absolute path to LuCI base directory.
719 -- @return String containing the directory path
721 return require "nixio.fs".dirname(ldebug.__file__)
726 -- Coroutine safe xpcall and pcall versions modified for Luci
728 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
730 -- Copyright © 2005 Kepler Project.
731 -- Permission is hereby granted, free of charge, to any person obtaining a
732 -- copy of this software and associated documentation files (the "Software"),
733 -- to deal in the Software without restriction, including without limitation
734 -- the rights to use, copy, modify, merge, publish, distribute, sublicense,
735 -- and/or sell copies of the Software, and to permit persons to whom the
736 -- Software is furnished to do so, subject to the following conditions:
738 -- The above copyright notice and this permission notice shall be
739 -- included in all copies or substantial portions of the Software.
741 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
742 -- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
743 -- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
744 -- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
745 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
746 -- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
747 -- OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
749 local performResume, handleReturnValue
750 local oldpcall, oldxpcall = pcall, xpcall
752 setmetatable(coxpt, {__mode = "kv"})
754 -- Identity function for copcall
755 local function copcall_id(trace, ...)
759 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
760 -- @param f Lua function to be called protected
761 -- @param err Custom error handler
762 -- @param ... Parameters passed to the function
763 -- @return A boolean whether the function call succeeded and the return
764 -- values of either the function or the error handler
765 function coxpcall(f, err, ...)
766 local res, co = oldpcall(coroutine.create, f)
769 local newf = function() return f(unpack(params)) end
770 co = coroutine.create(newf)
772 local c = coroutine.running()
773 coxpt[co] = coxpt[c] or c or 0
775 return performResume(err, co, ...)
778 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
779 -- @param f Lua function to be called protected
780 -- @param ... Parameters passed to the function
781 -- @return A boolean whether the function call succeeded and the returns
782 -- values of the function or the error object
783 function copcall(f, ...)
784 return coxpcall(f, copcall_id, ...)
787 -- Handle return value of protected call
788 function handleReturnValue(err, co, status, ...)
790 return false, err(debug.traceback(co, (...)), ...)
793 if coroutine.status(co) ~= 'suspended' then
797 return performResume(err, co, coroutine.yield(...))
800 -- Resume execution of protected function call
801 function performResume(err, co, ...)
802 return handleReturnValue(err, co, coroutine.resume(co, ...))