User Tools

Site Tools


lgscript:standard_library

Standard Library

Functions in the standard library are defined in the global scope.

assert

Tests a value, and if it is false then an error is reported. If there is no error, the function parameters are returned.

Returns any ... Returns all the parameters only if there is no error.
Parameter any Raise an error if the value is false or nil.
Parameter ... Parameters are passed through if there is no error.

When an error occurs, an extra parameter is extracted. If the parameter is a string, it is used to describe the error that occurred.

Many functions return normal values when they complete successfully. When the function isn’t successful, it will return a nil value and a description of the error. Returning values this way matches with the parameters to the assert function. You can wrap those function with a call to assert before assigning the return values. Since this function will only return if there is no error, then you don’t need to handle the error yourself.

On the other hand, you have the option of handling the error yourself when interrupting the script isn’t desired. Then you use a simple if-then-else block to check if the original function returned nil or a valid value.

collectgarbage

Manually control the memory manager.

collectgarbage("stop") Stops the garbage collector.
collectgarbage("restart") Restart the garbage collector.
collectgarbage("collect") Force all unused memory to be freed.
value=collectgarbage("count") Get the amount of used memory in Kbytes.
result=collectgarbage("step",size) Free some unused memory. Larger sizes increase the number of steps, and thus the amount of memory freed. When there is no more unused memory, returns true.
value=collectgarbage("setpause",value) Change the “pause” parameter of the garbage collector. A larger pause allows more unused memory to collect before it is freed. Values lower than 100 may make the garbage collector run too often and slow down the script. Returns the previous pause value.
value=collectgarbage("setstepmul",value) Change the “step” parameter of the garbage collector. A larger step multiplier increases the amount of memory that is freed each time the collector runs. Values lower than 100 may cause some memory to never be freed. Returns the previous step multiplier.

dofile

Load and run another Lua script.

Returns any ... Returns values if the script has a return statement.
Parameter string (opt.) The name of the file to load. If not specified, the script is read from standard input.

Errors in the script are reported as errors in the calling environment.

This function is a shortcut for assert(loadfile(name))().

error

Report an error. This function will not return.

Parameter string Description of the error.
Parameter number (opt.) Function level where the error occurred. Default is 1.

The name of the function that caused the error is reported with the error description. The first level is the function that called error. Level 2 is the function that called the function that called error, and so on. A level of 0 will omit reporting the function name.

getfenv

Access the current function environment.

Returns table The environment table.
Parameter number or function (opt.) Function level, or a function object. Default is 1.

Using a function level of 0 will get the global environment table, which may not necessarily be _G.

getmetatable

Access an object’s metatable.

Returns table or nil The metatable of the object.
Parameter object The object or type to get the metatable from.

The string type has a metatable, even though it is not an object. All strings share the same metatable.

ipairs

Creates an iterator for the integer indexes of a table.

Returns function,table,0 An iterator, the original table, and an initializer.
Parameter table A table to get the values of.

The ipairs iterator reads the integer indexes of the table. When used in a for loop, the values returned will be the integer index starting at 1, and that value from the table. The iterator returns consecutive indexes until it reads a nil value. If there are holes in the table, then not all values will be read.

load

Read a lua script and return the script as a function.

Returns function A function that will run the script.
Returns nil, string If the script cannot be loaded, returns nil and an error message.
Parameter function A function that reads the script.
Parameter string (opt.) The name of the script to use when reporting errors.

The reader function returns the script source to be loaded. The source can be in text or compiled binary form. Not all of the script needs to be read at once. The loader will repeatedly call the reader function until either an error occurs, or the reader returns nil or an empty string. No parameters are passed to the reader function.

loadfile

Load a Lua script from a file.

Returns function A function that will run the script.
Returns nil, string If the script cannot be loaded, returns nil and an error message.
Parameter string (opt.) The name of the file to load. If not specified, the script is read from standard input.

loadstring

Load a Lua script from a string.

Returns function A function that will run the script.
Returns nil, string If the script cannot be loaded, returns nil and an error message.
Parameter string The script to load.
Parameter string (opt.) The name of the script to use when reporting errors.

The string to load can be the text source code of the script, or compiled binary bytecodes.

module

Setup a new module.

Parameter string The name of the module.
Parameter function ... (opt.) Functions that will modify the module.

