MUSHclient documentation: setfenv

setfenv

setfenv
Lua function setfenv Summary Sets a function's environment Prototype `f = setfenv (f)` Description Sets the current environment to be used by f, which can be a function, userdata, thread or stack level. Level 1 is the current function. Level 0 is the global environment of the current thread. The return value is the function whose environment was changed, unless the argument was 0. function f (v) test = v -- assign to global variable test end -- function f local myenv = {} -- my local environment table setfenv (f, myenv) -- change environment for function f f (42) -- call f with new environment print (test) --> nil (global test was not changed) print (myenv.test) --> 42 (test inside myenv was changed) This can be used as a form of "sandbox", so that functions can run in an environment where they do not have access to normal global variables. For example, in the above code, you could not call "print" from inside function f, as print is not in the environment. To make it accessible you might do this: myenv.print = print -- copy print function into environment table A nice use of the setfenv function is to limit the damage that can be done when reading an external file. An example is to let the user of your script provide a configuration file, that you want to read in. An example might be: a = 42 b = "nick" c = { "the", "quick", "brown", "fox" } A quick way of processing that file would be to: dofile ("config.txt") However if the "config.txt" file contained malicious code (like: os.remove "myapplication.exe") then it could have undesired side-effects. Even a simple assignment like: 'print = nil' could cause problems. The solution is to use setfenv to limit the global environment for this file, like this: config = {} -- empty environment table -- load the file, get a function to execute local f = assert (loadfile ("config.txt")) -- want to load file into the config table setfenv (f, config) -- load it f () print (config.a) --> 42 What this does is change the global environment for the function returned from loadfile to be the empty config table. This means that all "global" variables will be relative to config, not _G. It also means that all the standard functions (like os.remove) are not visible. See Also ... Topics 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 table functions Lua utilities Scripting 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) pcall (Calls a function in protected mode) 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) 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) (Help topic: lua=setfenv) Documentation contents page

Lua function

setfenv

Summary

Sets a function's environment

Prototype

f = setfenv (f)

Description

Sets the current environment to be used by f, which can be a function, userdata, thread or stack level. Level 1 is the current function. Level 0 is the global environment of the current thread.



The return value is the function whose environment was changed, unless the argument was 0.




function f (v)
  test = v  -- assign to global variable test
end -- function f

local myenv = {}  -- my local environment table
setfenv (f, myenv)  -- change environment for function f
f (42)  -- call f with new environment

print (test) --> nil  (global test was not changed)
print (myenv.test)  --> 42  (test inside myenv was changed)




This can be used as a form of "sandbox", so that functions can run in an environment where they do not have access to normal global variables. For example, in the above code, you could not call "print" from inside function f, as print is not in the environment. To make it accessible you might do this:




myenv.print = print -- copy print function into environment table




A nice use of the setfenv function is to limit the damage that can be done when reading an external file.

An example is to let the user of your script provide a configuration file, that you want to read in. An example might be:




a = 42
b = "nick"
c = { "the", "quick", "brown", "fox" }




A quick way of processing that file would be to: dofile ("config.txt")

However if the "config.txt" file contained malicious code (like: os.remove "myapplication.exe") then it could have undesired side-effects. Even a simple assignment like: 'print = nil' could cause problems. The solution is to use setfenv to limit the global environment for this file, like this:




config = {} -- empty environment table
-- load the file, get a function to execute  
local f = assert (loadfile ("config.txt"))
-- want to load file into the config table
setfenv (f, config)
-- load it
f ()
print (config.a)  --> 42 




What this does is change the global environment for the function returned from loadfile to be the empty config table. This means that all "global" variables will be relative to config, not _G. It also means that all the standard functions (like os.remove) are not visible.