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 cutil = require "luci.cutil"
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, loadstring = ipairs, pairs, loadstring
40 local require, pcall, xpcall = require, pcall, xpcall
42 --- LuCI utility functions.
46 -- Pythonic string formatting extension
48 getmetatable("").__mod = function(a, b)
51 elseif type(b) == "table" then
52 return a:format(unpack(b))
60 -- Class helper routines
63 -- Instantiates a class
64 local function _instantiate(class, ...)
65 local inst = setmetatable({}, {__index = class})
74 --- Create a Class object (Python-style object model).
75 -- The class object can be instantiated by calling itself.
76 -- Any class functions or shared parameters can be attached to this object.
77 -- Attaching a table to the class object makes this table shared between
78 -- all instances of this class. For object parameters use the __init__ function.
79 -- Classes can inherit member functions and values from a base class.
80 -- Class can be instantiated by calling them. All parameters will be passed
81 -- to the __init__ function of this class - if such a function exists.
82 -- The __init__ function must be used to set any object parameters that are not shared
83 -- with other objects of this class. Any return values will be ignored.
84 -- @param base The base class to inherit from (optional)
85 -- @return A class object
89 return setmetatable({}, {
90 __call = _instantiate,
95 --- Test whether the given object is an instance of the given class.
96 -- @param object Object instance
97 -- @param class Class object to test against
98 -- @return Boolean indicating whether the object is an instance
101 function instanceof(object, class)
102 local meta = getmetatable(object)
103 while meta and meta.__index do
104 if meta.__index == class then
107 meta = getmetatable(meta.__index)
114 -- Scope manipulation routines
117 --- Create a new or get an already existing thread local store associated with
118 -- the current active coroutine. A thread local store is private a table object
119 -- whose values can't be accessed from outside of the running coroutine.
120 -- @return Table value representing the corresponding thread local store
121 function threadlocal()
124 local function get(self, key)
125 local c = coroutine.running()
126 local thread = coxpt[c] or c or 0
127 if not rawget(self, thread) then
130 return rawget(self, thread)[key]
133 local function set(self, key, value)
134 local c = coroutine.running()
135 local thread = coxpt[c] or c or 0
136 if not rawget(self, thread) then
137 rawset(self, thread, {})
139 rawget(self, thread)[key] = value
142 setmetatable(tbl, {__index = get, __newindex = set, __mode = "k"})
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 local _pcdata_repl = {
205 function pcdata(value)
206 return value and tostring(value):gsub("[&\"'<>]", _pcdata_repl)
209 --- Strip HTML tags from given string.
210 -- @param value String containing the HTML text
211 -- @return String with HTML tags stripped of
212 function striptags(s)
213 return pcdata(s:gsub("</?[A-Za-z][A-Za-z0-9:_%-]*[^>]*>", " "):gsub("%s+", " "))
216 --- Splits given string on a defined separator sequence and return a table
217 -- containing the resulting substrings. The optional max parameter specifies
218 -- the number of bytes to process, regardless of the actual length of the given
219 -- string. The optional last parameter, regex, specifies whether the separator
220 -- sequence is interpreted as regular expression.
221 -- @param str String value containing the data to split up
222 -- @param pat String with separator pattern (optional, defaults to "\n")
223 -- @param max Maximum times to split (optional)
224 -- @param regex Boolean indicating whether to interpret the separator
225 -- pattern as regular expression (optional, default is false)
226 -- @return Table containing the resulting substrings
227 function split(str, pat, max, regex)
247 local s, e = str:find(pat, c, not regex)
249 if s and max < 0 then
252 t[#t+1] = str:sub(c, s and s - 1)
254 c = e and e + 1 or #str + 1
255 until not s or max < 0
260 --- Remove leading and trailing whitespace from given string value.
261 -- @param str String value containing whitespace padded data
262 -- @return String value with leading and trailing space removed
264 return (str:gsub("^%s*(.-)%s*$", "%1"))
267 --- Count the occurences of given substring in given string.
268 -- @param str String to search in
269 -- @param pattern String containing pattern to find
270 -- @return Number of found occurences
271 function cmatch(str, pat)
273 for _ in str:gmatch(pat) do count = count + 1 end
277 --- Parse certain units from the given string and return the canonical integer
278 -- value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
279 -- Recognized units are:
280 -- o "y" - one year (60*60*24*366)
281 -- o "m" - one month (60*60*24*31)
282 -- o "w" - one week (60*60*24*7)
283 -- o "d" - one day (60*60*24)
284 -- o "h" - one hour (60*60)
285 -- o "min" - one minute (60)
286 -- o "kb" - one kilobyte (1024)
287 -- o "mb" - one megabyte (1024*1024)
288 -- o "gb" - one gigabyte (1024*1024*1024)
289 -- o "kib" - one si kilobyte (1000)
290 -- o "mib" - one si megabyte (1000*1000)
291 -- o "gib" - one si gigabyte (1000*1000*1000)
292 -- @param ustr String containing a numerical value with trailing unit
293 -- @return Number containing the canonical value
294 function parse_units(ustr)
301 y = 60 * 60 * 24 * 366,
302 m = 60 * 60 * 24 * 31,
303 w = 60 * 60 * 24 * 7,
311 gb = 1024 * 1024 * 1024,
313 -- storage sizes (si)
316 gib = 1000 * 1000 * 1000
319 -- parse input string
320 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
322 local num = spec:gsub("[^0-9%.]+$","")
323 local spn = spec:gsub("^[0-9%.]+", "")
325 if map[spn] or map[spn:sub(1,1)] then
326 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
336 -- also register functions above in the central string class for convenience
337 string.escape = escape
338 string.pcdata = pcdata
339 string.striptags = striptags
342 string.cmatch = cmatch
343 string.parse_units = parse_units
346 --- Appends numerically indexed tables or single objects to a given table.
347 -- @param src Target table
348 -- @param ... Objects to insert
349 -- @return Target table
350 function append(src, ...)
351 for i, a in ipairs({...}) do
352 if type(a) == "table" then
353 for j, v in ipairs(a) do
363 --- Combines two or more numerically indexed tables and single objects into one table.
364 -- @param tbl1 Table value to combine
365 -- @param tbl2 Table value to combine
366 -- @param ... More tables to combine
367 -- @return Table value containing all values of given tables
368 function combine(...)
369 return append({}, ...)
372 --- Checks whether the given table contains the given value.
373 -- @param table Table value
374 -- @param value Value to search within the given table
375 -- @return Boolean indicating whether the given value occurs within table
376 function contains(table, value)
377 for k, v in pairs(table) do
385 --- Update values in given table with the values from the second given table.
386 -- Both table are - in fact - merged together.
387 -- @param t Table which should be updated
388 -- @param updates Table containing the values to update
389 -- @return Always nil
390 function update(t, updates)
391 for k, v in pairs(updates) do
396 --- Retrieve all keys of given associative table.
397 -- @param t Table to extract keys from
398 -- @return Sorted table containing the keys
402 for k, _ in kspairs(t) do
409 --- Clones the given object and return it's copy.
410 -- @param object Table value to clone
411 -- @param deep Boolean indicating whether to do recursive cloning
412 -- @return Cloned table value
413 function clone(object, deep)
416 for k, v in pairs(object) do
417 if deep and type(v) == "table" then
423 return setmetatable(copy, getmetatable(object))
427 --- Create a dynamic table which automatically creates subtables.
428 -- @return Dynamic Table
430 return setmetatable({}, { __index =
432 return rawget(tbl, key)
433 or rawget(rawset(tbl, key, dtable()), key)
439 -- Serialize the contents of a table value.
440 function _serialize_table(t, seen)
441 assert(not seen[t], "Recursion detected.")
448 for k, v in pairs(t) do
449 if type(k) ~= "number" or k < 1 or math.floor(k) ~= k or ( k - #t ) > 3 then
450 k = serialize_data(k, seen)
451 v = serialize_data(v, seen)
452 data = data .. ( #data > 0 and ", " or "" ) ..
453 '[' .. k .. '] = ' .. v
460 local v = serialize_data(t[i], seen)
461 idata = idata .. ( #idata > 0 and ", " or "" ) .. v
464 return idata .. ( #data > 0 and #idata > 0 and ", " or "" ) .. data
467 --- Recursively serialize given data to lua code, suitable for restoring
468 -- with loadstring().
469 -- @param val Value containing the data to serialize
470 -- @return String value containing the serialized code
473 function serialize_data(val, seen)
474 seen = seen or setmetatable({}, {__mode="k"})
478 elseif type(val) == "number" then
480 elseif type(val) == "string" then
482 elseif type(val) == "boolean" then
483 return val and "true" or "false"
484 elseif type(val) == "function" then
485 return "loadstring(%q)" % get_bytecode(val)
486 elseif type(val) == "table" then
487 return "{ " .. _serialize_table(val, seen) .. " }"
489 return '"[unhandled data type:' .. type(val) .. ']"'
493 --- Restore data previously serialized with serialize_data().
494 -- @param str String containing the data to restore
495 -- @return Value containing the restored data structure
496 -- @see serialize_data
498 function restore_data(str)
499 return loadstring("return " .. str)()
504 -- Byte code manipulation routines
507 --- Return the current runtime bytecode of the given data. The byte code
508 -- will be stripped before it is returned.
509 -- @param val Value to return as bytecode
510 -- @return String value containing the bytecode of the given data
511 function get_bytecode(val)
514 if type(val) == "function" then
515 code = string.dump(val)
517 code = string.dump( loadstring( "return " .. serialize_data(val) ) )
520 return code and strip_bytecode(code)
523 --- Strips unnescessary lua bytecode from given string. Information like line
524 -- numbers and debugging numbers will be discarded. Original version by
525 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
526 -- @param code String value containing the original lua byte code
527 -- @return String value containing the stripped lua byte code
528 function strip_bytecode(code)
529 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
532 subint = function(code, i, l)
535 val = val * 256 + code:byte(i + n - 1)
540 subint = function(code, i, l)
543 val = val * 256 + code:byte(i + n - 1)
550 strip_function = function(code)
551 local count, offset = subint(code, 1, size)
552 local stripped, dirty = string.rep("\0", size), offset + count
553 offset = offset + count + int * 2 + 4
554 offset = offset + int + subint(code, offset, int) * ins
555 count, offset = subint(code, offset, int)
558 t, offset = subint(code, offset, 1)
562 offset = offset + size + subint(code, offset, size)
564 offset = offset + num
565 elseif t == 254 or t == 9 then
566 offset = offset + lnum
569 count, offset = subint(code, offset, int)
570 stripped = stripped .. code:sub(dirty, offset - 1)
572 local proto, off = strip_function(code:sub(offset, -1))
573 stripped, offset = stripped .. proto, offset + off - 1
575 offset = offset + subint(code, offset, int) * int + int
576 count, offset = subint(code, offset, int)
578 offset = offset + subint(code, offset, size) + size + int * 2
580 count, offset = subint(code, offset, int)
582 offset = offset + subint(code, offset, size) + size
584 stripped = stripped .. string.rep("\0", int * 3)
585 return stripped, offset
588 return code:sub(1,12) .. strip_function(code:sub(13,-1))
593 -- Sorting iterator functions
596 function _sortiter( t, f )
599 for k, v in pairs(t) do
605 table.sort( keys, f )
609 if _pos <= #keys then
610 return keys[_pos], t[keys[_pos]]
615 --- Return a key, value iterator which returns the values sorted according to
616 -- the provided callback function.
617 -- @param t The table to iterate
618 -- @param f A callback function to decide the order of elements
619 -- @return Function value containing the corresponding iterator
621 return _sortiter( t, f )
624 --- Return a key, value iterator for the given table.
625 -- The table pairs are sorted by key.
626 -- @param t The table to iterate
627 -- @return Function value containing the corresponding iterator
629 return _sortiter( t )
632 --- Return a key, value iterator for the given table.
633 -- The table pairs are sorted by value.
634 -- @param t The table to iterate
635 -- @return Function value containing the corresponding iterator
637 return _sortiter( t, function (a,b) return t[a] < t[b] end )
642 -- System utility functions
645 --- Test whether the current system is operating in big endian mode.
646 -- @return Boolean value indicating whether system is big endian
648 return string.byte(string.dump(function() end), 7) == 0
651 --- Execute given commandline and gather stdout.
652 -- @param command String containing command to execute
653 -- @return String containing the command's stdout
654 function exec(command)
655 local pp = io.popen(command)
656 local data = pp:read("*a")
662 --- Return a line-buffered iterator over the output of given command.
663 -- @param command String containing the command to execute
665 function execi(command)
666 local pp = io.popen(command)
668 return pp and function()
669 local line = pp:read()
680 function execl(command)
681 local pp = io.popen(command)
687 if (line == nil) then break end
695 --- Returns the absolute path to LuCI base directory.
696 -- @return String containing the directory path
698 return require "luci.fs".dirname(ldebug.__file__)
703 -- Coroutine safe xpcall and pcall versions modified for Luci
705 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
707 -- Copyright © 2005 Kepler Project.
708 -- Permission is hereby granted, free of charge, to any person obtaining a
709 -- copy of this software and associated documentation files (the "Software"),
710 -- to deal in the Software without restriction, including without limitation
711 -- the rights to use, copy, modify, merge, publish, distribute, sublicense,
712 -- and/or sell copies of the Software, and to permit persons to whom the
713 -- Software is furnished to do so, subject to the following conditions:
715 -- The above copyright notice and this permission notice shall be
716 -- included in all copies or substantial portions of the Software.
718 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
719 -- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
720 -- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
721 -- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
722 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
723 -- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
724 -- OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
726 local performResume, handleReturnValue
727 local oldpcall, oldxpcall = pcall, xpcall
729 setmetatable(coxpt, {__mode = "kv"})
731 -- Identity function for copcall
732 local function copcall_id(trace, ...)
736 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
737 -- @param f Lua function to be called protected
738 -- @param err Custom error handler
739 -- @param ... Parameters passed to the function
740 -- @return A boolean whether the function call succeeded and the return
741 -- values of either the function or the error handler
742 function coxpcall(f, err, ...)
743 local res, co = oldpcall(coroutine.create, f)
746 local newf = function() return f(unpack(params)) end
747 co = coroutine.create(newf)
749 local c = coroutine.running()
750 coxpt[co] = coxpt[c] or c or 0
752 return performResume(err, co, ...)
755 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
756 -- @param f Lua function to be called protected
757 -- @param ... Parameters passed to the function
758 -- @return A boolean whether the function call succeeded and the returns
759 -- values of the function or the error object
760 function copcall(f, ...)
761 return coxpcall(f, copcall_id, ...)
764 -- Handle return value of protected call
765 function handleReturnValue(err, co, status, ...)
767 return false, err(debug.traceback(co, (...)), ...)
769 if coroutine.status(co) == 'suspended' then
770 return performResume(err, co, coroutine.yield(...))
776 -- Resume execution of protected function call
777 function performResume(err, co, ...)
778 return handleReturnValue(err, co, coroutine.resume(co, ...))