annotations.txt

# lauxlib.h:
This is the public interface of the "Auxiliary Library".

# lauxlib.h:luaL_newlib
int luaL_newlib (lua_State *L, const luaL_Reg *l);
[-0, +1, m]

# lauxlib.h:luaL_argcheck
void luaL_argcheck (lua_State *L, int cond, int narg, const char *extramsg);
[-0, +0, v]

# lcode.h:getcode
FuncState*, expdesc* -> int

# llimits.h:MAXSTACK
Note: must fix in byte (lu_byte)--see Proto::maxstacksize.

# lua.h:
This is the public interface to the core Lua library.

# lua.h:LUA_VERSION_NUM
This is the number exposed by lua_version().
Note: 502 mean "5.2".  501 means "5.1"

# lua.h:LUA_SIGNATURE
Lua bytecode always starts with a signature consisting
of these bytes.  Both Lua 5.1 and 5.2 start with this
signature.  Some functions like load() determine whether
a file is Lua source code or Lua byte code by looking
for this signature.  The \033 (escape) character is not
a valid first character in Lua source code.

# lua.h:LUA_ERRERR
Note: see also LUA_ERRFILE in lauxlib.h.

# lua.h:LUA_NUMTAGS
This must always be set to one more than the
maximum LUA_T* value above.

# lua.h:LUA_MINSTACK
From the reference manual:
Whenever Lua calls C, it ensures that at least
LUA_MINSTACK stack positions are available.
LUA_MINSTACK is defined as 20, so that usually
you do not have to worry about stack space
unless your code has loops pushing elements
onto the stack.

# lua.h:LUA_RIDX_MAINTHREAD
From the reference manual: At this index the
registry has the main thread of the state.
(The main thread is the one created together
with the state.)

# lua.h:LUA_RIDX_GLOBALS
From the reference manual: At this index the
registry has the global environment. This is the
C equivalent to the _G global variable.

# lua.h:LUA_RIDX_LAST
This must always be set to the maximum LUA_RIDX
value above.

# lua.h:lua_Number
Typically set to double on PCs.

# lua.h:lua_Integer
Typically set to int (32-bit) on PCs.

# lua.h:lua_Unsigned
Typically set to unsigned int on PCs.

# luac.c:
This is the Lua compiler front-end (luac).

Note: Comments based on Lua 5.2.0-alpha.

# luac.c:fatal
Utility function to display fatal error message
and exit (without cleanup).

# luac.c:cannot
Utility function display fatal I/O error
and exit (without cleanup).

# luac.c:usage
Writes command-line help to standard error
and exit (without cleanup)

# luac.c:doargs
Parse main's command line arguments.
May exit without cleanup.

# luac.c:FUNCTION
used by luac.c:reader

# luac.c:reader
lua_Reader function that outputs Lua source code consisting of
a series of "(function()end)();" repeated by the number of times
in integer *ud.

This is used to generate the initial bytecode needed by
luac when compiling multiple files (chunks) together.  This bytecode
is later patched with the addresses of the real chunks.

# luac.c:combine
On exit, the top of the stack will contain a function that calls
the previous top-most n values (functions) on the stack.

This is used to generate the initial bytecode needed by
luac when compiling multiple files (chunks) together.

# luac.c:writer
lua_Writer function used to dump generated bytecode to a file.

# luac.c:pmain
Main code, protected by pcall.

# luac.c:main
Main code, entry point.

# luac.c:PrintString
Dump string object (quoted and escaped) to standard output.

# luac.c:PrintConstant
Dump i-th constant in function prototype f.

# luac.c:PrintCode
Dump all opcodes in function prototype f.

# luac.c:PrintHeader
Dump metadata on function prototype f.

# luac.c:PrintDebug
Dump all constants/locals/upvalues in function prototype f.

Used by undocumented "luac -l -l".

# luac.c:PrintFunction
Dump function prototype f.
If full (0 or 1) is 1, invokes PrintDebug.

