Coxpcall
Coroutine-safe `xpcall` and `pcall` versions

## Overview

Coxpcall encapsulates the protected calls with a coroutine based loop, so errors can be dealed without the usual `pcall`/`xpcall` issues with coroutines.

Using Coxpcall usually consists in simply loading the module and then replacing Lua `pcall`, `xpcall` and `coroutine.running` by `copcall`, `coxpcall`, and `running`.

Coxpcall is free software and uses the same license as Lua 5.1 and 5.2.

## Status

It supports Lua 5.1, 5.2 and 5.3. Lua 5.2 was extended with the Coxpcall functionality and hence coxpcall is no longer required. The 5.2+ compatibility by coxpcall means that it maintains backward compatibility while using the built-in implementation.

## Download

You can get Coxpcall using LuaRocks:

    luarocks install coxpcall

See also its GitHub page.

## Reference

Coxpcall module offers three functions that reproduce the behaviour of `pcall`, `xpcall`, and `coroutine.running`:

    local coxpcall = require "coxpcall"

`coxpcall.xpcall(f, err)`
  Offers the same functionality as Lua `xpcall(f, err)`, but calls the error handler after the error unwinds the stack, so that it's impossible to gather more information about the error. To compensate, if the error is a string, stack trace is appended to it. Also set as global `coxpcall`.
`coxpcall.pcall(f, ...)`
  Offers the same functionality as Lua `pcall(f, ...)`. Also set as global `copcall`.
`coxpcall.running([coro])`
  Because `coxpcall` and `copcall` run the function to protect inside a new coroutine, `coroutine.running()` will return an unexpected coroutine when used inside the protected function. If the coroutine `coro` was created by the coxpcall module, then `running(coro)` will return the original coroutine that created it. If `coro` is not provided, it will default to the currently running coroutine.

## Credits

Coxpcall was designed and implemented by Roberto Ierusalimschy and André Carregal with the colaboration of Thomas Harning Jr., Ignacio Burgueño, Gary NG and Fábio Mascarenhas as part of the Kepler Project which holds its copyright.

Valid XHTML 1.0!