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