WoW:API loadstring

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ WoW Lua

← WoW Lua

Parse a string as Lua code and return it as a reference to a function.

func, errorMessage = loadstring("luaCodeBlock"[, "chunkName"]);

Arguments

luaCodeBlock

String - a string of Lua code. Can be very long.

chunkName

String - optionally name the code block. Will be shown as the "file name" in error messages. If not given, the file name will be "[string: first line of your Lua code here...]".

Returns

func

Function reference - nil if there was a syntax error in the code block

errorMessage

String - will contain an error message if func was nil.

Examples

Emulating RunScript()

assert(loadstring("DEFAULT_CHAT_FRAME:AddMessage(\"Hello, World!\")")) ();

If an error occurs, the assert will trigger and automatically display the errorMessage return since assert()s second parameter is the error message to display. If it is successful, the function reference returned will also be returned out through the assert() call, and then be executed directly by the "()".

Catching all errors

local func, errorMessage = loadstring("DEFAULT_CHAT_FRAME:AddMessage(\"Hello, World!\")");
if(not func) then
  ... do something with errorMessage and return out?
end
local success, errorMessage = pcall(func);
if(not success) then
  ... do something with errorMessage and return out?
end

Returning values

Since the code block is actually a function, you can return values out of it just like with a function. (ignoring error handling for now)

 local func = assert(loadstring("return 38+4, \"Hello, World!\";"));
 local sum, message = func();

You cannot pass parameters into a loadstring()ed function like you can with regular functions. But, on the other hand, you can freely modify the string itself so getting values into it is usually not a problem.

Protecting the global environment

Lua can manipulate the environment that a function gets to see with setfenv(). It is however important to remember that already-existing functions that the code is allowed to call retain their original environments, so e.g. giving protected code access to the standard setglobal() is probably not a good idea.

local func = assert(loadstring([[
  print( 
    format("format is %s", tostring(format)) 
  );
  print("setglobal is "..tostring(getglobal("setglobal")));
]]));
local smallenv = {format=format, tostring=tostring, getglobal=getglobal};
smallenv.print = function(msg) DEFAULT_CHAT_FRAME:AddMessage(msg); end

setfenv(func, smallenv);
func();

Note how we're using the "[[", "]]" quoting style here. Such strings can span multiple lines. The above could of course also be written in a single line with regular quotes; it's just an example.

The above code cannot manipulate anything in the global environment. All it has access to is what we give it. It will output something like this in the default chat frame:

format is function:00127436
setglobal is nil

If the protected code modifies its environment, e.g. to return values out, we can examine the changes via looking at "smallenv". E.g. if the protected code does greeting = "So long and thanks for the fish";, we get hold of it via accessing smallenv.greeting.

Creating "real" functions through loadstring

local func = assert(loadstring([[
  return function(a,b)
    local result = a+b;
    return result;
  end
]]));

userdefFunc = func();

meaning_of_life_the_universe_and_everything = userdefFunc(38, 4);

Will result in "meaning_of_life_the_universe_and_everything" containing the number 42.