# lparser.c:hasmultret
Whether expkind k has multiple return values.

# lparser.c:NILCONSTANT
Use for structure initializer of TValue object representing nil.

# lparser.c:ttype
Returns a LUA_T* value.

# lobject.h:
This files provides the types an operations on for handling
values (TValue objects) in Lua.

# lobject.h:ttisnil
Checks whether TValue o is nil.

# lobject.h:ttisnumber
Checks whether TValue o is of type number.

# lobject.h:ttislcf
Checks whether TValue o is a Lua function (or C function exposed
to Lua, not including light C functions).  Such functions have
a prototype (see getproto)

# lobject.h:ttislcf
Checks whether TValue o is a light C function (lua_CFunction).

# lobject.h:pvalue
Gets void pointer in TValue o.

# lobject.h:nvalue
Gets number (lua_Number) in TValue o (or asserts if not number).

# lobject.h:rawtsvalue
Gets string (TString) in TValue o.

# lobject.h:tsvalue
Gets string header (TString.tsv) in TValue o.

# lobject.h:uvalue
Gets userdata header (Udata.uv) in TValue o.

# lobject.h:clvalue
Gets closure (Closure - GCObject.cl) in TValue o.

# lobject.h:fvalue
Gets light C function (lua_CFunction) in TValue o.

# lobject.h:hvalue
Gets table (Table - GCobject.h) in TValue o.

# lobject.h:bvalue
Gets boolean (int) value in TValue o.

# lobject.h:thvalue
Gets thread lua_State (GCObject.th) value in Tvalue o.

# lobject.h:l_isfalse
Gets whether TValue o evaluates to false (i.e. is nil or false).

# lobject.h:setnvalue
Sets value of TValue obj to number (lua_Number) x.

# lobject.h:setfvalue
Sets value of TValue obj to light C function (lua_CFunction) x.

# lobject.h:setfvalue
Sets value of TValue obj to light user data (void*) x.

# lobject.h:setbvalue
Sets value of TValue obj to boolean (int 0..1) x.

# lobject.h:svalue
Note: TValue o -> const char *.

# lobject.h:Udata
Note: each (heavyweight) userdata can be associated with a metatable
and a user value (previously called a "userdata environment table") set
via lua_setuservalue.
A userdata is garbage collectable CommonHeader) and is allocated
as a series of `len` bytes in Lua's own memory.

# lobject.h:Upvaldesc
Note: compare to Upval.

# lobject.h:Proto
Every definition of a Lua function (or C function exposed as a Lua function)
is represented with a function prototype object.
This contains things like a list of bytecode instructions (code),
links to other constant data used by the functions
(constants, nested functions, and upvalue descriptions), and other
metadata (e.g. debugging info).

For each function prototype, any number of values may be
instantiated (allocated) based on that prototype.  For example, this:

  local t = {}
  for i=1,10 do
    t[i] = function() return i end
  end
	
creates 10 function objects that all link to the same prototype of
"function() return i end".

# lobject.h:Upvaluedesc.
Compare to UpVal, which are stored in closures (instantiations of
prototypes).

# lobject.h:UpVal
This represents upvalues.  They are stored in a closure value (LClosure).
Compare to Upvaldesc.

# lobject.h:Closure
Represents a closure (implemented via C Function or Lua function).
These are linked to TValue's, among other places.

# lobject.h:getproto
Gets the prototype (Prototype) of TValue o (assumed to be a
function, not a lightweight C function).

# lobject.h:Table
Represents a Lua table ({}).
These are linked to TValues.

