libs/core: Add luci.execi as memory efficient replacement for now deprecated luci...
[project/luci.git] / libs / core / luasrc / util.lua
1 --[[
2 LuCI - Utility library
3
4 Description:
5 Several common useful Lua functions
6
7 FileId:
8 $Id$
9
10 License:
11 Copyright 2008 Steven Barth <steven@midlink.org>
12
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
16
17 http://www.apache.org/licenses/LICENSE-2.0
18
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.
24
25 ]]--
26
27 --- LuCI utility functions.
28 module("luci.util", package.seeall)
29
30 --
31 -- Class helper routines
32 --
33
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
46 -- @see instanceof
47 -- @see clone
48 function class(base)
49 local class = {}
50
51 local create = function(class, ...)
52 local inst = {}
53 setmetatable(inst, {__index = class})
54
55 if inst.__init__ then
56 local stat, err = copcall(inst.__init__, inst, ...)
57 if not stat then
58 error(err)
59 end
60 end
61
62 return inst
63 end
64
65 local classmeta = {__call = create}
66
67 if base then
68 classmeta.__index = base
69 end
70
71 setmetatable(class, classmeta)
72 return class
73 end
74
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
79 -- @see class
80 -- @see clone
81 function instanceof(object, class)
82 local meta = getmetatable(object)
83 while meta and meta.__index do
84 if meta.__index == class then
85 return true
86 end
87 meta = getmetatable(meta.__index)
88 end
89 return false
90 end
91
92
93 --
94 -- Scope manipulation routines
95 --
96
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
101 function resfenv(f)
102 setfenv(f, clone(getfenv(f)))
103 end
104
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
110 -- @see updfenv
111 -- @see resfenv
112 function extfenv(f, key, obj)
113 local scope = getfenv(f)
114 scope[key] = obj
115 end
116
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
122 -- @see extfenv
123 -- @see resfenv
124 function updfenv(f, extscope)
125 update(getfenv(f), extscope)
126 end
127
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()
133 local tbl = {}
134
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
139 return nil
140 end
141 return rawget(self, thread)[key]
142 end
143
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, {})
149 end
150 rawget(self, thread)[key] = value
151 end
152
153 setmetatable(tbl, {__index = get, __newindex = set, __mode = "k"})
154
155 return tbl
156 end
157
158
159 --
160 -- Debugging routines
161 --
162
163 --- Write given object to stderr.
164 -- @param obj Value to write to stderr
165 -- @return Boolean indicating whether the write operation was successful
166 function perror(obj)
167 return io.stderr:write(tostring(obj) .. "\n")
168 end
169
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)
175 i = i or 0
176 for k,v in pairs(t) do
177 print(string.rep("\t", i) .. tostring(k), tostring(v))
178 if type(v) == "table" then
179 dumptable(v, i+1)
180 end
181 end
182 end
183
184
185 --
186 -- String and data manipulation routines
187 --
188
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)
194 c = c or "\\"
195 return s:gsub(c, "\\" .. c)
196 end
197
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 value = value:gsub("&", "&amp;")
203 value = value:gsub('"', "&quot;")
204 value = value:gsub("'", "&apos;")
205 value = value:gsub("<", "&lt;")
206 return value:gsub(">", "&gt;")
207 end
208
209 --- Splits given string on a defined separator sequence and return a table
210 -- containing the resulting substrings. The optional max parameter specifies
211 -- the number of bytes to process, regardless of the actual length of the given
212 -- string. The optional last parameter, regex, specifies whether the separator
213 -- sequence is interpreted as regular expression.
214 -- @param str String value containing the data to split up
215 -- @param pat String with separator pattern (optional, defaults to "\n")
216 -- @param max Maximum times to split (optional)
217 -- @param regex Boolean indicating whether to interpret the separator
218 -- pattern as regular expression (optional, default is false)
219 -- @return Table containing the resulting substrings
220 function split(str, pat, max, regex)
221 pat = pat or "\n"
222 max = max or #str
223
224 local t = {}
225 local c = 1
226
227 if #str == 0 then
228 return {""}
229 end
230
231 if #pat == 0 then
232 return nil
233 end
234
235 if max == 0 then
236 return str
237 end
238
239 repeat
240 local s, e = str:find(pat, c, not regex)
241 max = max - 1
242 if s and max < 0 then
243 table.insert(t, str:sub(c))
244 else
245 table.insert(t, str:sub(c, s and s - 1))
246 end
247 c = e and e + 1 or #str + 1
248 until not s or max < 0
249
250 return t
251 end
252
253 --- Remove leading and trailing whitespace from given string value.
254 -- @param str String value containing whitespace padded data
255 -- @return String value with leading and trailing space removed
256 function trim(str)
257 local s = str:gsub("^%s*(.-)%s*$", "%1")
258 return s
259 end
260
261 --- Parse certain units from the given string and return the canonical integer
262 -- value or 0 if the unit is unknown. Upper- or lower case is irrelevant.
263 -- Recognized units are:
264 -- o "y" - one year (60*60*24*366)
265 -- o "m" - one month (60*60*24*31)
266 -- o "w" - one week (60*60*24*7)
267 -- o "d" - one day (60*60*24)
268 -- o "h" - one hour (60*60)
269 -- o "min" - one minute (60)
270 -- o "kb" - one kilobyte (1024)
271 -- o "mb" - one megabyte (1024*1024)
272 -- o "gb" - one gigabyte (1024*1024*1024)
273 -- o "kib" - one si kilobyte (1000)
274 -- o "mib" - one si megabyte (1000*1000)
275 -- o "gib" - one si gigabyte (1000*1000*1000)
276 -- @param ustr String containing a numerical value with trailing unit
277 -- @return Number containing the canonical value
278 function parse_units(ustr)
279
280 local val = 0
281
282 -- unit map
283 local map = {
284 -- date stuff
285 y = 60 * 60 * 24 * 366,
286 m = 60 * 60 * 24 * 31,
287 w = 60 * 60 * 24 * 7,
288 d = 60 * 60 * 24,
289 h = 60 * 60,
290 min = 60,
291
292 -- storage sizes
293 kb = 1024,
294 mb = 1024 * 1024,
295 gb = 1024 * 1024 * 1024,
296
297 -- storage sizes (si)
298 kib = 1000,
299 mib = 1000 * 1000,
300 gib = 1000 * 1000 * 1000
301 }
302
303 -- parse input string
304 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
305
306 local num = spec:gsub("[^0-9%.]+$","")
307 local spn = spec:gsub("^[0-9%.]+", "")
308
309 if map[spn] or map[spn:sub(1,1)] then
310 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
311 else
312 val = val + num
313 end
314 end
315
316
317 return val
318 end
319
320 --- Combines two or more numerically indexed tables into one.
321 -- @param tbl1 Table value to combine
322 -- @param tbl2 Table value to combine
323 -- @param ... More tables to combine
324 -- @return Table value containing all values of given tables
325 function combine(...)
326 local result = {}
327 for i, a in ipairs(arg) do
328 for j, v in ipairs(a) do
329 table.insert(result, v)
330 end
331 end
332 return result
333 end
334
335 --- Checks whether the given table contains the given value.
336 -- @param table Table value
337 -- @param value Value to search within the given table
338 -- @return Boolean indicating whether the given value occurs within table
339 function contains(table, value)
340 for k, v in pairs(table) do
341 if value == v then
342 return k
343 end
344 end
345 return false
346 end
347
348 --- Update values in given table with the values from the second given table.
349 -- Both table are - in fact - merged together.
350 -- @param t Table which should be updated
351 -- @param updates Table containing the values to update
352 -- @return Always nil
353 function update(t, updates)
354 for k, v in pairs(updates) do
355 t[k] = v
356 end
357 end
358
359 --- Clones the given object and return it's copy.
360 -- @param object Table value to clone
361 -- @param deep Boolean indicating whether to do recursive cloning
362 -- @return Cloned table value
363 function clone(object, deep)
364 local copy = {}
365
366 for k, v in pairs(object) do
367 if deep and type(v) == "table" then
368 v = clone(v, deep)
369 end
370 copy[k] = v
371 end
372
373 setmetatable(copy, getmetatable(object))
374
375 return copy
376 end
377
378
379 --- Create a dynamic table which automatically creates subtables.
380 -- @return Dynamic Table
381 function dtable()
382 return setmetatable({}, { __index =
383 function(tbl, key)
384 return rawget(tbl, key)
385 or rawget(rawset(tbl, key, dtable()), key)
386 end
387 })
388 end
389
390
391 -- Serialize the contents of a table value.
392 function _serialize_table(t)
393 local data = ""
394 for k, v in pairs(t) do
395 k = serialize_data(k)
396 v = serialize_data(v)
397 data = data .. ( #data > 0 and ", " or "" ) ..
398 '[' .. k .. '] = ' .. v
399 end
400 return data
401 end
402
403 --- Recursively serialize given data to lua code, suitable for restoring
404 -- with loadstring().
405 -- @param val Value containing the data to serialize
406 -- @return String value containing the serialized code
407 -- @see restore_data
408 -- @see get_bytecode
409 function serialize_data(val)
410 if val == nil then
411 return "nil"
412 elseif type(val) == "number" then
413 return val
414 elseif type(val) == "string" then
415 return string.format("%q", val)
416 elseif type(val) == "boolean" then
417 return val and "true" or "false"
418 elseif type(val) == "function" then
419 return string.format("loadstring(%q)", get_bytecode(val))
420 elseif type(val) == "table" then
421 return "{ " .. _serialize_table(val) .. " }"
422 else
423 return '"[unhandled data type:' .. type(val) .. ']"'
424 end
425 end
426
427 --- Restore data previously serialized with serialize_data().
428 -- @param str String containing the data to restore
429 -- @return Value containing the restored data structure
430 -- @see serialize_data
431 -- @see get_bytecode
432 function restore_data(str)
433 return loadstring("return " .. str)()
434 end
435
436
437 --
438 -- Byte code manipulation routines
439 --
440
441 --- Return the current runtime bytecode of the given data. The byte code
442 -- will be stripped before it is returned.
443 -- @param val Value to return as bytecode
444 -- @return String value containing the bytecode of the given data
445 function get_bytecode(val)
446 local code
447
448 if type(val) == "function" then
449 code = string.dump(val)
450 else
451 code = string.dump( loadstring( "return " .. serialize_data(val) ) )
452 end
453
454 return code and strip_bytecode(code)
455 end
456
457 --- Strips unnescessary lua bytecode from given string. Information like line
458 -- numbers and debugging numbers will be discarded. Original version by
459 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
460 -- @param code String value containing the original lua byte code
461 -- @return String value containing the stripped lua byte code
462 function strip_bytecode(code)
463 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
464 local subint
465 if endian == 1 then
466 subint = function(code, i, l)
467 local val = 0
468 for n = l, 1, -1 do
469 val = val * 256 + code:byte(i + n - 1)
470 end
471 return val, i + l
472 end
473 else
474 subint = function(code, i, l)
475 local val = 0
476 for n = 1, l, 1 do
477 val = val * 256 + code:byte(i + n - 1)
478 end
479 return val, i + l
480 end
481 end
482
483 local strip_function
484 strip_function = function(code)
485 local count, offset = subint(code, 1, size)
486 local stripped, dirty = string.rep("\0", size), offset + count
487 offset = offset + count + int * 2 + 4
488 offset = offset + int + subint(code, offset, int) * ins
489 count, offset = subint(code, offset, int)
490 for n = 1, count do
491 local t
492 t, offset = subint(code, offset, 1)
493 if t == 1 then
494 offset = offset + 1
495 elseif t == 4 then
496 offset = offset + size + subint(code, offset, size)
497 elseif t == 3 then
498 offset = offset + num
499 elseif t == 254 or t == 9 then
500 offset = offset + lnum
501 end
502 end
503 count, offset = subint(code, offset, int)
504 stripped = stripped .. code:sub(dirty, offset - 1)
505 for n = 1, count do
506 local proto, off = strip_function(code:sub(offset, -1))
507 stripped, offset = stripped .. proto, offset + off - 1
508 end
509 offset = offset + subint(code, offset, int) * int + int
510 count, offset = subint(code, offset, int)
511 for n = 1, count do
512 offset = offset + subint(code, offset, size) + size + int * 2
513 end
514 count, offset = subint(code, offset, int)
515 for n = 1, count do
516 offset = offset + subint(code, offset, size) + size
517 end
518 stripped = stripped .. string.rep("\0", int * 3)
519 return stripped, offset
520 end
521
522 return code:sub(1,12) .. strip_function(code:sub(13,-1))
523 end
524
525
526 --
527 -- Sorting iterator functions
528 --
529
530 function _sortiter( t, f )
531 local keys = { }
532
533 for k, v in pairs(t) do
534 table.insert( keys, k )
535 end
536
537 local _pos = 0
538 local _len = table.getn( keys )
539
540 table.sort( keys, f )
541
542 return function()
543 _pos = _pos + 1
544 if _pos <= _len then
545 return keys[_pos], t[keys[_pos]]
546 end
547 end
548 end
549
550 --- Return a key, value iterator which returns the values sorted according to
551 -- the provided callback function.
552 -- @param t The table to iterate
553 -- @param f A callback function to decide the order of elements
554 -- @return Function value containing the corresponding iterator
555 function spairs(t,f)
556 return _sortiter( t, f )
557 end
558
559 --- Return a key, value iterator for the given table.
560 -- The table pairs are sorted by key.
561 -- @param t The table to iterate
562 -- @return Function value containing the corresponding iterator
563 function kspairs(t)
564 return _sortiter( t )
565 end
566
567 --- Return a key, value iterator for the given table.
568 -- The table pairs are sorted by value.
569 -- @param t The table to iterate
570 -- @return Function value containing the corresponding iterator
571 function vspairs(t)
572 return _sortiter( t, function (a,b) return t[a] < t[b] end )
573 end
574
575
576 --
577 -- System utility functions
578 --
579
580 --- Test whether the current system is operating in big endian mode.
581 -- @return Boolean value indicating whether system is big endian
582 function bigendian()
583 return string.byte(string.dump(function() end), 7) == 0
584 end
585
586 --- Execute given commandline and gather stdout.
587 -- @param command String containing command to execute
588 -- @return String containing the command's stdout
589 function exec(command)
590 local pp = io.popen(command)
591 local data = pp:read("*a")
592 pp:close()
593
594 return data
595 end
596
597 --- Return a line-buffered iterator over the output of given command.
598 -- @param command String containing the command to execute
599 -- @return Iterator
600 function execi(command)
601 local pp = io.popen(command)
602
603 return pp and function()
604 local line = pp:read()
605
606 if not line then
607 pp:close()
608 end
609
610 return line
611 end
612 end
613
614 -- Deprecated
615 function execl(command)
616 local pp = io.popen(command)
617 local line = ""
618 local data = {}
619
620 while true do
621 line = pp:read()
622 if (line == nil) then break end
623 table.insert(data, line)
624 end
625 pp:close()
626
627 return data
628 end
629
630 --- Returns the absolute path to LuCI base directory.
631 -- @return String containing the directory path
632 function libpath()
633 return luci.fs.dirname(require("luci.debug").__file__)
634 end
635
636
637 --
638 -- Coroutine safe xpcall and pcall versions modified for Luci
639 -- original version:
640 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
641 --
642 -- Copyright © 2005 Kepler Project.
643 -- Permission is hereby granted, free of charge, to any person obtaining a
644 -- copy of this software and associated documentation files (the "Software"),
645 -- to deal in the Software without restriction, including without limitation
646 -- the rights to use, copy, modify, merge, publish, distribute, sublicense,
647 -- and/or sell copies of the Software, and to permit persons to whom the
648 -- Software is furnished to do so, subject to the following conditions:
649 --
650 -- The above copyright notice and this permission notice shall be
651 -- included in all copies or substantial portions of the Software.
652 --
653 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
654 -- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
655 -- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
656 -- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
657 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
658 -- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
659 -- OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
660
661 local performResume, handleReturnValue
662 local oldpcall, oldxpcall = pcall, xpcall
663 coxpt = {}
664 setmetatable(coxpt, {__mode = "kv"})
665
666 -- Identity function for copcall
667 local function copcall_id(trace, ...)
668 return ...
669 end
670
671 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
672 -- @param f Lua function to be called protected
673 -- @param err Custom error handler
674 -- @param ... Parameters passed to the function
675 -- @return A boolean whether the function call succeeded and the return
676 -- values of either the function or the error handler
677 function coxpcall(f, err, ...)
678 local res, co = oldpcall(coroutine.create, f)
679 if not res then
680 local params = {...}
681 local newf = function() return f(unpack(params)) end
682 co = coroutine.create(newf)
683 end
684 local c = coroutine.running()
685 coxpt[co] = coxpt[c] or c or 0
686
687 return performResume(err, co, ...)
688 end
689
690 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
691 -- @param f Lua function to be called protected
692 -- @param ... Parameters passed to the function
693 -- @return A boolean whether the function call succeeded and the returns
694 -- values of the function or the error object
695 function copcall(f, ...)
696 return coxpcall(f, copcall_id, ...)
697 end
698
699 -- Handle return value of protected call
700 function handleReturnValue(err, co, status, ...)
701 if not status then
702 return false, err(debug.traceback(co, (...)), ...)
703 end
704 if coroutine.status(co) == 'suspended' then
705 return performResume(err, co, coroutine.yield(...))
706 else
707 return true, ...
708 end
709 end
710
711 -- Resume execution of protected function call
712 function performResume(err, co, ...)
713 return handleReturnValue(err, co, coroutine.resume(co, ...))
714 end