=head1 NAME

luafunc - standard library functions (standard library)

=head1 OVERVIEW

The standard Lua libraries provide useful functions that are
implemented directly through the C API.  Some of these functions
provide essential services to the language (e.g., C<type> and
C<getmetatable>); others provide access to "outside" services (e.g.,
I/O); and others could be implemented in Lua itself, but are quite
useful or have critical performance requirements that deserve an
implementation in C (e.g., C<sort>).

All libraries are implemented through the official C API and are
provided as separate C modules.  Currently, Lua has the following
standard libraries:

=over 4

=item basic library;

=item package library;

=item string manipulation;

=item table manipulation;

=item mathematical functions (sin, log, etc.);

=item input and output;

=item operating system facilities;

=item debug facilities.

=back

Except for the basic and package libraries, each library provides all
its functions as fields of a global table or as methods of its
objects.

To have access to these libraries, the C host program must call
C<luaL_openlibs>, which open all standard libraries.  Alternatively,
it can open them individually by calling C<luaopen_base> (for the
basic library), C<luaopen_package> (for the package library),
C<luaopen_string> (for the string library), C<luaopen_table> (for the
table library), C<luaopen_math> (for the mathematical library),
C<luaopen_io> (for the I/O and the Operating System libraries), and
C<luaopen_debug> (for the debug library).  These functions are
declared in C<lualib.h> and should not be called directly: you must
call them like any other Lua C function, e.g., by using C<lua_call>.

=head1 REFERENCE

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.

=head2 C<assert>

  assert (v [, message])

Issues an error when the value of its argument C<v> is false (i.e.,
C<nil> or C<false>); otherwise, returns all its arguments.  C<message>
is an error message; when absent, it defaults to "assertion failed!"

=head2 C<collectgarbage>

  collectgarbage (opt [, arg])

This function is a generic interface to the garbage collector.  It
performs different functions according to its first argument, C<opt>:

=over

=item C<"stop">

stops the garbage collector.

=item C<"restart">

restarts the garbage collector.

=item C<"collect">

performs a full garbage-collection cycle.

=item C<"count">

returns the total memory in use by Lua (in Kbytes).

=item C<"step">

performs a garbage-collection step.

The step "size" is controlled by C<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 C<arg>.  Returns C<true> if
the step finished a collection cycle.

=item C<"setpause">

sets C<arg>/100 as the new value for the I<pause> of the collector
(see sect 2.10).

=item C<"setstepmul">

sets C<arg>/100 as the new value for the I<step multiplier> of
the collector (see sect 2.10).

=back

=head2 C<dofile>

  dofile (filename)

Opens the named file and executes its contents as a Lua chunk.  When
called without arguments, C<dofile> executes the contents of the
standard input (C<stdin>).  Returns all values returned by the chunk.
In case of errors, C<dofile> propagates the error to its caller (that
is, C<dofile> does not run in protected mode).

=head2 C<error>

  error (message [, level])

Terminates the last protected function called and returns C<message>
as the error message.  Function C<error> never returns.

Usually, C<error> adds some information about the error position at
the beginning of the message.  The C<level> argument specifies how to
get the error position.  With level 1 (the default), the error
position is where the C<error> function was called.  Level 2 points
the error to where the function that called C<error> was called; and
so on.  Passing a level 0 avoids the addition of error position
information to the message.

=head2 C<_G>

  _G

A global variable (not a function) that holds the global environment
(that is, C<_G._G = _G>).  Lua itself does not use this variable;
changing its value does not affect any environment, nor vice-versa.
(Use L</setfenv> to change environments.)

=head2 C<getfenv>

  getfenv (f)

Returns the current environment in use by the function.  C<f> can be a
Lua function or a number that specifies the function at that stack
level: Level 1 is the function calling C<getfenv>.  If the given
function is not a Lua function, or if C<f> is 0, C<getfenv> returns
the global environment.  The default for C<f> is 1.

=head2 C<getmetatable>

  getmetatable (object)

If C<object> does not have a metatable, returns C<nil>.  Otherwise, if
the object's metatable has a C<"__metatable"> field, returns the
associated value.  Otherwise, returns the metatable of the given
object.

=head2 C<ipairs>

  ipairs (t)

Returns three values: an iterator function, the table C<t>, and 0, so
that the construction

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

will iterate over the pairs (C<1,t[1]>), (C<2,t[2]>),
E<middot>E<middot>E<middot>, up to the first integer key absent from
the table.

See L</next> for the caveats of modifying the table during its
traversal.

=head2 C<load>

  load (func [, chunkname])

Loads a chunk using function C<func> to get its pieces.  Each call to
C<func> must return a string that concatenates with previous results.
A return of C<nil> (or no value) signals the end of the chunk.

If there are no errors, returns the compiled chunk as a function;
otherwise, returns C<nil> plus the error message.  The environment of
the returned function is the global environment.

C<chunkname> is used as the chunk name for error messages and debug
information.

=head2 C<loadfile>

  loadfile ([filename])

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

=head2 C<loadstring>

  loadstring (string [, chunkname])

Similar to C<load>, but gets the chunk from the given string.

To load and run a given string, use the idiom

  assert(loadstring(s))()

=head2 C<next>

  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.
