Editing WildStar:UI Lua

__NOWYSIWYG__{{\|uilua}}
This is the main reference for the WildStar [[Lua]] runtime, as implemented in the WildStar [[UI]]. See also [[\UI API]].

The [[wildstarwiki:WildStar|WildStar]] Lua runtime is based on Lua 5.1, and generally uses the same standard Lua functions listed on the official [//www.lua.org Lua web site]. Some functions differ slightly in WildStar's implementation and are documented here as well for consistency.

== Reference ==
Nearly all of these functions are part of the default Lua 5.1 runtime environment, described [//www.lua.org/manual/5.1/manual.html here]. Notable omissions are the  operating system, and file I/O libraries.

 /eval Print(_VERSION)
 [debug]: Lua 5.1
<div class="ApiList"><!-- do not remove -->

=== Basic ===
:{{\|id|API|assert}}(val[, sMsg]) returns (val) - returns ''val'' if true, else throws Lua error with sMsg
:{{\|id|API|collectgarbage}}() - forces garbage collection
:{{\|id|API|dofile}}([filename]) - opens the named file and executes its contents as a Lua chunk (stdio not usable in UI)
:{{\|id|API|error}}(sMsg, level) - throws error with message. use [[#pcall|pcall]]() to catch errors
:{{\|id|API|gcinfo}}() returns (nAddOn,nLimit) - gets AddOn memory used and current GC threshold in kB
:{{\|id|API|getfenv}}(any) returns (table) - gets stack frame of given function or stack level number
:{{\|id|API|getmetatable}}(aObject) returns (mtable) - gets metatable for table or userdata
:{{\|id|API|load}}(func [, chunkname]) returns (function) - gets Lua chunk from func stream, until empty, nil, no value
:{{\|id|API|loadfile}}([filename]) returns (function)  - similar to load, but gets from file (stdio not usable in UI)
:{{\|id|API|loadstring}}(string [, chunkname]) returns (function) - gets Lua chunk for a Lua code string
:{{\|id|API|newproxy}}(boolean or proxy) - creates a userdata with a sharable metatable
:{{\|id|API|next}}(table, index) returns (key,value) - gets next key-value pair of the table, allowing you to walk a table
:{{\|id|API|pcall}}(func, arg1, arg2, ...) returns (boolean, results or sMessage) - executes 'func' and returns true and values, otherwise false and error message
:{{\|id|API|print}}(string) - prints to Lua stdio (stdio not usable from UI) 
:{{\|id|API|rawequal}}(v1, v2) returns (boolean) - checks if v1 and v2 are equal, bypassing any metamethods
:{{\|id|API|rawget}}(table, index) - gets real value of table[index], bypassing any metamethods
:{{\|id|API|rawset}}(table, index, value) - sets real table[index] to value, bypassing any metamethods
:{{\|id|API|select}}(nIndex, list) returns (number or item) - gets count if 'index' is "#", or item at 'index'
:{{\|id|API|setfenv}}(function or integer, table) - sets table representing the stack frame for given function or stack level
:{{\|id|API|setmetatable}}(aObject, mtable) returns (any) - sets the metatable of a table or userdata, returns aObject
:{{\|id|API|type}}(any) - gets type of variable as a string: "number", "string", "table", "function" or "userdata"
:{{\|id|API|unpack}}(table[, nStart][, nEnd]) returns (...) - converts indexed values of table to an argument list 
:{{\|id|API|xpcall}}(function, fCallback) returns (boolean,results) - true if successfully executes function, or executes fCallback and returns false. results are return values of function or fCallback

WS UI offers these standard Lua global data vars
:{{\|id|API|_G}} [table] - canonical list of variables in global scope, including ones in this reference
:{{\|id|API|_VERSION}} [string] = "Lua 5.1" - printable Lua runtime version number

=== Strings ===
These string functions are Carbine custom, shorthand references to or a part of the Lua string library "string." See [//lua-users.org/wiki/StringLibraryTutorial StringLibraryTutorial] for more info.

:{{\|id|API|tonumber}}(any[, base]) returns (number) - converts any. nil if fails. non-10 bases accept only unsigned ints
:{{\|id|API|tostring}}(any) - converts to a string, or nil if fails.

These are custom string functions available in WS but not normal Lua.
:{{\|id|API|strRound}}(any[, nPlaces]) returns (number) - converts to number and rounds, default places 0. (Carbine)

==== {{\|id|API|string}} ====
:{{\|id|API|string|byte}}(string[, index]) - gets internal Lua char (byte size number) of the i-th element of string
:{{\|id|API|string|char}}(nByte[, ...]) - compiles one or more Lua chars (byte size numbers) into a string
:{{\|id|API|string|dump}}(function) - returns a binary representation of the given function code as a string
:{{\|id|API|string|find}}(s, pattern[, start[, plain]]) - find match for pattern on s. optional offset or plain sub-string
:{{\|id|API|string|format}}(sFormat[, value[, ...]]) - gets string of values formatted by sFormat format string
:{{\|id|API|string|gfind}}(s, pattern) returns iterator function for pattern over the string s. (deprecated, same as gmatch) 
:{{\|id|API|string|gmatch}}(s, pattern) gets iterator that returns the next captures each call, using pattern on string s 
:{{\|id|API|string|gsub}}(s, pattern, replacement[, nLimit]) - globally substitute pattern for replacement in string
:{{\|id|API|string|len}}(string) - return length of the string in Lua chars (byte size numbers)
:{{\|id|API|string|lower}}(string) - return string converted to all lower case
:{{\|id|API|string|match}}(string, pattern[, initpos]) - similar to strfind, but only returns the matches, not the positions
:{{\|id|API|string|rep}}(string, n [, sep]) - return a string which is ''n'' copies of ''s'', with optional delimeter ''sep'' 
:{{\|id|API|string|reverse}}(string) - reverses a string
:{{\|id|API|string|sub}}(string, index[, endIndex]) - return a substring of string starting at index
:{{\|id|API|string|upper}}(string) - return string converted to all upper case

=== Tables ===
These table functions are shorthand references to the Lua table library (which is available via "table.", see [//lua-users.org/wiki/TableLibraryTutorial TableLibraryTutorial] for more info). Be aware that some table functions only work with tables with proper numerical indexes, where {[1] = "x", [3] = "y"} would have only one indexed value at 1. Not being aware of this fact is one major causes for bugs in code written in Lua.

:{{\|id|API|ipairs}}(table) - gets an iterator of type integer to traverse a table
:{{\|id|API|pairs}}(table) - gets an iterator to traverse a table

==== {{\|id|API|table}} ====
:{{\|id|API|table|concat}}(table [, sep [, i [, j]]]) returns (string) - build a string from table elements
:{{\|id|API|table|foreach}}(table, function) - runs function for each name-value in table. (deprecated, use pairs)
:{{\|id|API|table|foreachi}}(table, function) - runs function for each index in table, in order. (deprecated, use ipairs)
:{{\|id|API|table|getn}}(table) returns (number) - gets cached size of table ''array'' values. (deprecated, use #table operator)
:{{\|id|API|table|insert}}(table[, pos], value) - insert value into table at pos. default is end of table
:{{\|id|API|table|maxn}}(table) returns (number) - last positive numerical index. requires scan of whole table
:{{\|id|API|table|remove}}(table[, pos]) returns (any) - remove and return element at pos. default is last entry in table
:{{\|id|API|table|setn}}(table, number) - attempts to set cached table size value. (deprecated, like getn)
:{{\|id|API|table|sort}}(table[, comp]) - sort the elements in the table in-place, optionally using a custom comparator.

=== Arithmetic ===

==== {{\|id|API|math}} ====
:{{\|id|API|math|abs}}(value) - returns the absolute value of the number
:{{\|id|API|math|acos}}(value) - returns the arc cosine of the value in degrees
:{{\|id|API|math|asin}}(value) - returns the arc sine of the value in degrees
:{{\|id|API|math|atan}}(value) - returns the arc tangent of the value in degrees
:{{\|id|API|math|atan2}}(y, x) - returns the arc tangent of Y/X in degrees
:{{\|id|API|math|ceil}}(value) - returns the ceiling of value
:{{\|id|API|math|cos}}(degrees) - returns the cosine of the degree value
:{{\|id|API|math|cosh}}(value) - returns the hyperbolic cosine of value
:{{\|id|API|math|deg}}(radians) - returns the degree equivalent of the radian value
:{{\|id|API|math|exp}}(value) - returns the exponent of value
:{{\|id|API|math|floor}}(value) - returns the floor of value
:{{\|id|API|math|fmod}}(x, y) - returns remainder of division of x by y, rounding quotient toward zero
:{{\|id|API|math|frexp}}(num) - Extract mantissa and exponent from a floating point number
:{{\|id|API|math|huge}} = 1.#INF
:{{\|id|API|math|ldexp}}(value, exponent) - Load exponent of a floating point number
:{{\|id|API|math|log}}(value) - returns the natural logarithm (log base e) of value
:{{\|id|API|math|log10}}(value) - returns the base-10 logarithm of value
:{{\|id|API|math|max}}(value[, values...]) - returns the numeric maximum of the input values
:{{\|id|API|math|min}}(value[,values...]) - returns the numeric minimum of the input values
:{{\|id|API|math|mod}}(a, b) - returns the integer remainder of a divided by b
:{{\|id|API|math|modf}}(x) - returns two numbers. integral part of x, and fractional part of x
:{{\|id|API|math|pi}} = 3.1415926535898
:{{\|id|API|math|pow}}(x, y) - returns x to power of y. can also use operator ^, as expression x^y
:{{\|id|API|math|rad}}(degrees) - returns the radian equivalent of the degree value
:{{\|id|API|math|random}}([ [lower,] upper]) - returns a random number, optionally bounded integer value
:{{\|id|API|math|randomseed}}(x) - sets x "seed" for random generator. seed always makes same sequence
:{{\|id|API|math|sin}}(degrees) - returns the sine of the degree value
:{{\|id|API|math|sinh}}(value) - returns the hyperbolic sine of value
:{{\|id|API|math|sqrt}}(x) - returns the square root of x
:{{\|id|API|math|tan}}(degrees) - returns the tangent of the degrees value
:{{\|id|API|math|tanh}}(x) - returns the hyperbolic tangent of x

=== Bitwise ===
WildStar includes the Lua BitLib library, which is available via "bit32." table, which provides access to C-style bitwise manipulation operators. This library uses the 32-bit integer size, e.g. bit32.lshift(2147483648, 1) = 0, because 1000 0000 0000 0000 0000 0000 0000 0000 -> 0000 0000 0000 0000 0000 0000 0000 0000.

==== {{\|id|API|bit32}} ====
:{{\|id|API|bit32|arshift}}(a, b) - returns a shifted arithmetically right b places
:{{\|id|API|bit32|band}}(w1, ...) - returns the bitwise ''and'' of the w's
:{{\|id|API|bit32|bnot}}(a) - returns the ''one's complement'' of a
:{{\|id|API|bit32|bor}}(w1, ...) - returns the bitwise ''or'' of the w's
:{{\|id|API|bit32|btest}}(···) returns (boolean) - true if ''bitwise and'' of all operands is not zero 
:{{\|id|API|bit32|bxor}}(w1, ...) - returns the bitwise ''exclusive or'' of the w's
:{{\|id|API|bit32|extract}}(n, start[, width]) - gets set of bits from n. start is 0-31. default width is 1
:{{\|id|API|bit32|lrotate}}(x, disp) - returns x rotated left disp places
:{{\|id|API|bit32|lshift}}(a, b) - returns a ''shifted left'' b places
:{{\|id|API|bit32|replace}}(n, v, start [, width]) - gets copy n with bits set from value v. start is 0-31. default width is 1
:{{\|id|API|bit32|rrotate}}(x, disp) - returns x rotated right disp places
:{{\|id|API|bit32|rshift}}(a, b) - returns a shifted logically right b places

=== System ===
The system functions whaich are generally just a subset of the Lua standard ''os'' library. Alternatively the {{../api||Apollo}} and {{../api|GameLib}} libraries offer standard WS UI date and time functions, like {{../api||GameLib|GetLocalTime}}, {{../api||GameLib|GetServerTime}} and {{../api||Apollo|GetTickCount}}.   

==== {{\|id|API|os}} ====
:{{\|id|API|clock}}() - returns an approximation in seconds of CPU time used by the program
:{{\|id|API|difftime}}(t2, t1) - returns diff in seconds between t1 and t2. in Windows and others is exactly t2-t1
:{{\|id|API|time}}([table]) returns (number) - current machine time, or from date table, in secs since 00:00 Jan 1 1970  
:{{\|id|API|date}}([format[, time]]) returns (table or string) - gets table or ''format'' string, of current or ''time'' date

=== Debugging ===
The debugging functions which are generally just a subset of the Lua stardard ''debug'' library.

==== {{\|id|API|debug}} ====
:{{\|id|API|debug|debug}}() enters an interactive mode with the user (not useable from UI)
:{{\|id|API|debug|gethook}}([thread]) - gets thread's hook settings: function, mask, count
:{{\|id|API|debug|getinfo}}([thread,] f [, what]) - gets table of information about a function ''f'' as: nups, what, func, lastlinedefined, source, currentline, namewhat, linedefined, short_src
:{{\|id|API|debug|getlocal}}([thread,] nLevel, nLocal) - gets name and value of the variable at ''nLocal'' in stack ''nLevel'' 
:{{\|id|API|debug|getmetatable}}(obj) returns (mtable) - gets metatable for table or userdata (same as _G.getmetatable)
:{{\|id|API|debug|getregistry}}() - returns the registry table (not useable from UI)
:{{\|id|API|debug|getupvalue}}(f, nUp) - gets name, value of upvalue nUp of function f. nil if no upvalue
:{{\|id|API|debug|sethook}}([thread,] f, sMask [, count]) - sets function f as to be called for event sMask
:{{\|id|API|debug|setlocal}}([thread,] nLevel, nLocal, value) - assigns value to nLocal at stack nLevel. gets name, or nil if no nLocal. throws if no nLevel
:{{\|id|API|debug|setmetatable}}(obj, mtable) returns (obj) - sets metatable for table or userdata (same as _G.setmetatable)
:{{\|id|API|debug|setupvalue}}(f, nUp, value) - assigns value to upvalue nUp of function f. gets name or nil if no upvalue
:{{\|id|API|debug|traceback}}([thread,] [sMessage [, nLevel]]) - gets string with a trace of call stack, starting at nLevel.

References added to ''debug.'' in WildStar
:{{\|id|API|debug|getfenv}}(any) returns (table) - stack frame of given function or stack level (same as _G.getfenv)
:{{\|id|API|debug|setfenv}}(function or nLevel, table) - sets table for stack frame for func or level (same as _G.setfenv)

=== Modules ===
The modules functions which are generally just a subset of the Lua stardard package library. Other than using the [[#require|require]] keyword to access standard Carbine WS modules, the {{\|api||Apollo}} library should be used instead for AddOns and Lua libraries, like {{\|api||Apollo|RegisterAddon}} and {{\|api||Apollo|RegisterPackage}}. 

:{{\|id|API|module}}(name [, ···]) - sets this Lua chunk as named Lua ''module'', in package.loaded[name] and _G[name]
:{{\|id|API|require}}(modname) - loads a module as reference in this Lua chunk, from package.loaded[name] or loader

==== {{\|id|API|package}} ====
:{{\|id|API|package|config}} [string] = "\\\n;\n?\n!\n-" - list of chunk string seperators (undocumented)
:{{\|id|API|package|cpath}} [string] = ".\?.dll;!\?.dll;!\loadall.dll" - require path for C loader
:{{\|id|API|package|loaded}} [table] - table used by require for modules are already loaded
:{{\|id|API|package|loaders}} [table] - table used by require for how to load modules
:{{\|id|API|package|loadlib}}(libname, sFunc) - loads and links a C Lua library
:{{\|id|API|package|path}} [string] = ".\?.lua;!\lua\?.lua;!\lua\?\init.lua;!\?.lua;!\?\init.lua" - require path for Lua loader
:{{\|id|API|package|preload}} [table] - table to store loaders for specific modules
:{{\|id|API|package|seeall}}(module) - sets metatable on module so inherits from global environment. option to [[#module|module]]()
</div><!-- do not remove -->

== See also ==
* [[Lua]] - which has plenty of links to other reference material
* [[\API types]] - with a list of Lua types and 'psudo-types' used in WS