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