C<next> returns the next index of the table and its associated value.
When called with C<nil> as its second argument, C<next> returns an
initial index and its associated value.  When called with the last
index, or with C<nil> in an empty table, C<next> returns C<nil>.  If
the second argument is absent, then it is interpreted as C<nil>.  In
particular, you can use C<next(t)> to check whether a table is empty.

The order in which the indices are enumerated is not specified, I<even
for numeric indices>.  (To traverse a table in numeric order, use a
numerical C<for> or the C<ipairs> function.)

The behavior of C<next> is I<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.

=head2 C<pairs>

  pairs (t)

Returns three values: the C<next> function, the table C<t>, and
C<nil>, so that the construction

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

will iterate over all keyE<ndash>value pairs of table C<t>.

See L</next> for the caveats of modifying the table during its
traversal.

=head2 C<pcall>

  pcall (f, arg1, ...)

Calls function C<f> with the given arguments in I<protected mode>.
This means that any error inside C<f> is not propagated; instead,
C<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, C<pcall> also returns all
results from the call, after this first result.  In case of any error,
C<pcall> returns C<false> plus the error message.

=head2 C<print>

  print (...)

Receives any number of arguments, and prints their values to
C<stdout>, using the C<tostring> function to convert them to strings.
C<print> is not intended for formatted output, but only as a quick way
to show a value, typically for debugging.  For formatted output, use
C<string.format>.

=head2 C<rawequal>

  rawequal (v1, v2)

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

=head2 C<rawget>

  rawget (table, index)

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

=head2 C<rawset>

  rawset (table, index, value)

Sets the real value of C<table[index]> to C<value>, without invoking
any metamethod.  C<table> must be a table, C<index> any value
different from C<nil>, and C<value> any Lua value.

This function returns C<table>.

=head2 C<select>

  select (index, ...)

If C<index> is a number, returns all arguments after argument number
C<index>.  Otherwise, C<index> must be the string C<"#">, and
C<select> returns the total number of extra arguments it received.

=head2 C<setfenv>

  setfenv (f, table)

Sets the environment to be used by the given function.  C<f> can be a
Lua function or a number that specifies the function at that stack
level: Level 1 is the function calling C<setfenv>.  C<setfenv> returns
the given function.

As a special case, when C<f> is 0 C<setfenv> changes the environment
of the running thread.  In this case, C<setfenv> returns no values.

=head2 C<setmetatable>

setmetatable (table, metatable)

Sets the metatable for the given table.  (You cannot change the
metatable of other types from Lua, only from C.)  If C<metatable> is
C<nil>, removes the metatable of the given table.  If the original
metatable has a C<"__metatable"> field, raises an error.

This function returns C<table>.

=head2 C<tonumber>

  tonumber (e [, base])

Tries to convert its argument to a number.  If the argument is already
a number or a string convertible to a number, then C<tonumber> returns
this number; otherwise, it returns C<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 'C<A>' (in either upper or lower case) represents 10,
'C<B>' represents 11, and so forth, with 'C<Z>' representing 35.  In
base 10 (the default), the number may have a decimal part, as well as
an optional exponent part (see sect 2.1).  In other bases, only
unsigned integers are accepted.

=head2 C<tostring>

  tostring (e)

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 C<string.format>.

If the metatable of C<e> has a C<"__tostring"> field, then C<tostring>
calls the corresponding value with C<e> as argument, and uses the
result of the call as its result.

=head2 C<type>

  type (v)

Returns the type of its only argument, coded as a string.  The
possible results of this function are "C<nil>" (a string, not the
value C<nil>), "C<number>", "C<string>", "C<boolean>", "C<table>",
"C<function>", "C<thread>", and "C<userdata>".

=head2 C<unpack>

  unpack (list [, i [, j]])

Returns the elements from the given table.  This function is
equivalent to

  return list[i], list[i+1], ..., list[j]

except that the above code can be written only for a fixed number of
elements.  By default, C<i> is 1 and C<j> is the length of the list,
as defined by the length operator (see sect 2.5.5).

=head2 C<_VERSION>

  _VERSION

A global variable (not a function) that holds a string containing the
current interpreter version.  The current contents of this variable is
"C<Lua 5.1>".

=head2 C<xpcall>

  xpcall (f, err)

This function is similar to C<pcall>, except that you can set a new
error handler.

C<xpcall> calls function C<f> in protected mode, using C<err> as the
error handler.  Any error inside C<f> is not propagated; instead,
C<xpcall> catches the error, calls the C<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, C<xpcall> also returns all results from
the call, after this first result.  In case of any error, C<xpcall>
returns C<false> plus the result from C<err>.

=head1 VERSION

This is Lua version 5.1.1.

=head1 CREDITS

Lua is developed at Lua.org, a laboratory of the Department of
Computer Science of PUC-Rio (the Pontifical Catholic University of Rio
de Janeiro in Brazil).  For more information about the authors, see
http://www.lua.org/authors.html .

=head1 LICENSE

Lua is licensed under the terms of the MIT license reproduced below.
This means that Lua is free software and can be used for both academic
and commercial purposes at absolutely no cost.

For details and rationale, see http://www.lua.org/license.html .

~~~~~

Copyright (C) 1994-2006 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

~~~~~