A module is a table that contains all the values, mostly functions, to implement a feature. The module can then be accessed using the require function. By putting all the functions of a module in its own table, each module is isolated from any other functions or modules that the script loads or creates.

Modules can be nested by using a dotted name. The dotted name is the names of all intermediate modules with a dot seperating each name. The final name is the module, and all previous names describe the package. When creating a nested module, the table for each intermediate module will be created if it doesn’t exist. So module A.B.C is the module C in the package A.B. The table for C is stored in the table for B which is stored in the global table A.

An existing module table will be reused if it either exists in package.loaded[name], or the global variable with that name is a table. Otherwise, a new table is created. The new table will be saved in package.loaded[name] and as a global variable.

The module table is initialized with these values.

_NAME The name of the module.
_M The module table.
_PACKAGE The package name.

The module table will become the new environment for the current function. If you wish to use global variables in the module, then you must take steps to make those variables accessable. This can be done either by creating local variables with the values of the global variables before you call the module function. Another way is to use the __index metamethod to make the _G table visible in the module table.

Extra parameters to module are functions to be called after the module table is created. Each function is called with the table as a parameter. One example of a function that is useful for this is package.seeall.

newproxy

Create a zero-length proxy object.

Returns userdata A proxy object.
Parameter boolean or userdata (opt.) Whether to add a metatable to the object. Default is false.

A proxy object is a unique value that may have a metatable, but is not otherwise modifiable. There is no data associated with a proxy, so it is smaller than a table. Because a proxy is userdata, it can have a __gc metamethod, which a table cannot.

If the parameter is false or nil, then the proxy is created without a metatable. The only purpose of the object is to be a value different from any other value. If the parameter is true, the proxy is created with an empty metatable.

You can pass an existing proxy to copy the metatable.

next

Get an index and value from a table based on a known index.

Returns any, any The index and value of the next table entry.
Returns nil There are no more table entries after the given index.
Parameter table The table to read entries from.
Parameter any (opt.) A known index in the table. Default is nil.

When called with a nil index, the first index and value in the table will be returned. Using an index that doesn’t exist in the table is an error.

Table entries are not returned in a particular order. However, as long as the table is not modified, then next will continue to return the same entry for a particular index. If the table is changed, or for any other table (even with the same values) the order of entries is not predictable.

pairs

Creates an iterator for a table.

Returns function,table,nil An iterator, the original table, and an initializer.
Parameter table A table to get the values of.

The pairs iterator reads all indexes of the table. When used in a for loop, each pair of index and value in the table will be read. The indexes are not read in any particular order. The iterator uses the same method to find an index as next.

pcall

Call a function in protected mode.

Returns true, any ... The return values from the function when there is no error.
Return false, string An error message.
Parameter function The function to call.
Parameter ... (opt.) Parameters for the function.

Calling a function in protected mode will catch any errors that occur. The error is not reported but is instead returned to the caller. The return from pcall indicates whether the call was successful and either the return values from the function, or an error message.

print

Display values on the standard output.

Parameter ... (opt.) Values to print.

The given values are converted to strings then displayed on the standard output. The strings are seperated with a tab character. After the values have been displayed, a new-line is output.

A simple string conversion is used that will not always show meaningful information for object types. A table, in particular, only prints that it is a table and not what the values are.

rawequal

Compare two values without using metamethods.

Returns boolean Whether the values are equal.
Parameter any A value to compare.
Parameter any Another value to compare.

Object types can customize the == operator using metamethods. This function compares two values using the standard method.

rawget

Get a value in a table without using metamethods.

Returns any The value of the table entry, or nil.
Parameter table The table to read the value from.
Parameter any The index to read. Cannot be nil.

Tables can customize the subscript operator using metamethods. This function gets a value from the table directly.

rawset

Set a value in a table without using metamethods.

Returns table The table being written to.
Parameter table A table to write the value to.
Parameter any The index to write. Cannot be nil.
Parameter any The value to set the index to.

Tables can customize the subscript operator using metamethods. This function will store a value in the table directly. If the value is nil then the entry is deleted.

require

Load a module.

Returns table The module table.
Parameter string The module name.

Require will get the table of an already loaded module, or will attempt to load a new module. If there is a value in package.loaded[name] then the module is already loaded and that value is returned. Otherwise, the functions in package.loaders are each tried until the module can be loaded, or there are no more loaders. An error is reported if the module cannot be loaded.

