org.classdump.luna.lib

Class BasicLib

java.lang.Object

org.classdump.luna.lib.BasicLib

public final class BasicLib
extends Object

The basic library provides 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.

Field Summary

Fields

Modifier and Type	Field and Description
static org.classdump.luna.ByteString	_VERSION The global variable _VERSION.
static org.classdump.luna.ByteString	MT_METATABLE The metatable key "__metatable".
static org.classdump.luna.ByteString	MT_NAME The metatable key "__name".
static org.classdump.luna.ByteString	MT_PAIRS The metatable key "__pairs".
static org.classdump.luna.ByteString	MT_TOSTRING The metatable key "__tostring".
static org.classdump.luna.ByteString	TYPENAME_LIGHT_USERDATA The name used for describing light userdata in error messages.

Method Summary

Modifier and Type	Method and Description
static org.classdump.luna.runtime.LuaFunction	assertFn() Returns the assert function.
static org.classdump.luna.runtime.LuaFunction	dofile(Object env, org.classdump.luna.load.ChunkLoader loader, FileSystem fileSystem) Returns a dofile function that uses the specified chunk loader loader and env as the default global environment for loaded chunks, and opens files in the specified fileSystem.
static org.classdump.luna.runtime.LuaFunction	error() Returns the error function.
static org.classdump.luna.runtime.LuaFunction	getmetatable() Returns the getmetatable function.
static void	installInto(org.classdump.luna.StateContext context, org.classdump.luna.Table env, RuntimeEnvironment runtimeEnvironment, org.classdump.luna.load.ChunkLoader loader) Installs the basic library into the specified table env in the state context context.
static org.classdump.luna.runtime.LuaFunction	ipairs() Returns the ipairs function.
static org.classdump.luna.runtime.LuaFunction	load(Object env, org.classdump.luna.load.ChunkLoader loader) Returns a load function that uses the specified chunk loader loader and env as the default global environment for loaded chunks.
static org.classdump.luna.runtime.LuaFunction	loadfile(Object env, org.classdump.luna.load.ChunkLoader loader, FileSystem fileSystem) Returns a loadfile function that uses the specified chunk loader loader and env as the default global environment for loaded chunks, and opens files in the specified fileSystem.
static org.classdump.luna.runtime.LuaFunction	next() Returns the next function.
static org.classdump.luna.runtime.LuaFunction	pairs() Returns the pairs function.
static org.classdump.luna.runtime.LuaFunction	pcall() Returns the pcall function.
static org.classdump.luna.runtime.LuaFunction	print(OutputStream out, Object env) Returns a print function that writes its output to the output stream out and looks up the tostring function in the supplied environment env.
static org.classdump.luna.runtime.LuaFunction	rawequal() Returns the rawequal function.
static org.classdump.luna.runtime.LuaFunction	rawget() Returns the rawget function.
static org.classdump.luna.runtime.LuaFunction	rawlen() Returns the rawlen function.
static org.classdump.luna.runtime.LuaFunction	rawset() Returns the rawset function.
static org.classdump.luna.runtime.LuaFunction	select() Returns the select function.
static org.classdump.luna.runtime.LuaFunction	setmetatable() Returns the setmetatable function.
static org.classdump.luna.runtime.LuaFunction	tonumber() Returns the tonumber function.
static org.classdump.luna.runtime.LuaFunction	tostring() Returns the tostring function.
static org.classdump.luna.runtime.LuaFunction	type() Returns the type function.
static org.classdump.luna.runtime.LuaFunction	xpcall() Returns the xpcall function.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MT_METATABLE

public static final org.classdump.luna.ByteString MT_METATABLE

The metatable key "__metatable". When defined, customises the behaviour of getmetatable and setmetatable.

MT_NAME

public static final org.classdump.luna.ByteString MT_NAME

The metatable key "__name". Used to customise the type name of an object in error messages.

See Also:

NameMetamethodValueTypeNamer

MT_PAIRS

public static final org.classdump.luna.ByteString MT_PAIRS

The metatable key "__pairs". When defined, customises the behaviour of pairs.

MT_TOSTRING

public static final org.classdump.luna.ByteString MT_TOSTRING

The metatable key "__tostring". When defined, customises the behaviour of tostring.

TYPENAME_LIGHT_USERDATA

