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