If loading a module results in a value, because the module script used a return statement, then that value is stored in package.loaded[name]. If the module does not return a value, it may have already set a value in package.loaded[name], so that value is preserved. On the other hand if there is no value, then it will be set to true, and this is what the call to require will return.

In short, typing require “something” is how you load a module. Or you may have to type something = require “something”. The description of the module should tell you which to use. If it doesn’t, then assume the former.

select

Returns some of the parameters passed to it.

Returns any ... Zero or more parameters passed to the function.
Returns number The number of parameters passed to the function.
Parameter number or "#" What to return.
Parameter ... Extra parameters.

When called with an integer, returns the rest of the parameter list starting with the index given. The first parameter after the index is index 1. So passing 1 will return all of the extra parameters; using 2 will return all except for the first parameter, and so on.

If the index is negative, select will return that many values starting at the end of the parameter list.

When you use the parameter "#", returns the number of extra parameters passed to the function.

seq

Generate a sequence of numbers.

Returns number ... A sequence of numbers or integers.
Parameter number (opt.) The first number in the sequence. Default is 1.
Parameter number The last number in the sequence.
Parameter number (opt.) Amount to increment each number in the sequence.

The first return value will be the start of the sequence and each subsequent value will be incremented by the step value. The last value in the sequence will be less than or equal to the final number. If the step value is negative, the last value will be greater than or equal to the final number.

If the first number is greater than the last number, or with a negative step value, the first number is less than the last number, then no values are returned.

setfenv

Change the current function environment.

Returns function The current function.
Parameter number or function Function level, or a function object.
Parameter table The environment table.

Using a function level of 0 will set the global environment table. This does not change the value of _G.

setmetatable

Assign a metatable to a table.

Returns table The table object.
Parameter table The object to set a metatable for.
Paramete table or nil The new metatable.

If the field __metatable is set in the original metatable, then the metatable may not be changed.

shift

Returns some of the parameters passed to it.

Returns any ... Zero or more parameters passed to the function.
Returns number The number of parameters passed to the function.
Parameter number or "#" What to return.
Parameter ... Extra parameters.

When called with an integer, returns that many values from the start of the parameter list. If the index is negative, it will return up to and including that number parameter counting from the end of the list.

When you use the parameter "#", the number of extra parameters passed to the function.

tonumber

Convert a value to a real number.

Returns number or nil The result of the conversion.
Parameter any The value to convert.

Values that cannot convert to a real number will return nil. A string will be converted if it is a decimal or hexadecimal number.

tostring

Convert a value to a string.

Returns string A string representation of the value.
Parameter any The value to convert.

Values that do not have a meaningful string representation will be converted to the name of their type and an internal ID.

type

Get the type of a value.

Returns string Name of the type.
Parameter any A value.

unpack

Get the values in a table.

Returns any ... The values from the table.
Parameter table A table to unpack.
Parameter integer (opt.) The first index to unpack.
Parameter integer (opt.) The last index to unpack.

The values from the table with consecutive integer indexes will be returned. This function is also in the table library, for compatibility with Lua 5.2.

vector

Create a three-element vector.

Returns userdata A vector.
Parameter number (opt.) The X element value.
Parameter number (opt.) The Y element value.
Parameter number (opt.) The Z element value.

A vector is made up of three real numbers. The elements of a vector can be accessed using the indexes x, y, and z. You can also use r, g, and b, or 0, 1, and 2.

Two vectors can be added or subtracted. A vector can be reversed with the minus sign. You can scale a vector by multiplying it with a number. Vectors can be compared using == and ~=.

These methods can be used with a vector.

v:mag() The magnitude of the vector.
v:norm() A normalized vector.
v:dot(vector) The dot product of this vector and another.
v:cross(vector) The cross product of this vector and another.

xpcall

Call a function in protected mode with an error handler.

Returns true, any ... The return values from the function when there is no error.
Return false, string An error message.
Parameter function The function to call.
Parameter function An error handler.

Calling a function in protected mode will catch any errors that occur. The error is not reported but is instead passed to an error handler function. The result of the error handler is the error message returned by xpcall. See pcall for details about protected mode.

lgscript/standard_library.txt · Last modified: 2011/05/18 23:25 by telliamed