public static final org.classdump.luna.ByteString TYPENAME_LIGHT_USERDATA

The name used for describing light userdata in error messages.

See Also:

NameMetamethodValueTypeNamer

_VERSION

public static final org.classdump.luna.ByteString _VERSION

The global variable _VERSION.

The following is the corresponding entry from the Lua Reference Manual:

_VERSION

A global variable (not a function) that holds a string containing the running Lua version. The current value of this variable (in PUC-Lua 5.3.x) is "Lua 5.3".

See Also:

the Lua 5.3 Reference Manual entry for _VERSION

Method Detail

assertFn

public static org.classdump.luna.runtime.LuaFunction assertFn()

Returns the assert function.

The following is the corresponding entry from the Lua Reference Manual:

assert (v [, message])

Calls error if the value of its argument v is false (i.e., nil or false); otherwise, returns all its arguments. In case of error, message is the error object; when absent, it defaults to "assertion failed!"

Returns:

the assert function

See Also:

the Lua 5.3 Reference Manual entry for assert

dofile

public static org.classdump.luna.runtime.LuaFunction dofile(Object env,
                                                            org.classdump.luna.load.ChunkLoader loader,
                                                            FileSystem fileSystem)

Returns a dofile function that uses the specified chunk loader loader and env as the default global environment for loaded chunks, and opens files in the specified fileSystem.

Note: the loadfile function returned by this method does not support loading from standard input.

The following is the corresponding entry from the Lua Reference Manual:

dofile ([filename])

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).

Parameters:

env - the default global environment for loaded chunks, may be null

loader - the chunk loader to use, must not be null

fileSystem - the file system to use, must not be null

Returns:

the dofile function

Throws:

NullPointerException - if fileSystem or loader is null

See Also:

the Lua 5.3 Reference Manual entry for dofile

error

public static org.classdump.luna.runtime.LuaFunction error()

Returns the error function.

The following is the corresponding entry from the Lua Reference Manual:

error (message [, level])

Terminates the last protected function called and returns message as the error object. Function error never returns.

Usually, error adds some information about the error position at the beginning of the message, if the message is a string. 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.

Returns:

the error function

See Also:

the Lua 5.3 Reference Manual entry for error

getmetatable

public static org.classdump.luna.runtime.LuaFunction getmetatable()

Returns the getmetatable function.

The following is the corresponding entry from the Lua Reference Manual:

getmetatable (object)

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.

Returns:

the getmetatable function

See Also:

the Lua 5.3 Reference Manual entry for getmetatable

ipairs

public static org.classdump.luna.runtime.LuaFunction ipairs()

Returns the ipairs function.

The following is the corresponding entry from the Lua Reference Manual:

ipairs (t)

Returns three values (an iterator function, the table t, and 0) so that the construction

for i,v in ipairs(t) do body end

will iterate over the key–value pairs (1,t[1]), (2,t[2]), ..., up to the first nil value.

Returns:

the ipairs function

See Also:

the Lua 5.3 Reference Manual entry for ipairs

load

public static org.classdump.luna.runtime.LuaFunction load(Object env,
                                                          org.classdump.luna.load.ChunkLoader loader)

Returns a load function that uses the specified chunk loader loader and env as the default global environment for loaded chunks.

The following is the corresponding entry from the Lua Reference Manual:

load (chunk [, chunkname [, mode [, env]]])

Loads a chunk.

If chunk is a string, the chunk is this string. If chunk is a function, load calls it repeatedly to get the chunk pieces. Each call to chunk must return a string that concatenates with previous results. A return of an empty string, nil, or no value signals the end of the chunk.

If there are no syntactic errors, returns the compiled chunk as a function; otherwise, returns nil plus the error message.

If the resulting function has upvalues, the first upvalue is set to the value of env, if that parameter is given, or to the value of the global environment. Other upvalues are initialized with nil. (When you load a main chunk, the resulting function will always have exactly one upvalue, the _ENV variable (see §2.2 of the Lua Reference Manual). However, when you load a binary chunk created from a function (see string.dump), the resulting function can have an arbitrary number of upvalues.) All upvalues are fresh, that is, they are not shared with any other function.

chunkname is used as the name of the chunk for error messages and debug information (see §4.9 of the Lua Reference Manual). When absent, it defaults to chunk, if chunk is a string, or to "=(load)" otherwise.

