1e03489463897c277572bb33308cf1d10d0a84c3
[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 --- Creates a Class object (Python-style object model)
35 -- Creates a new class object which 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 paramters 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 wheather 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 --- Resets the scope of f doing a shallow copy of its scope into a new table
98 -- (ToDo: @param and @return)
99 function resfenv(f)
100 setfenv(f, clone(getfenv(f)))
101 end
102
103 --- Store given object associated with given key in the scope associated with
104 -- the given identifier.
105 -- @param f Value containing the scope identifier
106 -- @param key String value containg the key of the object to store
107 -- @param obj Object to store in the scope
108 -- @return Always nil
109 function extfenv(f, key, obj)
110 local scope = getfenv(f)
111 scope[key] = obj
112 end
113
114 --- Updates the scope of f with "extscope" (ToDo: docu)
115 function updfenv(f, extscope)
116 update(getfenv(f), extscope)
117 end
118
119 --- Create a new or get an already existing thread local store associated with
120 -- the current active coroutine. A thread local store is private a table object
121 -- whose values can't be accessed from outside of the running coroutine.
122 -- @return Table value representing the corresponding thread local store
123 function threadlocal()
124 local tbl = {}
125
126 local function get(self, key)
127 local c = coroutine.running()
128 local thread = coxpt[c] or c or 0
129 if not rawget(self, thread) then
130 return nil
131 end
132 return rawget(self, thread)[key]
133 end
134
135 local function set(self, key, value)
136 local c = coroutine.running()
137 local thread = coxpt[c] or c or 0
138 if not rawget(self, thread) then
139 rawset(self, thread, {})
140 end
141 rawget(self, thread)[key] = value
142 end
143
144 setmetatable(tbl, {__index = get, __newindex = set, __mode = "k"})
145
146 return tbl
147 end
148
149
150 --
151 -- Debugging routines
152 --
153
154 --- Write given object to stderr.
155 -- @param obj Value to write to stderr
156 -- @return Boolean indicating wheather the write operation was successful
157 function perror(obj)
158 io.stderr:write(tostring(obj) .. "\n")
159 end
160
161 --- Recursively dumps a table to stdout, useful for testing and debugging.
162 -- @param t Table value to dump
163 -- @param i Number of tabs to prepend to each line
164 -- @return Always nil
165 function dumptable(t, i)
166 i = i or 0
167 for k,v in pairs(t) do
168 print(string.rep("\t", i) .. tostring(k), tostring(v))
169 if type(v) == "table" then
170 dumptable(v, i+1)
171 end
172 end
173 end
174
175
176 --
177 -- String and data manipulation routines
178 --
179
180 --- Escapes all occurences of the given character in given string.
181 -- @param s String value containing unescaped characters
182 -- @param c String value with character to escape (optional, defaults to "\")
183 -- @return String value with each occurence of character escaped with "\"
184 function escape(s, c)
185 c = c or "\\"
186 return s:gsub(c, "\\" .. c)
187 end
188
189 --- Create valid XML PCDATA from given string.
190 -- @param value String value containing the data to escape
191 -- @return String value containing the escaped data
192 function pcdata(value)
193 value = value:gsub("&", "&amp;")
194 value = value:gsub('"', "&quot;")
195 value = value:gsub("'", "&apos;")
196 value = value:gsub("<", "&lt;")
197 return value:gsub(">", "&gt;")
198 end
199
200 --- Splits given string on a defined seperator sequence and return a table
201 -- containing the resulting substrings. The optional max parameter specifies
202 -- the number of bytes to process, regardless of the actual length of the given
203 -- string. The optional last parameter, regex, sepcifies wheather the separator
204 -- sequence is interpreted as regular expression.
205 -- @param str String value containing the data to split up
206 -- @param pat String with separator pattern (optional, defaults to "\n")
207 -- @param max Num of bytes to process (optional, default is string length)
208 -- @param regexp Boolean indicating wheather to interprete the separator
209 -- pattern as regular expression (optional, default is false)
210 -- @return Table containing the resulting substrings
211 function split(str, pat, max, regex)
212 pat = pat or "\n"
213 max = max or #str
214
215 local t = {}
216 local c = 1
217
218 if #str == 0 then
219 return {""}
220 end
221
222 if #pat == 0 then
223 return nil
224 end
225
226 if max == 0 then
227 return str
228 end
229
230 repeat
231 local s, e = str:find(pat, c, not regex)
232 max = max - 1
233 if s and max < 0 then
234 table.insert(t, str:sub(c))
235 else
236 table.insert(t, str:sub(c, s and s - 1))
237 end
238 c = e and e + 1 or #str + 1
239 until not s or max < 0
240
241 return t
242 end
243
244 --- Remove leading and trailing whitespace from given string value.
245 -- @param str String value containing whitespace padded data
246 -- @return String value with leading and trailing space removed
247 function trim(str)
248 local s = str:gsub("^%s*(.-)%s*$", "%1")
249 return s
250 end
251
252 --- Parse certain units from the given string and return the canonical integer
253 -- value or 0 if the unit is unknown. Upper- or lowercase is irrelevant.
254 -- Recognized units are:
255 -- o "y" - one year (60*60*24*366)
256 -- o "m" - one month (60*60*24*31)
257 -- o "w" - one week (60*60*24*7)
258 -- o "d" - one day (60*60*24)
259 -- o "h" - one hour (60*60)
260 -- o "min" - one minute (60)
261 -- o "kb" - one kilobyte (1024)
262 -- o "mb" - one megabyte (1024*1024)
263 -- o "gb" - one gigabyte (1024*1024*1024)
264 -- o "kib" - one si kilobyte (1000)
265 -- o "mib" - one si megabyte (1000*1000)
266 -- o "gib" - one si gigabyte (1000*1000*1000)
267 -- @param ustr String containing a numerical value with trailing unit
268 -- @return Number containing the canonical value
269 function parse_units(ustr)
270
271 local val = 0
272
273 -- unit map
274 local map = {
275 -- date stuff
276 y = 60 * 60 * 24 * 366,
277 m = 60 * 60 * 24 * 31,
278 w = 60 * 60 * 24 * 7,
279 d = 60 * 60 * 24,
280 h = 60 * 60,
281 min = 60,
282
283 -- storage sizes
284 kb = 1024,
285 mb = 1024 * 1024,
286 gb = 1024 * 1024 * 1024,
287
288 -- storage sizes (si)
289 kib = 1000,
290 mib = 1000 * 1000,
291 gib = 1000 * 1000 * 1000
292 }
293
294 -- parse input string
295 for spec in ustr:lower():gmatch("[0-9%.]+[a-zA-Z]*") do
296
297 local num = spec:gsub("[^0-9%.]+$","")
298 local spn = spec:gsub("^[0-9%.]+", "")
299
300 if map[spn] or map[spn:sub(1,1)] then
301 val = val + num * ( map[spn] or map[spn:sub(1,1)] )
302 else
303 val = val + num
304 end
305 end
306
307
308 return val
309 end
310
311 --- Combines two or more numerically indexed tables into one.
312 -- @param tbl1 Table value to combine
313 -- @param tbl2 Table value to combine
314 -- @param tblN More values to combine
315 -- @return Table value containing all values of given tables
316 function combine(...)
317 local result = {}
318 for i, a in ipairs(arg) do
319 for j, v in ipairs(a) do
320 table.insert(result, v)
321 end
322 end
323 return result
324 end
325
326 --- Checks whether the given table contains the given value.
327 -- @param table Table value
328 -- @param value Value to search within the given table
329 -- @return Boolean indicating wheather the given value occurs within table
330 function contains(table, value)
331 for k, v in pairs(table) do
332 if value == v then
333 return k
334 end
335 end
336 return false
337 end
338
339 --- Update values in given table with the values from the second given table.
340 -- Both table are - in fact - merged together.
341 -- @param t Table which should be updated
342 -- @param updates Table containing the values to update
343 -- @return Always nil
344 function update(t, updates)
345 for k, v in pairs(updates) do
346 t[k] = v
347 end
348 end
349
350 --- Clones the given object and return it's copy.
351 -- @param object Table value to clone
352 -- @param deep Boolean indicating wheather to do recursive cloning
353 -- @return Cloned table value
354 function clone(object, deep)
355 local copy = {}
356
357 for k, v in pairs(object) do
358 if deep and type(v) == "table" then
359 v = clone(v, deep)
360 end
361 copy[k] = v
362 end
363
364 setmetatable(copy, getmetatable(object))
365
366 return copy
367 end
368
369
370 --
371 -- Byte code manipulation routines
372 --
373
374 --- Return the current runtime bytecode of the given function. The byte code
375 -- will be stripped before it is returned.
376 -- @param f Function value to return as bytecode
377 -- @return String value containing the bytecode of the given function
378 function get_bytecode(f)
379 local d = string.dump(f)
380 return d and strip_bytecode(d)
381 end
382
383 --- Strips unnescessary lua bytecode from given string. Information like line
384 -- numbers and debugging numbers will be discarded. Original version by
385 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
386 -- @param code String value containing the original lua byte code
387 -- @return String value containing the stripped lua byte code
388 function strip_bytecode(code)
389 local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
390 local subint
391 if endian == 1 then
392 subint = function(code, i, l)
393 local val = 0
394 for n = l, 1, -1 do
395 val = val * 256 + code:byte(i + n - 1)
396 end
397 return val, i + l
398 end
399 else
400 subint = function(code, i, l)
401 local val = 0
402 for n = 1, l, 1 do
403 val = val * 256 + code:byte(i + n - 1)
404 end
405 return val, i + l
406 end
407 end
408
409 local strip_function
410 strip_function = function(code)
411 local count, offset = subint(code, 1, size)
412 local stripped, dirty = string.rep("\0", size), offset + count
413 offset = offset + count + int * 2 + 4
414 offset = offset + int + subint(code, offset, int) * ins
415 count, offset = subint(code, offset, int)
416 for n = 1, count do
417 local t
418 t, offset = subint(code, offset, 1)
419 if t == 1 then
420 offset = offset + 1
421 elseif t == 4 then
422 offset = offset + size + subint(code, offset, size)
423 elseif t == 3 then
424 offset = offset + num
425 elseif t == 254 or t == 9 then
426 offset = offset + lnum
427 end
428 end
429 count, offset = subint(code, offset, int)
430 stripped = stripped .. code:sub(dirty, offset - 1)
431 for n = 1, count do
432 local proto, off = strip_function(code:sub(offset, -1))
433 stripped, offset = stripped .. proto, offset + off - 1
434 end
435 offset = offset + subint(code, offset, int) * int + int
436 count, offset = subint(code, offset, int)
437 for n = 1, count do
438 offset = offset + subint(code, offset, size) + size + int * 2
439 end
440 count, offset = subint(code, offset, int)
441 for n = 1, count do
442 offset = offset + subint(code, offset, size) + size
443 end
444 stripped = stripped .. string.rep("\0", int * 3)
445 return stripped, offset
446 end
447
448 return code:sub(1,12) .. strip_function(code:sub(13,-1))
449 end
450
451
452 --
453 -- Sorting iterator functions
454 --
455
456 function _sortiter( t, f )
457 local keys = { }
458
459 for k, v in pairs(t) do
460 table.insert( keys, k )
461 end
462
463 local _pos = 0
464 local _len = table.getn( keys )
465
466 table.sort( keys, f )
467
468 return function()
469 _pos = _pos + 1
470 if _pos <= _len then
471 return keys[_pos], t[keys[_pos]]
472 end
473 end
474 end
475
476 --- Return a key, value iterator which returns the values sorted according to
477 -- the provided callback function.
478 -- @param t The table to iterate
479 -- @param f A callback function to decide the order of elements
480 -- @return Function value containing the corresponding iterator
481 function spairs(t,f)
482 return _sortiter( t, f )
483 end
484
485 --- Return a key, value iterator for the given table.
486 -- The table pairs are sorted by key.
487 -- @param t The table to iterate
488 -- @return Function value containing the corresponding iterator
489 function kspairs(t)
490 return _sortiter( t )
491 end
492
493 --- Return a key, value iterator for the given table.
494 -- The table pairs are sorted by value.
495 -- @param t The table to iterate
496 -- @return Function value containing the corresponding iterator
497 function vspairs(t)
498 return _sortiter( t, function (a,b) return t[a] < t[b] end )
499 end
500
501
502 --
503 -- Coroutine safe xpcall and pcall versions modified for Luci
504 -- original version:
505 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
506 --
507
508 local performResume, handleReturnValue
509 local oldpcall, oldxpcall = pcall, xpcall
510 coxpt = {}
511 setmetatable(coxpt, {__mode = "kv"})
512
513 --- (ToDo: docu)
514 function coxpcall(f, err, ...)
515 local res, co = oldpcall(coroutine.create, f)
516 if not res then
517 local params = {...}
518 local newf = function() return f(unpack(params)) end
519 co = coroutine.create(newf)
520 end
521 local c = coroutine.running()
522 coxpt[co] = coxpt[c] or c or 0
523
524 return performResume(err, co, ...)
525 end
526
527 --- (ToDo: docu)
528 function copcall(f, ...)
529 return coxpcall(f, id, ...)
530 end
531
532 --- (ToDo: docu)
533 local function id(trace, ...)
534 return ...
535 end
536
537 --- (ToDo: docu)
538 function handleReturnValue(err, co, status, ...)
539 if not status then
540 return false, err(debug.traceback(co, (...)), ...)
541 end
542 if coroutine.status(co) == 'suspended' then
543 return performResume(err, co, coroutine.yield(...))
544 else
545 return true, ...
546 end
547 end
548
549 --- (ToDo: docu)
550 function performResume(err, co, ...)
551 return handleReturnValue(err, co, coroutine.resume(co, ...))
552 end