Note: each table can have an optional metatable and can have
an array part (stored in array `array` of length `sizearray` and
a hash part (stored in array `node` of length encoded in `lsizenode`).

You can quickly check for certain metamethods via the `flags` field
rather than looking in the metatable.

# lobject.h:twoto
Efficiently raises 2 to the integer x power.

# lopcodes.h:getarg
Gets size bits starting at offset pos in Instruction i.
Example: getarg(0x12345678,4,8) == 0x67

# lopcodes.h:setarg
Sets (in-place) size bits starting at offset pos in Instruction i to v.
Example: Instruction i = 0x12345678; setarg(i,0x76,4,8); assert(i == 0x12345768);

# lopcodes.h:GETARG_A
Gets integer A fields bits of Instruction i.

# lopcodes.h:SETARG_A
Sets (in-place) A field bits of Instruction i to integer v.

# lopcodes.h:CREATE_ABC
Returns Instruction formed from opcode (OpCode) o and given integer A, B, C fields.

# lcode:isnumeral
Determines whether expression represents a number that is a known constant.
Note: constant numbers can be used in expression folding (compile time evaluation).
Careful on jumps (true (t) and false (f) patch lists).

# lcode.c:luaK_ret
Encode opcode for "return" (OP_RETURN).
Note: (first,nret)=(0,0) means return no values.  nret == LUA_MULTRET means return all
values starting at first (useful for vararg expressions).

# lcode.c:luaK_checkstack
Updates function state's maximum needed stack size (maxstacksize) given that
n additional registers will be needed.  Raises syntax error if above limit (MAXSTACK).

# lcode.c:luaK_reserveregs
Like luaK_checkstack but also reserves those n additional registers.

# lcode.c:freereg
This complements luaK_reserveregs.  It frees the top-most reserved register.
But it only does this if reg is actually a register (not an index in the constant table)
and it's not used for storage of a local variable (the lowest nactvar values on the stack).

# lcode.c:addk
Adds a constant with name `key` and value v to the function state's constant table
(i.e. array k of size sizek where first nk values are used).
Duplicates are detected and avoided via the helper table 'h', which maps each existing
value in the constant table to an integer index in the constant table.  The constant
table allocated size may need to be grown (and new empty space filled
with nil's) prior to inserting the constant.  (TODO-comment on luaC_barrier?)
Returns 0-based index of the new constant in the constant table.

# lcode.c:luaK_stringK
Adds a string to the constant table (addk).
Note: stores in TValue first.

# lcode.c:luaK_numberK
Adds a number to the constant table (addk).
(TODO: comment on "numeric problems")

# lcode.c:boolK
Adds a boolean (0 or 1) to the constant table (addk).

# lcode.c:nilK
Adds a nil to the constant table (addk).
Note: the helper table 'h' (see addk) normally maps constant values to indicies in the
constant table, but the constant value is nil here, which Lua tables don't allow.
So, following a design pattern in <http://lua-users.org/wiki/StoringNilsInTables>,
we use another unique value instead as its placeholder, which here is
convenient to use the h table itself, which is never used outside of the compiler
internal and therefore has no chance of misinterpretation.
h is a Table, which we wrap in a TValue before doing addk.

# lcode.c:constfolding
Attempts to constant fold (i.e. evaluate at compile time as an optimization) the given
operation on the two expressions.
Folding is attempted only on operations on numbers that are known constants
(e.g. `local x = 1+1` -> `local x = 2`).  Moreover, constant folding is skipped on
division (or modulo) by zero (resulting in not-a-number, NaN), which Lua 5.1 folded
but it caused problems so this folding was eliminated in Lua 5.2.
Returns 1 (not 0) if folding was possible.
--see <http://lua-users.org/lists/lua-l/2007-02/msg00207.html>.

# ltable.h:gnode
Table*, int -> Node*
Gets i-th node in table's hashpart array.
(Question: why isn't there a corresponding function
to get the i-th node in table's arraypart array? or why
have this macro at all?)

# ltable.h:gkey
Node* -> TValue*
Gets node key's TValue.

# ltable.h:gval
Node* -> TValue*
Gets node value's TValue.

# ltable.h:gnext
Node* -> Node*
Gets node following given node in chain of nodes.