The string mode controls whether the chunk can be text or binary (that is, a precompiled chunk). It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text). The default is "bt".

Lua does not check the consistency of binary chunks. Maliciously crafted binary chunks can crash the interpreter.

Parameters:

env - the default global environment for loaded chunks, may be null

loader - the chunk loader to use, must not be null

Returns:

the load function

Throws:

NullPointerException - if loader is null

See Also:

the Lua 5.3 Reference Manual entry for load

loadfile

public static org.classdump.luna.runtime.LuaFunction loadfile(Object env,
                                                              org.classdump.luna.load.ChunkLoader loader,
                                                              FileSystem fileSystem)

Returns a loadfile function that uses the specified chunk loader loader and env as the default global environment for loaded chunks, and opens files in the specified fileSystem.

Note: the loadfile function returned by this method does not support loading from standard input.

The following is the corresponding entry from the Lua Reference Manual:

loadfile ([filename [, mode [, env]]])

Similar to load, but gets the chunk from file filename or from the standard input, if no file name is given.

Parameters:

env - the default global environment for loaded chunks, may be null

loader - the chunk loader to use, must not be null

fileSystem - the file system to use, must not be null

Returns:

the loadfile function

Throws:

NullPointerException - if fileSystem or loader is null

See Also:

the Lua 5.3 Reference Manual entry for loadfile

next

public static org.classdump.luna.runtime.LuaFunction next()

Returns the next function.

The following is the corresponding entry from the Lua Reference Manual:

next (table [, index])

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 numerical order, use a numerical for.)

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.

Returns:

the next function

See Also:

the Lua 5.3 Reference Manual entry for next

pairs

public static org.classdump.luna.runtime.LuaFunction pairs()

Returns the pairs function.

The following is the corresponding entry from the Lua Reference Manual:

pairs (t)

If t has a metamethod "__pairs", calls it with t as argument and returns the first three results from the call.

Otherwise, returns three values: the next function, the table t, and nil, so that the construction

for k,v in pairs(t) do body end

will iterate over all key–value pairs of table t.

See function next for the caveats of modifying the table during its traversal.

Returns:

the pairs function

See Also:

the Lua 5.3 Reference Manual entry for pairs

pcall

public static org.classdump.luna.runtime.LuaFunction pcall()

Returns the pcall function.

The following is the corresponding entry from the Lua Reference Manual:

pcall (f [, arg1, ···])

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.

Returns:

the pcall function

See Also:

the Lua 5.3 Reference Manual entry for pcall

print

public static org.classdump.luna.runtime.LuaFunction print(OutputStream out,
                                                           Object env)

Returns a print function that writes its output to the output stream out and looks up the tostring function in the supplied environment env.

Note: the function returned by this method looks up tostring by evaluating the Lua expression env["tostring"] every time it is invoked. It does not call tostring() directly. This is the (undocumented) behaviour of the print function provided by PUC-Lua 5.3.3.

The following is the corresponding entry from the Lua Reference Manual:

print (···)

Receives any number of arguments and prints their values to stdout, using the tostring function to convert each argument to a string. print is not intended for formatted output, but only as a quick way to show a value, for instance for debugging. For complete control over the output, use string.format and io.write.

Parameters:

out - the output stream, must not be null

env - the environment for looking up the global function tostring, may be null

Returns:

the print function

Throws:

NullPointerException - if out is null

See Also:

the Lua 5.3 Reference Manual entry for print

rawequal

public static org.classdump.luna.runtime.LuaFunction rawequal()

Returns the rawequal function.

The following is the corresponding entry from the Lua Reference Manual:

rawequal (v1, v2)

Checks whether v1 is equal to v2, without invoking any metamethod. Returns a boolean.

Returns:

the rawequal function

See Also:

the Lua 5.3 Reference Manual entry for rawequal

rawget

public static org.classdump.luna.runtime.LuaFunction rawget()

Returns the rawget function.

The following is the corresponding entry from the Lua Reference Manual:

rawget (table, index)

Gets the real value of table[index], without invoking any metamethod. table must be a table; index may be any value.

Returns:

the rawget function

See Also:

the Lua 5.3 Reference Manual entry for rawget

rawlen

public static org.classdump.luna.runtime.LuaFunction rawlen()

Returns the rawlen function.

