|
|
| (10 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| {{User:Merlin11188/Templates/NoEdit}} | | {{User:Merlin11188/Templates/NoEdit}} |
| {{Map|Function Dump}}
| |
|
| |
|
| ==Basic Functions==
| |
|
| |
|
| The basic library provides some core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities.
| | {{Stub}} |
| | {| |
| | |[[File:Home_Subpage.png|frame|A picture of the 'Home' tab on the submenu in 'My ROBLOX'.]] <br/> |
| | |} |
| | __TOC__ |
|
| |
|
|
| |
|
| ===assert (<var>v</var> [, <var>message</var>])=== | | ===Character and Notifications=== |
| | {| |
| | |On the far left of the page there is a picture of [[My_Character|your character]]. Underneath, there is a link to your system notifications. |
| | |[[File:Avatar_Notifications.png|frame|A picture of [[My_Character|your character]] with system notifications beneath it.]] |
| | |} |
|
| |
|
| | ===Best Friends=== |
| | {| |
| | |Underneath of your avatar and notification box is your [[Friends#Best_Friends|best friends]] list. Here you can see what your best friends are doing (from their [[My_Home#Status_Update|shout box]]) and whether or not they're online. |
| | |[[File:Best_Friends.png|frame|This a list of your [[Friends#Best_Friends|best friends]] and their most recent shouts!]] |
| | |} |
|
| |
|
| Issues an error when the value of its argument v is false (i.e., nil or false); otherwise, returns all its arguments. message is an error message; when absent, it defaults to "assertion failed!"
| | ===Status Update=== |
| | {| |
| | |You can use this so that people who visit your profile can see what you're up to. |
| | |[[File:Status Update.png|frame|This is the status update bar. People who have you as their [[Friends#Best_Friends|best friend]] will see it on their [[My_Home|home]]!]] |
| | |} |
|
| |
|
| {{Example|{{Code and output|code= | | ===Feed=== |
| assert (false, "This is an error message")
| | {| |
| assert (false)
| | |Your feed is in the center of the page, just beneath your status update box. Your feed is a way to keep you updated with all of your groups. Every time someone uses the shout box in one of your [[groups]], you're updated here! |
| assert (true)
| | |[[File:Feed bar.png|frame|This is for your feed—all of your [[groups]]' shouts go here.]] |
| |output= | | |} |
| Tue Oct 07 10:15:37 2008 - Cmd:1: This is an error message
| |
| Tue Oct 07 10:15:37 2008 - Cmd, line 1
| |
| Tue Oct 07 10:15:37 2008 - stack end
| |
|
| |
|
| Tue Oct 07 10:14:18 2008 - Cmd:1: assertion failed!
| | ===Recently Played Games=== |
| Tue Oct 07 10:14:18 2008 - Cmd, line 1
| | {| |
| Tue Oct 07 10:14:18 2008 - stack end
| | |On the far right is the 'Recently Played Games' box. Your most recently played games can be seen here. If you want a larger list, you can click the '''See More''' button. |
| | |[[File:Recently_Played_Games.png|frame|This is a list of your most recently played [[game]]s.]] |
| | |} |
|
| |
|
| -- Won't display anything at all.
| | ===Facebook Connect=== |
| }}}}
| | {| |
| | |On the far right, underneath of the 'Recently Played Games' box is the Facebook connect box. If you have a Facebook account, you can link it to your ROBLOX account! See [[connecting your account to Facebook]] for more info. |
| | |[[File:FacebookConnect_Unconnected.png|frame|Facebook connect. You can use this to link your Facebook account to your [[Roblox|ROBLOX]] account! Your personal info will '''not''' be shared with other users!]] |
| | |} |
|
| |
|
| ===collectgarbage (<var>opt</var> [, <var>arg</var>])===
| | <!-- |
| | | {| class="wikitable" style="border-spacing: 0px; padding: 0px;" |
| | | |- |
| This function is a generic interface to the garbage collector. It performs different functions according to its first argument, opt:
| | |[[File:Avatar + Notifications]] |
| | | |[[File:Status_Update.png]] |
| * ''stop'': stops the garbage collector.
| | |[[File:Recently_Played_Games.png|287px]] |
| * ''restart'': restarts the garbage collector.
| | |- |
| * ''collect'': performs a full garbage-collection cycle.
| | |[[File:Best_Friends.png]] |
| * ''count'': returns the total memory in use by Lua (in Kbytes).
| | |<div style="top:0px;">[[File:Feed_bar.png]]</div> |
| * ''step'': performs a garbage-collection step. The step "size" is controlled by arg (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of arg. Returns true if the step finished a collection cycle.
| | |[[File:FacebookConnect_Unconnected.png]] |
| * ''setpause'': sets arg/100 as the new value for the pause of the collector (see §2.10).
| | |}--> |
| * ''setstepmul'': sets arg/100 as the new value for the step multiplier of the collector (see §2.10).
| |
| | |
| {{Example|{{Code and output|fit=output|code= | |
| t = {}
| |
| for i = 0,20000 do
| |
| table.insert(t,i,i)
| |
| end
| |
| | |
| print(collectgarbage("count"))
| |
| t = nil
| |
| print(collectgarbage("count"))
| |
| |output=
| |
| ~535.7998046875
| |
| ~23.7197265625
| |
| }}}}
| |
| | |
| ===dofile (<var>filename</var>)===
| |
| | |
| | |
| Opens the named file and executes its contents as a Lua chunk. When called without arguments, dofile executes the contents of the standard input (stdin). Returns all values returned by the chunk. In case of errors, dofile propagates the error to its caller (that is, dofile does not run in protected mode).
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| '''File:''' Hello.luq
| |
| '''Contents:''' print("Hello World!")
| |
| | |
| dofile("C:/Hello.lua")
| |
| |output=
| |
| Hello World!
| |
| | |
| }}}}
| |
| | |
| ===error (<var>message</var> [, <var>level</var>])===
| |
| | |
| | |
| Terminates the last protected function called and returns message as the error message. Function error never returns.
| |
| | |
| Usually, error adds some information about the error position at the beginning of the message. The level argument specifies how to get the error position. With level 1 (the default), the error position is where the error function was called. Level 2 points the error to where the function that called error was called; and so on. Passing a level 0 avoids the addition of error position information to the message.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| error ("this is an error message")
| |
| |output=
| |
| Tue Oct 07 08:18:36 2008 - Cmd:1: this is an error message
| |
| Tue Oct 07 08:18:36 2008 - Cmd, line 1
| |
| Tue Oct 07 08:18:36 2008 - stack end
| |
| }}}}
| |
| | |
| ===_G===
| |
| | |
| | |
| A [[Tables|table]] that is shared between all scripts in one instance of Roblox. Scripts can use this to share data, including functions, between them.
| |
| | |
| Notes:
| |
| *In [[Online mode]], scripts running in a [[LocalScript]] run on the player's computer, so they are in a separate instance of Roblox and can't share data with non-local scripts except by using objects such as [[IntValue]].
| |
| *Until recently, this was the table that all the built-in functions were stored in, and it was possible to read values from it without writing "_G" in front. This is no longer the case.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| --Script one:
| |
| _G.variable = "This a variable in _G."
| |
| | |
| --Script two:
| |
| while _G.variable == nil do wait() end --make sure that script one sets the variable before this one tries to read it
| |
| print(_G.variable)
| |
| |output= | |
| "This a variable in _G."
| |
| }}}}
| |
| | |
| See also [[Global Functions]].
| |
| | |
| ===<s>gcinfo ()</s>===
| |
| | |
| Returns amount of dynamic memory in use. This is deprecated. Use collectgarbage ("count") instead.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print (gcinfo ())
| |
| a=collectgarbage ("count")
| |
| print(a)
| |
| |output=
| |
| 28
| |
| 29.6875
| |
| }}}}
| |
| | |
| ===getfenv ([<var>f</var>])===
| |
| | |
| | |
| Returns the current environment in use by the function. f can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling getfenv. If the given function is not a Lua function, or if f is 0, getfenv returns the global environment. The default for f is 1.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| | |
| var1 = 7
| |
| var2 = 9
| |
| for i, v in pairs(getfenv()) do
| |
| print(i, " = ", v)
| |
| end
| |
| |output=
| |
| script = Script
| |
| var1 = 7
| |
| var2 = 9
| |
| | |
| }}}}
| |
| | |
| ===getmetatable (<var>object</var>)===
| |
| | |
| | |
| If object does not have a metatable, returns nil. Otherwise, if the object's metatable has a "__metatable" field, returns the associated value. Otherwise, returns the metatable of the given object.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| | |
| t = {}
| |
| print(getmetatable(t))
| |
| setmetatable(t,{})
| |
| print(getmetatable(t))
| |
| |output=
| |
| nil
| |
| table: [hexadecimal memory address]
| |
| }}}}
| |
| | |
| ===ipairs (<var>t</var>)===
| |
| | |
| | |
| Returns three values: an iterator function, the table t, and 0, so that the construction
| |
| <code lua>
| |
| for i,v in ipairs(t) do
| |
| --body
| |
| end
| |
| </code>
| |
| | |
| will iterate over the pairs (1,t[1]), (2,t[2]), ···, up to the first integer key absent from the table.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| | |
| t = {'a', 'b', 'c', nil, 'd'}
| |
| for i,v in ipairs(t) do
| |
| print(i, v)
| |
| end
| |
| |output= | |
| 1 a
| |
| 2 b
| |
| 3 c
| |
| }}}}
| |
| | |
| ===load (<var>func</var> [, <var>chunkname</var>])===
| |
| | |
| | |
| Loads a chunk using function func to get its pieces. Each call to func must return a string that concatenates with previous results. A return of nil (or no value) signals the end of the chunk.
| |
| | |
| If there are no errors, returns the compiled chunk as a function; otherwise, returns nil plus the error message. The environment of the returned function is the global environment.
| |
| | |
| chunkname is used as the chunk name for error messages and debug information.
| |
| | |
| | |
| ===loadfile ([<var>filename</var>])===
| |
| | |
| | |
| Similar to load, but gets the chunk from file filename or from the standard input, if no file name is given.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| '''File:''' file.lua
| |
| '''Contents:''' print("This is the contents of a file.")
| |
| | |
| f = loadfile("C:/file.lua")
| |
| f()
| |
| |output= | |
| This is the contents of a file.
| |
| }}}}
| |
| | |
| | |
| ===loadstring (<var>string</var> [, <var>chunkname</var>])===
| |
| | |
| | |
| Similar to load, but gets the chunk from the given string.
| |
| Loadstring returns a [[function]].
| |
| | |
| To load and run a given string, use the idiom
| |
| <code lua>
| |
| assert(loadstring(s))()
| |
| </code>
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| a = 2
| |
| loadstring("b = 3")() -- This loads the string to a function, and then calls that function.
| |
| print(a+b)
| |
| a = 5
| |
| b = 1
| |
| change = loadstring("b = 2")
| |
| print(a+b)
| |
| change()
| |
| print(a+b)
| |
| |output= | |
| 5
| |
| 6
| |
| 7
| |
| }}}}
| |
| | |
| ===<var>newproxy</var> (boolean ''or'' proxy)===
| |
| ''Undocumented feature of Lua.''
| |
| | |
| Arguments:
| |
| boolean - returned proxy has metatable
| |
| ''or''
| |
| userdata - different proxy created with newproxy
| |
| | |
| Creates a blank userdata with an empty metatable, or with the metatable of another proxy.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| local a = newproxy(true)
| |
| local mt = getmetatable(a)
| |
| print( mt ~= nil )
| |
| | |
| local b = newproxy(a)
| |
| print( mt == getmetatable(b) )
| |
| | |
| local c = newproxy(false)
| |
| print( getmetatable(c) ~= nil )
| |
| | |
| print( a.Name )
| |
| mt.__index = {Name="Proxy"}
| |
| print( a.Name )
| |
| print( b.Name )
| |
| |output=
| |
| true
| |
| true
| |
| false
| |
| attempt to index local 'a' (a userdata value)
| |
| Proxy
| |
| Proxy
| |
| }}}}
| |
| | |
| ===next (<var>table</var> [, <var>index</var>])===
| |
| | |
| | |
| Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. next returns the next index of the table and its associated value. When called with nil as its second argument, next returns an initial index and its associated value. When called with the last index, or with nil in an empty table, next returns nil. If the second argument is absent, then it is interpreted as nil. In particular, you can use next(t) to check whether a table is empty.
| |
| | |
| The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numeric order, use a numerical for or the ipairs function.)
| |
| | |
| The behavior of next is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may clear existing fields.
| |
| | |
| {{Example|{{Code and output|code=
| |
| days = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}
| |
| print(next(days))
| |
| print(next(days,4))
| |
| |output=
| |
| 1 Sunday
| |
| 5 Thursday -- cf. print(days[4]), which gives you Wednesday
| |
| }}}}
| |
| | |
| ===pairs (<var>t</var>)===
| |
| | |
| | |
| Returns three values: the next function, the table t, and nil, so that the construction
| |
| <code lua>
| |
| for k,v in pairs(t) do body end
| |
| </code>
| |
| | |
| will iterate over all key–value pairs of table t.
| |
| | |
| See function next for the caveats of modifying the table during its traversal.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| t = {1,2,"a","d",c = 12, q = 20}
| |
| for i,v in pairs(t) do
| |
| print(i,v)
| |
| end
| |
| |output= | |
| 1 1
| |
| 2 2
| |
| 3 a
| |
| 4 d
| |
| c 12
| |
| q 20
| |
| }}
| |
| | |
| ===pcall (<var>f</var>, <var>arg1</var>, <var>···</var>)===
| |
| | |
| | |
| Calls function f with the given arguments in protected mode. This means that any error inside f is not propagated; instead, pcall catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, pcall also returns all results from the call, after this first result. In case of any error, pcall returns false plus the error message.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| if pcall (function() print("Hi Mom!") end) then
| |
| else print("There were errors")
| |
| end
| |
| | |
| if pcall (function() ppppprint("Hi Mom!") end) then
| |
| else print("There were errors")
| |
| end
| |
| |output=
| |
| Hi Mom!
| |
| | |
| There were errors
| |
| }}}}
| |
| | |
| '''NOTE:''' You cannot use a function that yields the running coroutine in use by pcall. That includes the wait function. You will get an error about not being able to resume a dead coroutine and not being able to yield across the C boundary.
| |
| | |
| ===print (<var>···</var>)===
| |
| | |
| | |
| Receives any number of arguments, and prints their values to the output, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print ("Hello!")
| |
| |output=
| |
| Hello!
| |
| }}}}
| |
| | |
| ===rawequal (<var>v1</var>, <var>v2</var>)===
| |
| | |
| | |
| Checks whether v1 is equal to v2, without invoking any metamethod. Returns a boolean.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print(rawequal (5, 3))
| |
| print(rawequal (5, 5))
| |
| |output=
| |
| false
| |
| true
| |
| }}}}
| |
| | |
| ===rawget (<var>table</var>, <var>index</var>)===
| |
| | |
| | |
| Gets the real value of table[index], without invoking any [[Metatables#Metamethods|metamethod]]. table must be a table; index may be any value.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| days = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}
| |
| print(rawget (days, 2))
| |
| |output=
| |
| Monday
| |
| }}}}
| |
| | |
| ===rawset (<var>table</var>, <var>index</var>, <var>value</var>)===
| |
| | |
| | |
| Sets the real value of table[index] to value, without invoking any metamethod. table must be a table, index any value different from nil, and value any Lua value.
| |
| | |
| This function returns table.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| rawset (_G, "test", 42)
| |
| print (test)
| |
| |output=
| |
| 42
| |
| }}}}
| |
| | |
| ===select (<var>index</var>, <var>···</var>)===
| |
| | |
| | |
| If index is a number, returns all arguments after argument number index. Otherwise, index must be the string "#", and select returns the total number of extra arguments it received.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print(select (3, "a", "b", "c", "d", "e", 1, 2, 3))
| |
| print(select ("#", "a", "b", "c", "d", "e", 1, 2, 3))
| |
| |output=
| |
| c d e 1 2 3
| |
| 8
| |
| }}}}
| |
| | |
| ===setfenv (<var>f</var>, <var>table</var>)===
| |
| | |
| | |
| Sets the environment to be used by the given function. f can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling setfenv. setfenv returns the given function.
| |
| | |
| As a special case, when f is 0 setfenv changes the environment of the running thread. In this case, setfenv returns no values.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| _G.a = 1 -- create a global variable
| |
| setfenv(1, {_G = _G}) -- change current environment
| |
| _G.print(a)
| |
| _G.print(_G.a)
| |
| |output=
| |
| nil 1
| |
| [http://www.lua.org/pil/14.3.html] | |
| }}}}
| |
| | |
| ===setmetatable (<var>table</var>, <var>metatable</var>)===
| |
| | |
| | |
| Sets the metatable for the given table. (You cannot change the metatable of other types from Lua, only from C.) If metatable is nil, removes the metatable of the given table. If the original metatable has a "__metatable" field, raises an error.
| |
| | |
| This function returns table.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| t = {"a","b","c"}
| |
| mt = {"Orange","Apple","Microsoft"}
| |
| | |
| setmetatable(t,mt)
| |
| | |
| for i,v in pairs(getmetatable(t)) do
| |
| print(i,v)
| |
| end
| |
| |output=
| |
| 1 Orange
| |
| 2 Apple
| |
| 3 Microsoft
| |
| }}}}
| |
| | |
| ===tonumber (<var>e</var> [, <var>base</var>])===
| |
| | |
| | |
| Tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns nil.
| |
| | |
| An optional argument specifies the base to interpret the numeral. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter 'A' (in either upper or lower case) represents 10, 'B' represents 11, and so forth, with 'Z' representing 35. In base 10 (the default), the number may have a decimal part, as well as an optional exponent part (see §2.1). In other bases, only unsigned integers are accepted.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print(tonumber(255))
| |
| print(tonumber (11111111, 2))
| |
| print(tonumber ("FF", 16))
| |
| |output=
| |
| 255
| |
| 255
| |
| 255
| |
| }}}}
| |
| | |
| ===tostring (<var>e</var>)===
| |
| | |
| | |
| Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format.
| |
| | |
| If the [[metatables|metatable]] of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result.
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| a=tostring("The answer to 2+2 is " .. 2+2)
| |
| print(a)
| |
| |output= | |
| The answer to 2+2 is 4
| |
| }}}}
| |
| | |
| ===type (<var>v</var>)===
| |
| | |
| | |
| Returns the type of its only argument, coded as a string. The possible results of this function are "nil" (a string, not the value nil), "number", "string", "boolean", "table", "function", "thread", and "userdata".
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print(type (true))
| |
| print(type (3))
| |
| |output=
| |
| boolean
| |
| number
| |
| }}}}
| |
| | |
| ===unpack (<var>list</var> [, <var>i</var> [, <var>j</var>]])===
| |
| Returns the elements from the given table. This function is equivalent to
| |
| <code lua>
| |
| return list[i], list[i+1], ···, list[j]
| |
| </code>
| |
| | |
| except that the above code can be written only for a fixed number of elements. By default, i is 1 and j is the length of the list, as defined by the length operator (see §2.5.5).
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| t = { "the", "quick", "brown" }
| |
| print (unpack (t))
| |
| |output= | |
| the quick brown
| |
| }}}} | |
| | |
| ===_VERSION===
| |
| | |
| | |
| A global variable (not a function) that holds a string containing the current interpreter version. The current contents of this variable is "Lua 5.1".
| |
| | |
| {{Example|{{Code and output|fit=output|code=
| |
| print(_VERSION)
| |
| |output=
| |
| Lua 5.1
| |
| }}}}
| |
| | |
| ===xpcall (<var>f</var>, <var>err</var>)===
| |
| | |
| | |
| This function is similar to pcall, except that you can set a new error handler.
| |
| | |
| xpcall calls function f in protected mode, using err as the error handler. Any error inside f is not propagated; instead, xpcall catches the error, calls the err function with the original error object, and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In this case, xpcall also returns all results from the call, after this first result. In case of any error, xpcall returns false plus the result from err.
| |
| | |
| {{Example|{{Code and output|code=
| |
| function handle(err)
| |
| return "ERROR: " .. err:gsub("(.-:)","")
| |
| end
| |
| | |
| function f()
| |
| local a = nil
| |
| return a+1
| |
| end
| |
| | |
| print(xpcall(f,handle))
| |
| |output=
| |
| false ERROR: attempt to perform arithmetic on local 'a' (a nil value)
| |
| }}}}
| |
