[Home] [Downloads] [Search] [Help/forum]

Register forum user name Search FAQ



Calls a function in protected mode


ok, result [ , result2 ...] = pcall (f, arg1, arg2, ...)


Calls function f with the supplied arguments in protected mode. Catches errors and returns:

On success:

  • true
  • function result(s) - may be more than one

On failure:

  • false
  • error message

function f (v)
  return v + 2
end -- f

a, b = pcall (f, 1)
print (a, b) --> true 3

a, b = pcall (f, "a")
print (a, b)  --> false   stdin:2: attempt to perform arithmetic on local `v' (a string value)

If you are expecting to get multiple return values from the protected function, then the code below would let you do that:

-- see: http://lua-users.org/lists/lua-l/2009-11/msg00269.html
local function pack (...)
  return { n = select("#", ...); ... }

-- calls a function (f) with multiple arguments in protected mode
-- shows the error reason if there is one
local function ProtectedCall (name, f, ...)
  -- protected call of f, get all results
  local r = pack (pcall (f, ...)) -- call function, get all results
  -- first result is false if the function failed, and second result is the reason
  if not r [1] then
    print ("Failure in " .. name .. ": " .. r [2])
    return nil
  end -- if
  -- otherwise all the returned results are in table item 2 onwards
  return unpack (r, 2, r.n) 
end -- ProtectedCall

The "name" argument above is a string that is the name of the function being called, and "f" is the actual function. After that are the arguments. The name could be a description instead, it is just used in the error message. For example:

a, b, c = ProtectedCall ("myfunction", myfunction, 1, 2, 3, 4)

If the return value in "a" is nil then you know the function failed (unless it could possibly return nil, in which case you would need a different method of detecting a failure, if that was important).

See Also ...

Lua functions

assert - Asserts that condition is not nil and not false
collectgarbage - Collects garbage
dofile - Executes a Lua file
error - Raises an error message
gcinfo - Returns amount of dynamic memory in use
getfenv - Returns the current environment table
getmetatable - Returns the metatable for the object
ipairs - Iterates over a numerically keyed table
load - Loads a chunk by calling a function repeatedly
loadfile - Loads a Lua file and parses it
loadlib - Loads a DLL (obsolete in Lua 5.1)
loadstring - Compiles a string of Lua code
module - Creates a Lua module
next - Returns next key / value pair in a table
pairs - Traverse all items in a table
print - Prints its arguments
rawequal - Compares two values for equality without invoking metamethods
rawget - Gets the value of a table item without invoking metamethods
rawset - Sets the value of a table item without invoking metamethods
require - Loads a module
select - Returns items in a list
setfenv - Sets a function's environment
setmetatable - Sets the metatable for a table
tonumber - Converts a string (of the given base) to a number
tostring - Converts its argument to a string
type - Returns the type of a variable
unpack - Unpacks a table into individual items
xpcall - Calls a function with a custom error handler


Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Scripting callbacks - plugins

(Help topic: lua=pcall)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Search for:   

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at HostDash]