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 tblN  More values 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 -- Test whether the given table value is a numerically indexed table.
 379 function _is_numeric_table(t)
 380         local k = pairs(t)(t)
 381         return ( tonumber(k) ~= nil )
 382 end
 383
 384 -- Serialize the contents of a table value.
 385 function _serialize_table(t)
 386         local data = ""
 387         if _is_numeric_table(t) then
 388                 for i, v in ipairs(t) do
 389                         v = serialize_data(v)
 390                         data = data .. ( #data > 0 and ", " or "" ) .. v
 391                 end
 392         else
 393                 for k, v in pairs(t) do
 394                         k = serialize_data(k)
 395                         v = serialize_data(v)
 396                         data = data .. ( #data > 0 and "; " or "" ) ..
 397                                 '[' .. k .. '] = ' .. v
 398                 end
 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 tostring(val)
 414         elseif type(val) == "string" then
 415                 val = val:gsub("\\", "\\\\")
 416                                  :gsub("\r", "\\r")
 417                                  :gsub("\n", "\\n")
 418                                  :gsub('"','\\"')
 419                 return '"' .. val .. '"'
 420         elseif type(val) == "boolean" then
 421                 return val and "true" or "false"
 422         elseif type(val) == "table" then
 423                 return "{ " .. _serialize_table(val) .. " }"
 424         else
 425                 return '"[unhandled data type:' .. type(val) .. ']"'
 426         end
 427 end
 428
 429 --- Restore data previously serialized with serialize_data().
 430 -- @param str   String containing the data to restore
 431 -- @return              Value containing the restored data structure
 432 -- @see                 serialize_data
 433 -- @see                 get_bytecode
 434 function restore_data(str)
 435         return loadstring("return " .. str)()
 436 end
 437
 438
 439 --
 440 -- Byte code manipulation routines
 441 --
 442
 443 --- Return the current runtime bytecode of the given data. The byte code
 444 -- will be stripped before it is returned if the given value is a function.
 445 -- @param val   Value to return as bytecode
 446 -- @return              String value containing the bytecode of the given data
 447 function get_bytecode(val)
 448         if type(val) == "function" then
 449                 local code = string.dump(val)
 450                 return code and strip_bytecode(code)
 451         else
 452                 return string.dump( loadstring( "return " .. serialize_data(val) ) )
 453         end
 454 end
 455
 456 --- Strips unnescessary lua bytecode from given string. Information like line
 457 -- numbers and debugging numbers will be discarded. Original version by
 458 -- Peter Cawley (http://lua-users.org/lists/lua-l/2008-02/msg01158.html)
 459 -- @param code  String value containing the original lua byte code
 460 -- @return              String value containing the stripped lua byte code
 461 function strip_bytecode(code)
 462         local version, format, endian, int, size, ins, num, lnum = code:byte(5, 12)
 463         local subint
 464         if endian == 1 then
 465                 subint = function(code, i, l)
 466                         local val = 0
 467                         for n = l, 1, -1 do
 468                                 val = val * 256 + code:byte(i + n - 1)
 469                         end
 470                         return val, i + l
 471                 end
 472         else
 473                 subint = function(code, i, l)
 474                         local val = 0
 475                         for n = 1, l, 1 do
 476                                 val = val * 256 + code:byte(i + n - 1)
 477                         end
 478                         return val, i + l
 479                 end
 480         end
 481
 482         local strip_function
 483         strip_function = function(code)
 484                 local count, offset = subint(code, 1, size)
 485                 local stripped, dirty = string.rep("\0", size), offset + count
 486                 offset = offset + count + int * 2 + 4
 487                 offset = offset + int + subint(code, offset, int) * ins
 488                 count, offset = subint(code, offset, int)
 489                 for n = 1, count do
 490                         local t
 491                         t, offset = subint(code, offset, 1)
 492                         if t == 1 then
 493                                 offset = offset + 1
 494                         elseif t == 4 then
 495                                 offset = offset + size + subint(code, offset, size)
 496                         elseif t == 3 then
 497                                 offset = offset + num
 498                         elseif t == 254 or t == 9 then
 499                                 offset = offset + lnum
 500                         end
 501                 end
 502                 count, offset = subint(code, offset, int)
 503                 stripped = stripped .. code:sub(dirty, offset - 1)
 504                 for n = 1, count do
 505                         local proto, off = strip_function(code:sub(offset, -1))
 506                         stripped, offset = stripped .. proto, offset + off - 1
 507                 end
 508                 offset = offset + subint(code, offset, int) * int + int
 509                 count, offset = subint(code, offset, int)
 510                 for n = 1, count do
 511                         offset = offset + subint(code, offset, size) + size + int * 2
 512                 end
 513                 count, offset = subint(code, offset, int)
 514                 for n = 1, count do
 515                         offset = offset + subint(code, offset, size) + size
 516                 end
 517                 stripped = stripped .. string.rep("\0", int * 3)
 518                 return stripped, offset
 519         end
 520
 521         return code:sub(1,12) .. strip_function(code:sub(13,-1))
 522 end
 523
 524
 525 --
 526 -- Sorting iterator functions
 527 --
 528
 529 function _sortiter( t, f )
 530         local keys = { }
 531
 532         for k, v in pairs(t) do
 533                 table.insert( keys, k )
 534         end
 535
 536         local _pos = 0
 537         local _len = table.getn( keys )
 538
 539         table.sort( keys, f )
 540
 541         return function()
 542                 _pos = _pos + 1
 543                 if _pos <= _len then
 544                         return keys[_pos], t[keys[_pos]]
 545                 end
 546         end
 547 end
 548
 549 --- Return a key, value iterator which returns the values sorted according to
 550 -- the provided callback function.
 551 -- @param t     The table to iterate
 552 -- @param f A callback function to decide the order of elements
 553 -- @return      Function value containing the corresponding iterator
 554 function spairs(t,f)
 555         return _sortiter( t, f )
 556 end
 557
 558 --- Return a key, value iterator for the given table.
 559 -- The table pairs are sorted by key.
 560 -- @param t     The table to iterate
 561 -- @return      Function value containing the corresponding iterator
 562 function kspairs(t)
 563         return _sortiter( t )
 564 end
 565
 566 --- Return a key, value iterator for the given table.
 567 -- The table pairs are sorted by value.
 568 -- @param t     The table to iterate
 569 -- @return      Function value containing the corresponding iterator
 570 function vspairs(t)
 571         return _sortiter( t, function (a,b) return t[a] < t[b] end )
 572 end
 573
 574
 575 --
 576 -- Coroutine safe xpcall and pcall versions modified for Luci
 577 -- original version:
 578 -- coxpcall 1.13 - Copyright 2005 - Kepler Project (www.keplerproject.org)
 579 --
 580
 581 local performResume, handleReturnValue
 582 local oldpcall, oldxpcall = pcall, xpcall
 583 coxpt = {}
 584 setmetatable(coxpt, {__mode = "kv"})
 585
 586 -- Identity function for copcall
 587 local function copcall_id(trace, ...)
 588   return ...
 589 end
 590
 591 --- This is a coroutine-safe drop-in replacement for Lua's "xpcall"-function
 592 -- @param f             Lua function to be called protected
 593 -- @param err   Custom error handler
 594 -- @param ...   Parameters passed to the function
 595 -- @return              A boolean whether the function call succeeded and the return
 596 --                              values of either the function or the error handler
 597 function coxpcall(f, err, ...)
 598         local res, co = oldpcall(coroutine.create, f)
 599         if not res then
 600                 local params = {...}
 601                 local newf = function() return f(unpack(params)) end
 602                 co = coroutine.create(newf)
 603         end
 604         local c = coroutine.running()
 605         coxpt[co] = coxpt[c] or c or 0
 606
 607         return performResume(err, co, ...)
 608 end
 609
 610 --- This is a coroutine-safe drop-in replacement for Lua's "pcall"-function
 611 -- @param f             Lua function to be called protected
 612 -- @param ...   Parameters passed to the function
 613 -- @return              A boolean whether the function call succeeded and the returns
 614 --                              values of the function or the error object
 615 function copcall(f, ...)
 616         return coxpcall(f, copcall_id, ...)
 617 end
 618
 619 -- Handle return value of protected call
 620 function handleReturnValue(err, co, status, ...)
 621         if not status then
 622                 return false, err(debug.traceback(co, (...)), ...)
 623         end
 624         if coroutine.status(co) == 'suspended' then
 625                 return performResume(err, co, coroutine.yield(...))
 626         else
 627                 return true, ...
 628         end
 629 end
 630
 631 -- Resume execution of protected function call
 632 function performResume(err, co, ...)
 633         return handleReturnValue(err, co, coroutine.resume(co, ...))
 634 end