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 --- Create a Class object (Python-style object model).
35 -- The class object 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 occurrences 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 occurrence 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 if not value then return end
203 value = tostring(value)
204 value = value:gsub("&", "&")
205 value = value:gsub('"', """)
206 value = value:gsub("'", "'")
207 value = value:gsub("<", "<")
208 return value:gsub(">", ">")
211 --- Strip HTML tags from given string.
212 -- @param value String containing the HTML text
213 -- @return String with HTML tags stripped of
214 function striptags(s)
215 return pcdata(s:gsub("</?[A-Za-z][A-Za-z0-9:_%-]*[^>]*>", " "):gsub("%s+", " "))
218 --- Splits given string on a defined separator sequence and return a table
219 -- containing the resulting substrings. The optional max parameter specifies
220 -- the number of bytes to process, regardless of the actual length of the given
221 -- string. The optional last parameter, regex, specifies whether the separator
222 -- sequence is interpreted as regular expression.
223 -- @param str String value containing the data to split up
224 -- @param pat String with separator pattern (optional, defaults to "\n")
225 -- @param max Maximum times to split (optional)
226 -- @param regex Boolean indicating whether to interpret the separator
227 -- pattern as regular expression (optional, default is false)
228 -- @return Table containing the resulting substrings
229 function split(str, pat, max, regex)
249 local s, e = str:find(pat, c, not regex)
251 if s and max < 0 then
252 table.insert(t, str:sub(c))
254 table.insert(t, str:sub(c, s and s - 1))
256 c = e and e + 1 or #str + 1
257 until not s or max < 0
262 --- Remove leading and trailing whitespace from given string value.
263 -- @param str String value containing whitespace padded data
264 -- @return String value with leading and trailing space removed
266 local s = str:gsub("^%s*(.-)%s*$", "%1")
270 --- Parse certain units from the given string and return the canonical integer
271 -- value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
272 -- Recognized units are:
273 -- o "y" - one year (60*60*24*366)
274 -- o "m" - one month (60*60*24*31)
275 -- o "w" - one week (60*60*24*7)
276 -- o "d" - one day (60*60*24)
277 -- o "h" - one hour (60*60)
278 -- o "min" - one minute (60)
279 -- o "kb" - one kilobyte (1024)
280 -- o "mb" - one megabyte (1024*1024)
281 -- o "gb" - one gigabyte (1024*1024*1024)
282 -- o "kib" - one si kilobyte (1000)
283 -- o "mib" - one si megabyte (1000*1000)
284 -- o "gib" - one si gigabyte (1000*1000*1000)
285 -- @param ustr String containing a numerical value with trailing unit
286 -- @return Number containing the canonical value
287 function parse_units(ustr)
294 y = 60 * 60 * 24 * 366,
295 m = 60 * 60 * 24 * 31,
296 w = 60 * 60 * 24 * 7,
304 gb = 1024 * 1024 * 1024,
306 -- storage sizes (si)
309 gib = 1000 * 1000 * 1000
312 -- parse input string
313 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
315 local num = spec:gsub("[^0-9%.]+$","")
316 local spn = spec:gsub("^[0-9%.]+", "")
318 if map[spn] or map[spn:sub(1,1)] then
319 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
329 --- Combines two or more numerically indexed tables into one.
330 -- @param tbl1 Table value to combine
331 -- @param tbl2 Table value to combine
332 -- @param ... More tables to combine
333 -- @return Table value containing all values of given tables
334 function combine(...)
336 for i, a in ipairs(arg) do
337 for j, v in ipairs(a) do
338 table.insert(result, v)
344 --- Checks whether the given table contains the given value.
345 -- @param table Table value
346 -- @param value Value to search within the given table
347 -- @return Boolean indicating whether the given value occurs within table
348 function contains(table, value)
349 for k, v in pairs(table) do
357 --- Update values in given table with the values from the second given table.
358 -- Both table are - in fact - merged together.
359 -- @param t Table which should be updated
360 -- @param updates Table containing the values to update
361 -- @return Always nil
362 function update(t, updates)
363 for k, v in pairs(updates) do
368 --- Retrieve all keys of given associative table.
369 -- @param t Table to extract keys from
370 -- @return Sorted table containing the keys
374 for k, _ in kspairs(t) do
375 table.insert( keys, k )
381 --- Clones the given object and return it's copy.
382 -- @param object Table value to clone
383 -- @param deep Boolean indicating whether to do recursive cloning
384 -- @return Cloned table value
385 function clone(object, deep)
388 for k, v in pairs(object) do
389 if deep and type(v) == "table" then
395 setmetatable(copy, getmetatable(object))
401 --- Create a dynamic table which automatically creates subtables.
402 -- @return Dynamic Table
404 return setmetatable({}, { __index =
406 return rawget(tbl, key)
407 or rawget(rawset(tbl, key, dtable()), key)
413 -- Serialize the contents of a table value.
414 function _serialize_table(t)
416 for k, v in pairs(t) do
417 k = serialize_data(k)
418 v = serialize_data(v)
419 data = data .. ( #data > 0 and ", " or "" ) ..
420 '[' .. k .. '] = ' .. v
425 --- Recursively serialize given data to lua code, suitable for restoring
426 -- with loadstring().
427 -- @param val Value containing the data to serialize
428 -- @return String value containing the serialized code
431 function serialize_data(val)
434 elseif type(val) == "number" then
436 elseif type(val) == "string" then
437 return string.format("%q", val)
438 elseif type(val) == "boolean" then
439 return val and "true" or "false"
440 elseif type(val) == "function" then
441 return string.format("loadstring(%q)", get_bytecode(val))
442 elseif type(val) == "table" then
443 return "{ " .. _serialize_table(val) .. " }"
445 return '"[unhandled data type:' .. type(val) .. ']"'
449 --- Restore data previously serialized with serialize_data().
450 -- @param str String containing the data to restore
451 -- @return Value containing the restored data structure
452 -- @see serialize_data
454 function restore_data(str)
455 return loadstring("return " .. str)()
460 -- Byte code manipulation routines
463 --- Return the current runtime bytecode of the given data. The byte code
464 -- will be stripped before it is returned.
465 -- @param val Value to return as bytecode
466 -- @return String value containing the bytecode of the given data
467 function get_bytecode(val)
470 if type(val) == "function" then
471 code = string.dump(val)
473 code = string.dump( loadstring( "return " .. serialize_data(val) ) )
476 return code and strip_bytecode(code)
479 --- Strips unnescessary lua bytecode from given string. Information like line
480 -- numbers and debugging numbers will be discarded. Original version by
481 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
482 -- @param code String value containing the original lua byte code
483 -- @return String value containing the stripped lua byte code
484 function strip_bytecode(code)
485 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
488 subint = function(code, i, l)
491 val = val * 256 + code:byte(i + n - 1)
496 subint = function(code, i, l)
499 val = val * 256 + code:byte(i + n - 1)
506 strip_function = function(code)
507 local count, offset = subint(code, 1, size)
508 local stripped, dirty = string.rep("\0", size), offset + count
509 offset = offset + count + int * 2 + 4
510 offset = offset + int + subint(code, offset, int) * ins
511 count, offset = subint(code, offset, int)
514 t, offset = subint(code, offset, 1)
518 offset = offset + size + subint(code, offset, size)
520 offset = offset + num
521 elseif t == 254 or t == 9 then
522 offset = offset + lnum
525 count, offset = subint(code, offset, int)
526 stripped = stripped .. code:sub(dirty, offset - 1)
528 local proto, off = strip_function(code:sub(offset, -1))
529 stripped, offset = stripped .. proto, offset + off - 1
531 offset = offset + subint(code, offset, int) * int + int
532 count, offset = subint(code, offset, int)
534 offset = offset + subint(code, offset, size) + size + int * 2
536 count, offset = subint(code, offset, int)
538 offset = offset + subint(code, offset, size) + size
540 stripped = stripped .. string.rep("\0", int * 3)
541 return stripped, offset
544 return code:sub(1,12) .. strip_function(code:sub(13,-1))
549 -- Sorting iterator functions
552 function _sortiter( t, f )
555 for k, v in pairs(t) do
556 table.insert( keys, k )
560 local _len = table.getn( keys )
562 table.sort( keys, f )
567 return keys[_pos], t[keys[_pos]]
572 --- Return a key, value iterator which returns the values sorted according to
573 -- the provided callback function.
574 -- @param t The table to iterate
575 -- @param f A callback function to decide the order of elements
576 -- @return Function value containing the corresponding iterator
578 return _sortiter( t, f )
581 --- Return a key, value iterator for the given table.
582 -- The table pairs are sorted by key.
583 -- @param t The table to iterate
584 -- @return Function value containing the corresponding iterator
586 return _sortiter( t )
589 --- Return a key, value iterator for the given table.
590 -- The table pairs are sorted by value.
591 -- @param t The table to iterate
592 -- @return Function value containing the corresponding iterator
594 return _sortiter( t, function (a,b) return t[a] < t[b] end )
599 -- System utility functions
602 --- Test whether the current system is operating in big endian mode.
603 -- @return Boolean value indicating whether system is big endian
605 return string.byte(string.dump(function() end), 7) == 0
608 --- Execute given commandline and gather stdout.
609 -- @param command String containing command to execute
610 -- @return String containing the command's stdout
611 function exec(command)
612 local pp = io.popen(command)
613 local data = pp:read("*a")
619 --- Return a line-buffered iterator over the output of given command.
620 -- @param command String containing the command to execute
622 function execi(command)
623 local pp = io.popen(command)
625 return pp and function()
626 local line = pp:read()
637 function execl(command)
638 local pp = io.popen(command)
644 if (line == nil) then break end
645 table.insert(data, line)
652 --- Returns the absolute path to LuCI base directory.
653 -- @return String containing the directory path
655 return luci.fs.dirname(require("luci.debug").__file__)
660 -- Coroutine safe xpcall and pcall versions modified for Luci
662 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
664 -- Copyright © 2005 Kepler Project.
665 -- Permission is hereby granted, free of charge, to any person obtaining a
666 -- copy of this software and associated documentation files (the "Software"),
667 -- to deal in the Software without restriction, including without limitation
668 -- the rights to use, copy, modify, merge, publish, distribute, sublicense,
669 -- and/or sell copies of the Software, and to permit persons to whom the
670 -- Software is furnished to do so, subject to the following conditions:
672 -- The above copyright notice and this permission notice shall be
673 -- included in all copies or substantial portions of the Software.
675 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
676 -- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
677 -- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
678 -- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
679 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
680 -- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
681 -- OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
683 local performResume, handleReturnValue
684 local oldpcall, oldxpcall = pcall, xpcall
686 setmetatable(coxpt, {__mode = "kv"})
688 -- Identity function for copcall
689 local function copcall_id(trace, ...)
693 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
694 -- @param f Lua function to be called protected
695 -- @param err Custom error handler
696 -- @param ... Parameters passed to the function
697 -- @return A boolean whether the function call succeeded and the return
698 -- values of either the function or the error handler
699 function coxpcall(f, err, ...)
700 local res, co = oldpcall(coroutine.create, f)
703 local newf = function() return f(unpack(params)) end
704 co = coroutine.create(newf)
706 local c = coroutine.running()
707 coxpt[co] = coxpt[c] or c or 0
709 return performResume(err, co, ...)
712 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
713 -- @param f Lua function to be called protected
714 -- @param ... Parameters passed to the function
715 -- @return A boolean whether the function call succeeded and the returns
716 -- values of the function or the error object
717 function copcall(f, ...)
718 return coxpcall(f, copcall_id, ...)
721 -- Handle return value of protected call
722 function handleReturnValue(err, co, status, ...)
724 return false, err(debug.traceback(co, (...)), ...)
726 if coroutine.status(co) == 'suspended' then
727 return performResume(err, co, coroutine.yield(...))
733 -- Resume execution of protected function call
734 function performResume(err, co, ...)
735 return handleReturnValue(err, co, coroutine.resume(co, ...))