The following is the corresponding entry from the Lua Reference Manual:

rawlen (v)

Returns the length of the object v, which must be a table or a string, without invoking any metamethod. Returns an integer.

Returns:

the rawlen function

See Also:

the Lua 5.3 Reference Manual entry for rawlen

rawset

public static org.classdump.luna.runtime.LuaFunction rawset()

Returns the rawset function.

The following is the corresponding entry from the Lua Reference Manual:

rawset (table, index, value)

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 NaN, and value any Lua value.

This function returns table.

Returns:

the rawset function

See Also:

the Lua 5.3 Reference Manual entry for rawset

select

public static org.classdump.luna.runtime.LuaFunction select()

Returns the select function.

The following is the corresponding entry from the Lua Reference Manual:

select (index, ···)

If index is a number, returns all arguments after argument number index; a negative number indexes from the end (-1 is the last argument). Otherwise, index must be the string "#", and select returns the total number of extra arguments it received.

Returns:

the select function

See Also:

the Lua 5.3 Reference Manual entry for select

setmetatable

public static org.classdump.luna.runtime.LuaFunction setmetatable()

Returns the setmetatable function.

The following is the corresponding entry from the Lua Reference Manual:

setmetatable (table, metatable)

Sets the metatable for the given table. (To change the metatable of other types from Lua code, you must use the debug library (see §6.10 of the Lua Reference Manual).) 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.

Returns:

the setmetatable function

See Also:

the Lua 5.3 Reference Manual entry for setmetatable

tonumber

public static org.classdump.luna.runtime.LuaFunction tonumber()

Returns the tonumber function.

The following is the corresponding entry from the Lua Reference Manual:

tonumber (e [, base])

When called with no base, tonumber tries to convert its argument to a number. If the argument is already a number or a string convertible to a number (see §3.4.2 of the Lua Reference Manual), then tonumber returns this number; otherwise, it returns nil.

When called with base, then e should be a string to be interpreted as an integer numeral in that base. 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. If the string e is not a valid numeral in the given base, the function returns nil.

Returns:

the tonumber function

See Also:

the Lua 5.3 Reference Manual entry for tonumber

tostring

public static org.classdump.luna.runtime.LuaFunction tostring()

Returns the tostring function.

The following is the corresponding entry from the Lua Reference Manual:

tostring (v)

Receives a value of any type and converts it to a string in a human-readable format. (For complete control of how numbers are converted, use string.format.) If the metatable of v has a "__tostring" field, then tostring calls the corresponding value with v as argument, and uses the result of the call as its result.

Returns:

the tostring function

See Also:

the Lua 5.3 Reference Manual entry for tostring

type

public static org.classdump.luna.runtime.LuaFunction type()

Returns the type function.

The following is the corresponding entry from the Lua Reference Manual:

type (v)

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".

Returns:

the type function

See Also:

the Lua 5.3 Reference Manual entry for type

xpcall

public static org.classdump.luna.runtime.LuaFunction xpcall()

Returns the xpcall function.

The following is the corresponding entry from the Lua Reference Manual:

xpcall (f, msgh [, arg1, ···])

This function is similar to pcall, except that it sets a new message handler msgh.

Returns:

the xpcall function

See Also:

the Lua 5.3 Reference Manual entry for xpcall

installInto

public static void installInto(org.classdump.luna.StateContext context,
                               org.classdump.luna.Table env,
                               RuntimeEnvironment runtimeEnvironment,
                               org.classdump.luna.load.ChunkLoader loader)

Installs the basic library into the specified table env in the state context context. Uses runtimeEnvironment for I/O facilities and loader for chunk loading.

The following functions are only installed if the conditions are satisfied:

• dofile: if runtimeEnvironment != null && runtimeEnvironment.fileSystem() != null && loader != null;
• load: if loader != null;
• loadfile: if runtimeEnvironment != null && runtimeEnvironment.fileSystem() != null && loader != null;
• print: if runtimeEnvironment != null && runtimeEnvironment.standardOutput() != null;

If env.package.loaded is a table, adds env to it with the key "_G", using raw access.

Parameters:

context - the state context, must not be null

env - the global environment, must not be null

runtimeEnvironment - the runtime environment to use, may be null

loader - the chunk loader to use, may be null

Throws:

NullPointerException - if context or env is null