repo/luan: website/src/manual.html.luan annotate

annotate website/src/manual.html.luan @ 417:a40e99cf0b0b

work on manual

author	Franklin Schmidt <fschmidt@gmail.com>
date	Thu, 30 Apr 2015 21:30:32 -0600
parents	ba8b0aae6453
children	455784e2227d

rev	line source
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	1 local Io = require "luan:Io"
db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	2 local Html = require "luan:Html"
db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	3 local Http = require "luan:web/Http"
387 23d075ce1e48 add website/src/Shared.luan Franklin Schmidt <fschmidt@gmail.com> parents: 386 diff changeset	4 local Shared = require "site:/Shared"
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	5
db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	6
db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	7 function service()
db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	8 Io.stdout = Http.response.text_writer()
391 2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	9 %>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	10 <html>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	11 <head>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	12 <% Html.simply_html_head() %>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	13 <title>Luan Reference Manual</title>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	14 </head>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	15 <body>
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	16
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	17 <div container>
387 23d075ce1e48 add website/src/Shared.luan Franklin Schmidt <fschmidt@gmail.com> parents: 386 diff changeset	18 <% Shared.header() %>
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	19
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	20 <h1>Luan Reference Manual</h1>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	21
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	22 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	23 <small>
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	24 Original copyright © 2015 Lua.org, PUC-Rio.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	25 Freely available under the terms of the
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	26 <a href="http://www.lua.org/license.html">Lua license</a>.
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	27 Modified for Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	28 </small>
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	29 </p>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	30
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	31 <hr/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	32
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	33 <h2>Contents</h2>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	34
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	35 <div margin-bottom="1em"><a href="#intro">Introduction</a></div>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	36
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	37 <div margin-bottom="1em">
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	38 <a href="#basic">Basic Concepts</a>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	39 <ul>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	40 <li><a href="#types">Values and Types</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	41 <li><a href="#env">Environments</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	42 <li><a href="#error">Error Handling</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	43 <li><a href="#meta">Metatables and Metamethods</a></li>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	44 <li><a href="#gc">Garbage Collection</a></li>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	45 </ul>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	46 </div>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	47
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	48 <div margin-bottom="1em">
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	49 <a href="#lang">The Language</a>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	50 <ul>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	51 <li><a href="#lex">Lexical Conventions</a></li>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	52 <li><a href="#vars">Variables</a></li>
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	53 <li>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	54 <a href="#stmts">Statements</a>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	55 <ul>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	56 <li><a href="#blocks">Blocks</a></li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	57 <li><a href="#chunks">Chunks</a></li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	58 <li><a href="#assignment">Assignment</a></li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	59 <li><a href="#control">Control Structures</a></li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	60 <li><a href="#for">For Statement</a></li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	61 <li><a href="#fn_stmt">Function Calls as Statements</a></li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	62 <li><a href="#local_stmt">Local Declarations</a></li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	63 </ul>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	64 </li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	65 <li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	66 <a href="#expressions">Expressions</a>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	67 <ul>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	68 <li><a href="#arithmetic">Arithmetic Operators</a></li>
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	69 <li><a href="#conversions">Coercions and Conversions</a></li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	70 <li><a href="#relational">Relational Operators</a></li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	71 <li><a href="#logical_ops">Logical Operators</a></li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	72 <li><a href="#concatenation">Concatenation</a></li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	73 <li><a href="#length">The Length Operator</a></li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	74 <li><a href="#precedence">Precedence</a></li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	75 <li><a href="#constructors">Table Constructors</a></li>
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	76 <li><a href="#fn_calls">Function Calls</a></li>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	77 <li><a href="#fn_def">Function Definitions</a></li>
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	78 </ul>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	79 </li>
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	80 <li><a href="#visibility">>Visibility Rules</a></li>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	81 </ul>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	82 </div>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	83
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	84 <hr/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	85
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	86
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	87 <h2 margin-top="1em"><a name="intro">Introduction</a></h2>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	88
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	89 <p>Luan is a high level programming language based on <a href="http://www.lua.org">Lua</a>. A great strength of Lua is its simplicity and Luan takes this even further, being even simpler than Lua. The goal is to provide a simple programming language for the casual programmer with as few concepts as possible so that one can quickly learn the language and then easily understand any code written in Luan.</p>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	90
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	91 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	92
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	93 <p>Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding feature to Luan, but rather by providing a complete set of libraries.</p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	94
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	95
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	96 <h2 margin-top="1em"><a name="basic">Basic Concepts</a></h2>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	97
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	98 <p>This section describes the basic concepts of the language.</p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	99
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	100 <h3 margin-top="1em"><a name="types">Values and Types</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	101
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	102 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	103 Luan is a <i>dynamically typed language</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	104 This means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	105 variables do not have types; only values do.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	106 There are no type definitions in the language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	107 All values carry their own type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	110 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	111 All values in Luan are <i>first-class values</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	112 This means that all values can be stored in variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	113 passed as arguments to other functions, and returned as results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	116 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	117 There are eight basic types in Luan:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	118 <i>nil</i>, <i>boolean</i>, <i>number</i>,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	119 <i>string</i>, <i>binary</i>, <i>function</i>, <i>userdata</i>,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	120 and <i>table</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	121 <i>Nil</i> is the type of the value <b>nil</b>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	122 whose main property is to be different from any other value;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	123 it usually represents the absence of a useful value.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	124 <i>Nil</i> is implemented as the Java value <i>null</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	125 <i>Boolean</i> is the type of the values <b>false</b> and <b>true</b>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	126 <i>Boolean</i> is implemented as the Java class <i>Boolean</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	127 <i>Number</i> represents both
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	128 integer numbers and real (floating-point) numbers.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	129 <i>Number</i> is implemented as the Java class <i>Number</i>. Any Java subclass of <i>Number</i> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	130 the underlying Java implementation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	131
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	132 <i>String</i> is implemented as the Java class <i>String</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	133 <i>Binary</i> is implemented as the Java type <i>byte[]</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	134
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	135
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	136 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	137 Luan can call (and manipulate) functions written in Luan and
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	138 functions written in Java (see <a href="#3.4.10">§3.4.10</a>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	139 Both are represented by the type <i>function</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	140
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	141
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	142 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	143 The type <i>userdata</i> is provided to allow arbitrary Java objects to
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	144 be stored in Luan variables.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	145 A userdata value is a Java object that isn't one of the standard Luan types.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	146 Userdata has no predefined operations in Luan,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	147 except assignment and identity test.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	148 Userdata is useful then Java access is enabled in Luan
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	149
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	150
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	151
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	152 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	153 The type <i>table</i> implements associative arrays,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	154 that is, arrays that can be indexed not only with numbers,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	155 but with any Luan value except <b>nil</b>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	156 Tables can be <i>heterogeneous</i>;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	157 that is, they can contain values of all types (except <b>nil</b>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	158 Any key with value <b>nil</b> is not considered part of the table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	159 Conversely, any key that is not part of a table has
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	160 an associated value <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	163 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	164 Tables are the sole data-structuring mechanism in Luan;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	165 they can be used to represent ordinary arrays, sequences,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	166 symbol tables, sets, records, graphs, trees, etc.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	167 To represent records, Luan uses the field name as an index.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	168 The language supports this representation by
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	169 providing <tt>a.name</tt> as syntactic sugar for <tt>a["name"]</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	170 There are several convenient ways to create tables in Luan
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	171 (see <a href="#3.4.9">§3.4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	174 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	175 We use the term <i>sequence</i> to denote a table where
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	176 the set of all positive numeric keys is equal to {1..<i>n</i>}
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	177 for some non-negative integer <i>n</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	178 which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	181 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	182 Like indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	183 the values of table fields can be of any type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	184 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	185 because functions are first-class values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	186 table fields can contain functions.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	187 Thus tables can also carry <i>methods</i> (see <a href="#3.4.11">§3.4.11</a>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	190 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	191 The indexing of tables follows
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	192 the definition of raw equality in the language.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	193 The expressions <tt>a[i]</tt> and <tt>a[j]</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	194 denote the same table element
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	195 if and only if <tt>i</tt> and <tt>j</tt> are raw equal
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	196 (that is, equal without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	197 In particular, floats with integral values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	198 are equal to their respective integers
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	199 (e.g., <tt>1.0 == 1</tt>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	200
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	201
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	202 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	203 Luan values are <i>objects</i>:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	204 variables do not actually <i>contain</i> values,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	205 only <i>references</i> to them.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	206 Assignment, parameter passing, and function returns
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	207 always manipulate references to values;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	208 these operations do not imply any kind of copy.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	211 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	212 The library function <a href="#pdf-type"><tt>Luan.type</tt></a> returns a string describing the type
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	213 of a given value (see <a href="#6.1">§6.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	218
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	219 <h3 margin-top="1em"><a name="env">Environments</a></h3>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	221 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	222 As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	223 any reference to a free name
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	224 (that is, a name not bound to any declaration) <tt>var</tt>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	225 is syntactically translated to <tt>_ENV.var</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	226 Moreover, every chunk is compiled in the scope of
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	227 an external local variable named <tt>_ENV</tt> (see <a href="#3.3.2">§3.3.2</a>),
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	228 so <tt>_ENV</tt> itself is never a free name in a chunk.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	229
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	230
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	231 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	232 Despite the existence of this external <tt>_ENV</tt> variable and
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	233 the translation of free names,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	234 <tt>_ENV</tt> is a completely regular name.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	235 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	236 you can define new variables and parameters with that name.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	237 Each reference to a free name uses the <tt>_ENV</tt> that is
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	238 visible at that point in the program,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	239 following the usual visibility rules of Luan (see <a href="#3.5">§3.5</a>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	240
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	241
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	242 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	243 Any table used as the value of <tt>_ENV</tt> is called an <i>environment</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	244
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	245
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	246 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	247 When Luan loads a chunk,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	248 the default value for its <tt>_ENV</tt> is an empty table.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	249
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	250 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	251 Luan also provides all chunks with two other local values: <tt>require</tt> and <tt>java</tt>. These are functions used to load and access libraries and other modules.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	252
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	253
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	254
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	255
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	256 <h3 margin-top="1em"><a name="error">Error Handling</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	257
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	258 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	259 Luan code can explicitly generate an error by calling the
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	260 <a href="#pdf-error"><tt>error</tt></a> function.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	261 If you need to catch errors in Luan,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	262 you can use <a href="#pdf-pcall"><tt>pcall</tt></a> or <a href="#pdf-xpcall"><tt>try</tt></a>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	263 to call a given function in <i>protected mode</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	266 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	267 Whenever there is an error,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	268 an <i>error object</i> (also called an <i>error message</i>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	269 is propagated with information about the error.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	270 Luan itself only generates errors whose error object is a string,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	271 but programs may generate errors with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	272 any value as the error object.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	273 It is up to the Luan program or its host to handle such error objects.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	274
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	275
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	276
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	277
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	278
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	279 <h3 margin-top="1em"><a name="meta">Metatables and Metamethods</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	280
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	281 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	282 Every table in Luan can have a <i>metatable</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	283 This <i>metatable</i> is an ordinary Luan table
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	284 that defines the behavior of the original value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	285 under certain special operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	286 You can change several aspects of the behavior
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	287 of operations over a value by setting specific fields in its metatable.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	288 For instance, when a table is the operand of an addition,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	289 Luan checks for a function in the field "<tt>__add</tt>" of the table's metatable.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	290 If it finds one,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	291 Luan calls this function to perform the addition.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	292
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	293
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	294 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	295 The keys in a metatable are derived from the <i>event</i> names;
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	296 the corresponding values are called <ii>metamethods</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	297 In the previous example, the event is <tt>"add"</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	298 and the metamethod is the function that performs the addition.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	301 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	302 You can query the metatable of any table
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	303 using the <a href="#pdf-getmetatable"><tt>get_metatable</tt></a> function.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	307 You can replace the metatable of tables
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	308 using the <a href="#pdf-setmetatable"><tt>set_metatable</tt></a> function.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	309
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	310
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	311 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	312 A metatable controls how a table behaves in
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	313 arithmetic operations, bitwise operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	314 order comparisons, concatenation, length operation, calls, and indexing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	318 A detailed list of events controlled by metatables is given next.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	319 Each operation is identified by its corresponding event name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	320 The key for each event is a string with its name prefixed by
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	321 two underscores, '<tt>__</tt>';
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	322 for instance, the key for operation "add" is the
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	323 string "<tt>__add</tt>".
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	324 Note that queries for metamethods are always raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	325 the access to a metamethod does not invoke other metamethods.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	326 You can emulate how Luan queries a metamethod for an object <tt>obj</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	327 with the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	328
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	329 <p><tt><pre>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	330 raw_get(get_metatable(obj) or {}, "__" .. event_name)
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	331 </pre></tt></p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	332
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	333 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	334 Here are the events:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	336 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	338 <li><b>"add": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	339 the <tt>+</tt> operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	340
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	341 If any operand for an addition is a table,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	342 Luan will try to call a metamethod.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	343 First, Luan will check the first operand (even if it is valid).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	344 If that operand does not define a metamethod for the "<tt>__add</tt>" event,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	345 then Luan will check the second operand.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	346 If Luan can find a metamethod,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	347 it calls the metamethod with the two operands as arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	348 and the result of the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	349 (adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	350 is the result of the operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	351 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	352 it raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	353 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	355 <li><b>"sub": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	356 the <tt>-</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	358 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	359 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	361 <li><b>"mul": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	362 the <tt>*</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	364 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	365 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	367 <li><b>"div": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	368 the <tt>/</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	370 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	371 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	373 <li><b>"mod": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	374 the <tt>%</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	376 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	377 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	379 <li><b>"pow": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	380 the <tt>^</tt> (exponentiation) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	382 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	383 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	385 <li><b>"unm": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	386 the <tt>-</tt> (unary minus) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	388 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	389 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	391 <li><b>"concat": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	392 the <tt>..</tt> (concatenation) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	393
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	394 Behavior similar to the "add" operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	395 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	397 <li><b>"len": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	398 the <tt>#</tt> (length) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	399
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	400 If there is a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	401 Luan calls it with the object as argument,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	402 and the result of the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	403 (always adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	404 is the result of the operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	405 If there is no metamethod but the object is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	406 then Luan uses the table length operation (see <a href="#3.4.7">§3.4.7</a>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	407 Otherwise, Luan raises an error.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	408 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	410 <li><b>"eq": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	411 the <tt>==</tt> (equal) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	413 Behavior similar to the "add" operation,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	414 except that Luan will try a metamethod only when the values
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	415 being compared are both tables
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	416 and they are not primitively equal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	417 The result of the call is always converted to a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	418 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	420 <li><b>"lt": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	421 the <tt><</tt> (less than) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	422
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	423 Behavior similar to the "add" operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	424 The result of the call is always converted to a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	425 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	427 <li><b>"le": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	428 the <tt><=</tt> (less equal) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	430 Unlike other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	431 The less-equal operation can use two different events.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	432 First, Luan looks for the "<tt>__le</tt>" metamethod in both operands,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	433 like in the "lt" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	434 If it cannot find such a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	435 then it will try the "<tt>__lt</tt>" event,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	436 assuming that <tt>a <= b</tt> is equivalent to <tt>not (b < a)</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	437 As with the other comparison operators,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	438 the result is always a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	439 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	441 <li><b>"index": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	442 The indexing access <tt>table[key]</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	443
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	444 This event happens
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	445 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	446 The metamethod is looked up in <tt>table</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	449 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	450 Despite the name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	451 the metamethod for this event can be either a function or a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	452 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	453 it is called with <tt>table</tt> and <tt>key</tt> as arguments.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	454 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	455 the final result is the result of indexing this table with <tt>key</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	456 (This indexing is regular, not raw,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	457 and therefore can trigger another metamethod.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	458 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	460 <li><b>"newindex": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	461 The indexing assignment <tt>table[key] = value</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	463 Like the index event,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	464 this event happens when
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	465 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	466 The metamethod is looked up in <tt>table</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	469 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	470 Like with indexing,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	471 the metamethod for this event can be either a function or a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	472 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	473 it is called with <tt>table</tt>, <tt>key</tt>, and <tt>value</tt> as arguments.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	474 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	475 Luan does an indexing assignment to this table with the same key and value.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	476 (This assignment is regular, not raw,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	477 and therefore can trigger another metamethod.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	480 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	481 Whenever there is a "newindex" metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	482 Luan does not perform the primitive assignment.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	483 (If necessary,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	484 the metamethod itself can call <a href="#pdf-rawset"><tt>raw_set</tt></a>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	485 to do the assignment.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	486 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	488 <li><b>"call": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	489 The call operation <tt>func(args)</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	490
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	491 This event happens when Luan tries to call a table.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	492 The metamethod is looked up in <tt>func</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	493 If present,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	494 the metamethod is called with <tt>func</tt> as its first argument,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	495 followed by the arguments of the original call (<tt>args</tt>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	496 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	498 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	502
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	503 <h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	504
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	505 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	506 Luan uses Java's garbage collection.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	507
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	508
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	509
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	510
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	511
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	512 <h2 margin-top="1em"><a name="lang">The Language</a></h2>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	513
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	514 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	515 This section describes the lexis, the syntax, and the semantics of Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	516 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	517 this section describes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	518 which tokens are valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	519 how they can be combined,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	520 and what their combinations mean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	524 Language constructs will be explained using the usual extended BNF notation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	525 in which
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	526 {<i>a</i>} means 0 or more <i>a</i>'s, and
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	527 [<i>a</i>] means an optional <i>a</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	528 Non-terminals are shown like non-terminal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	529 keywords are shown like <b>kword</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	530 and other terminal symbols are shown like ‘<b>=</b>’.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	531 The complete syntax of Luan can be found in <a href="#9">§9</a>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	532 at the end of this manual.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	535
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	536 <h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	537
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	538 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	539 Luan ignores spaces and comments
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	540 between lexical elements (tokens),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	541 except as delimiters between names and keywords.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	542 Luan generally considers the end of a line to be the end of a statement. This catches errors and encourages readability. The exception to this is in paranthesis ( <i>(...)</i>, <i>[...]</i>, and <i>{...}</i> ) where the end of line is treated as white space.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	543
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	544 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	545 <i>Names</i>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	546 (also called <i>identifiers</i>)
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	547 in Luan can be any string of letters,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	548 digits, and underscores,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	549 not beginning with a digit.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	550 Identifiers are used to name variables, table fields, and labels.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	553 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	554 The following <i>keywords</i> are reserved
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	555 and cannot be used as names:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	557
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	558 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	559 and break do else elseif end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	560 false for function goto if in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	561 local nil not or repeat return
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	562 then true until while
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	563 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	565 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	566 Luan is a case-sensitive language:
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	567 <tt>and</tt> is a reserved word, but <tt>And</tt> and <tt>AND</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	568 are two different, valid names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	572 The following strings denote other tokens:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	573
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	574 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	575 + - * / % ^ #
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	576 & ~ \| << >> //
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	577 == ~= <= >= < > =
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	578 ( ) { } [ ] ::
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	579 ; : , . .. ...
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	580 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	582 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	583 <i>Literal strings</i>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	584 can be delimited by matching single or double quotes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	585 and can contain the following C-like escape sequences:
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	586 '<tt>\a</tt>' (bell),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	587 '<tt>\b</tt>' (backspace),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	588 '<tt>\f</tt>' (form feed),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	589 '<tt>\n</tt>' (newline),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	590 '<tt>\r</tt>' (carriage return),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	591 '<tt>\t</tt>' (horizontal tab),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	592 '<tt>\v</tt>' (vertical tab),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	593 '<tt>\\</tt>' (backslash),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	594 '<tt>\"</tt>' (quotation mark [double quote]),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	595 and '<tt>\'</tt>' (apostrophe [single quote]).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	596 A backslash followed by a real newline
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	597 results in a newline in the string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	598 The escape sequence '<tt>\z</tt>' skips the following span
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	599 of white-space characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	600 including line breaks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	601 it is particularly useful to break and indent a long literal string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	602 into multiple lines without adding the newlines and spaces
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	603 into the string contents.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	606 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	607 Luan can specify any character in a literal string by its numerical value.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	608 This can be done
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	609 with the escape sequence <tt>\x<i>XX</i></tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	610 where <i>XX</i> is a sequence of exactly two hexadecimal digits,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	611 or with the escape sequence <tt>\<i>ddd</i></tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	612 where <i>ddd</i> is a sequence of up to three decimal digits.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	613 (Note that if a decimal escape sequence is to be followed by a digit,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	614 it must be expressed using exactly three digits.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	618 Literal strings can also be defined using a long format
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	619 enclosed by <i>long brackets</i>.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	620 We define an <i>opening long bracket of level <i>n</i></i> as an opening
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	621 square bracket followed by <i>n</i> equal signs followed by another
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	622 opening square bracket.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	623 So, an opening long bracket of level 0 is written as <tt>[[</tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	624 an opening long bracket of level 1 is written as <tt>[=[</tt>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	625 and so on.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	626 A <i>closing long bracket</i> is defined similarly;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	627 for instance,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	628 a closing long bracket of level 4 is written as <tt>]====]</tt>.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	629 A <i>long literal</i> starts with an opening long bracket of any level and
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	630 ends at the first closing long bracket of the same level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	631 It can contain any text except a closing bracket of the same level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	632 Literals in this bracketed form can run for several lines,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	633 do not interpret any escape sequences,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	634 and ignore long brackets of any other level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	635 Any kind of end-of-line sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	636 (carriage return, newline, carriage return followed by newline,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	637 or newline followed by carriage return)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	638 is converted to a simple newline.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	641 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	642 Any character in a literal string not
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	643 explicitly affected by the previous rules represents itself.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	644 However, Luan opens files for parsing in text mode,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	645 and the system file functions may have problems with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	646 some control characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	647 So, it is safer to represent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	648 non-text data as a quoted literal with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	649 explicit escape sequences for non-text characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	653 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	654 when the opening long bracket is immediately followed by a newline,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	655 the newline is not included in the string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	656 As an example
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	657 the five literal strings below denote the same string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	658
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	659 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	660 a = 'alo\n123"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	661 a = "alo\n123\""
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	662 a = '\97lo\10\04923"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	663 a = [[alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	664 123"]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	665 a = [==[
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	666 alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	667 123"]==]
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	668 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	670 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	671 A <i>numerical constant</i> (or <i>numeral</i>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	672 can be written with an optional fractional part
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	673 and an optional decimal exponent,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	674 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	675 Luan also accepts hexadecimal constants,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	676 which start with <tt>0x</tt> or <tt>0X</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	677 Hexadecimal constants also accept an optional fractional part
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	678 plus an optional binary exponent,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	679 marked by a letter '<tt>p</tt>' or '<tt>P</tt>'.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	680 A numeric constant with a fractional dot or an exponent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	681 denotes a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	682 otherwise it denotes an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	683 Examples of valid integer constants are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	684
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	685 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	686 3 345 0xff 0xBEBADA
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	687 </pre></tt></p>
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	688
8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	689 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	690 Examples of valid float constants are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	691
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	692 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	693 3.0 3.1416 314.16e-2 0.31416E1 34e1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	694 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	695 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	697 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	698 A <i>comment</i> starts with a double hyphen (<tt>--</tt>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	699 anywhere outside a string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	700 If the text immediately after <tt>--</tt> is not an opening long bracket,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	701 the comment is a <i>short comment</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	702 which runs until the end of the line.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	703 Otherwise, it is a <i>long comment</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	704 which runs until the corresponding closing long bracket.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	705 Long comments are frequently used to disable code temporarily.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	710
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	711 <h3 margin-top="1em"><a name="vars">Variables</a></h3>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	714 Variables are places that store values.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	715 There are three kinds of variables in Luan:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	716 global variables, local variables, and table fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	719 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	720 A single name can denote a global variable or a local variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	721 (or a function's formal parameter,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	722 which is a particular kind of local variable):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	723
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	724 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	725 var ::= Name
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	726 </pre></tt></p>
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	727
8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	728 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	729 Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	733 Any variable name is assumed to be global unless explicitly declared
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	734 as a local (see <a href="#3.3.7">§3.3.7</a>).
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	735 Local variables are <i>lexically scoped</i>:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	736 local variables can be freely accessed by functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	737 defined inside their scope (see <a href="#3.5">§3.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	740 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	741 Before the first assignment to a variable, its value is <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	745 Square brackets are used to index a table:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	746
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	747 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	748 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	749 </pre></tt></p>
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	750
8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	751 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	752 The meaning of accesses to table fields can be changed via metatables.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	753 An access to an indexed variable <tt>t[i]</tt> is equivalent to
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	754 a call <tt>gettable_event(t,i)</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	755 (See <a href="#2.4">§2.4</a> for a complete description of the
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	756 <tt>gettable_event</tt> function.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	757 This function is not defined or callable in Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	758 We use it here only for explanatory purposes.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	761 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	762 The syntax <tt>var.Name</tt> is just syntactic sugar for
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	763 <tt>var["Name"]</tt>:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	764
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	765 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	766 var ::= prefixexp ‘<b>.</b>’ Name
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	767 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	769 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	770 An access to a global variable <tt>x</tt>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	771 is equivalent to <tt>_ENV.x</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	772 Due to the way that chunks are compiled,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	773 <tt>_ENV</tt> is never a global name (see <a href="#2.2">§2.2</a>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	778
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	779 <h3 margin-top="1em"><a name="stmts">Statements</a></h3>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	780
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	781 <p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	782 Luan supports an almost conventional set of statements,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	783 similar to those in Pascal or C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	784 This set includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	785 assignments, control structures, function calls,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	786 and variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	789
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	790 <h4 margin-top="1em"><a name="blocks">Blocks</a></h4>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	792 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	793 A block is a list of statements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	794 which are executed sequentially:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	795
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	796 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	797 block ::= {stat}
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	798 </pre></tt></p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	799
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	800 <p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	801 Luan has <i>empty statements</i>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	802 that allow you to separate statements with semicolons,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	803 start a block with a semicolon
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	804 or write two semicolons in sequence:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	805
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	806 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	807 stat ::= ‘<b>;</b>’
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	808 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	810 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	811 A block can be explicitly delimited to produce a single statement:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	812
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	813 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	814 stat ::= <b>do</b> block <b>end</b>
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	815 </pre></tt></p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	816
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	817 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	818 Explicit blocks are useful
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	819 to control the scope of variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	820 Explicit blocks are also sometimes used to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	821 add a <b>return</b> statement in the middle
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	822 of another block (see <a href="#3.3.4">§3.3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	827
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	828 <h4 margin-top="1em"><a name="chunks">Chunks</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	829
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	830 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	831 The unit of compilation of Luan is called a <i>chunk</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	832 Syntactically,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	833 a chunk is simply a block:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	834
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	835 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	836 chunk ::= block
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	837 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	838
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	839 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	840 Luan handles a chunk as the body of an anonymous function
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	841 with a variable number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	842 (see <a href="#3.4.11">§3.4.11</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	843 As such, chunks can define local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	844 receive arguments, and return values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	847 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	848 A chunk can be stored in a file or in a string inside the host program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	849 To execute a chunk,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	850 Luan first <i>loads</i> it,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	851 compiling the chunk's code,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	852 and then Luan executes the compiled code.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	853
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	854
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	855
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	856
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	857
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	858 <h4 margin-top="1em"><a name="assignment">Assignment</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	859
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	860 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	861 Luan allows multiple assignments.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	862 Therefore, the syntax for assignment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	863 defines a list of variables on the left side
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	864 and a list of expressions on the right side.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	865 The elements in both lists are separated by commas:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	866
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	867 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	868 stat ::= varlist ‘<b>=</b>’ explist
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	869 varlist ::= var {‘<b>,</b>’ var}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	870 explist ::= exp {‘<b>,</b>’ exp}
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	871 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	872
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	873 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	874 Expressions are discussed in <a href="#3.4">§3.4</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	877 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	878 Before the assignment,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	879 the list of values is <i>adjusted</i> to the length of
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	880 the list of variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	881 If there are more values than needed,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	882 the excess values are thrown away.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	883 If there are fewer values than needed,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	884 the list is extended with as many <b>nil</b>'s as needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	885 If the list of expressions ends with a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	886 then all values returned by that call enter the list of values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	887 before the adjustment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	888 (except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	891 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	892 The assignment statement first evaluates all its expressions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	893 and only then the assignments are performed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	894 Thus the code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	895
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	896 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	897 i = 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	898 i, a[i] = i+1, 20
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	899 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	900
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	901 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	902 sets <tt>a[3]</tt> to 20, without affecting <tt>a[4]</tt>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	903 because the <tt>i</tt> in <tt>a[i]</tt> is evaluated (to 3)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	904 before it is assigned 4.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	905 Similarly, the line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	906
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	907 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	908 x, y = y, x
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	909 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	910
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	911 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	912 exchanges the values of <tt>x</tt> and <tt>y</tt>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	913 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	914
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	915 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	916 x, y, z = y, z, x
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	917 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	918
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	919 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	920 cyclically permutes the values of <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	923 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	924 The meaning of assignments to global variables
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	925 and table fields can be changed via metatables.
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	926 An assignment to an indexed variable <tt>t[i] = val</tt> is equivalent to
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	927 <tt>settable_event(t,i,val)</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	928 (See <a href="#2.4">§2.4</a> for a complete description of the
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	929 <tt>settable_event</tt> function.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	930 This function is not defined or callable in Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	931 We use it here only for explanatory purposes.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	934 <p>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	935 An assignment to a global name <tt>x = val</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	936 is equivalent to the assignment
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	937 <tt>_ENV.x = val</tt> (see <a href="#2.2">§2.2</a>).
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	938
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	939
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	940
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	941
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	942 <h4 margin-top="1em"><a name="control">Control Structures</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	943
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	944 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	945 The control structures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	946 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	947 familiar syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	948
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	949 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	950 stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	951 stat ::= <b>repeat</b> block <b>until</b> exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	952 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	953 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	954
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	955 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	956 Luan also has a <b>for</b> statement (see <a href="#3.3.5">§3.3.5</a>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	959 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	960 The condition expression of a
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	961 control structure must be a boolean.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	962 Any other value type will produce an error.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	963 This helps catch errors and makes code more readable.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	966 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	967 In the <b>repeat</b>–<b>until</b> loop,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	968 the inner block does not end at the <b>until</b> keyword,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	969 but only after the condition.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	970 So, the condition can refer to local variables
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	971 declared inside the loop block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	975 The <b>break</b> statement terminates the execution of a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	976 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	977 skipping to the next statement after the loop:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	979
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	980 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	981 stat ::= <b>break</b>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	982 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	983
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	984 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	985 A <b>break</b> ends the innermost enclosing loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	988 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	989 The <b>return</b> statement is used to return values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	990 from a function or a chunk
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	991 (which is an anonymous function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	993 Functions can return more than one value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	994 so the syntax for the <b>return</b> statement is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	995
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	996 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	997 stat ::= <b>return</b> [explist] [‘<b>;</b>’]
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	998 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	999
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1000
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1001
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1002
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1003 <h4 margin-top="1em"><a name="for">For Statement</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1004
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1005 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1006 The <b>for</b> statement works over functions,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1007 called <i>iterators</i>.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1008 On each iteration, the iterator function is called to produce a new value,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1009 stopping when this new value is <b>nil</b>.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1010 The <b>for</b> loop has the following syntax:
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1011
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1012 <p><tt><pre>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1013 stat ::= <b>for</b> namelist <b>in</b> exp <b>do</b> block <b>end</b>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1014 namelist ::= Name {‘<b>,</b>’ Name}
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1015 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1016
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1017 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1018 A <b>for</b> statement like
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1019
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1020 <p><tt><pre>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1021 for <i>var_1</i>, ···, <i>var_n</i> in <i>exp</i> do <i>block</i> end
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1022 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1023
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1024 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1025 is equivalent to the code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1026
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1027 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1028 do
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1029 local <i>f</i> = <i>exp</i>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1030 while true do
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1031 local <i>var_1</i>, ···, <i>var_n</i> = <i>f</i>()
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1032 if <i>var_1</i> == nil then break end
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1033 <i>block</i>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1034 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1035 end
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1036 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1038 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1039 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1041 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1043 <li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1044 <tt><i>exp</i></tt> is evaluated only once.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1045 Its result is an <i>iterator</i> function.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1046 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1048 <li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1049 <tt><i>f</i></tt> is an invisible variable.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1050 The name is here for explanatory purposes only.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1051 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1053 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1054 You can use <b>break</b> to exit a <b>for</b> loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1055 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1057 <li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1058 The loop variables <tt><i>var_i</i></tt> are local to the loop;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1059 you cannot use their values after the <b>for</b> ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1060 If you need these values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1061 then assign them to other variables before breaking or exiting the loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1062 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1064 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1068
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1069 <h4 margin-top="1em"><a name="fn_stmt">Function Calls as Statements</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1070
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1071 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1072 To allow possible side-effects,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1073 function calls can be executed as statements:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1074
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1075 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1076 stat ::= functioncall
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1077 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1078
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1079 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1080 In this case, all returned values are thrown away.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1081 Function calls are explained in <a href="#3.4.10">§3.4.10</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1084
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1085 <h4 margin-top="1em"><a name="local_stmt">Local Declarations</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1086
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1087 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1088 Local variables can be declared anywhere inside a block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1089 The declaration can include an initial assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1090
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1091 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1092 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist]
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1093 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1094
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1095 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1096 If present, an initial assignment has the same semantics
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1097 of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1098 Otherwise, all variables are initialized with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1101 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1102 A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1103 and so local variables can be declared in a chunk outside any explicit block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1106 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1107 The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1111
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1112 <h3 margin-top="1em"><a name="expressions">Expressions</a></h3>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1113
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1114 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1115 The basic expressions in Luan are the following:
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1116
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1117 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1118 exp ::= prefixexp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1119 exp ::= <b>nil</b> \| <b>false</b> \| <b>true</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1120 exp ::= Numeral
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1121 exp ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1122 exp ::= functiondef
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1123 exp ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1124 exp ::= ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1125 exp ::= exp binop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1126 exp ::= unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1127 prefixexp ::= var \| functioncall \| ‘<b>(</b>’ exp ‘<b>)</b>’
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1128 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1130 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1131 Numerals and literal strings are explained in <a href="#3.1">§3.1</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1132 variables are explained in <a href="#3.2">§3.2</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1133 function definitions are explained in <a href="#3.4.11">§3.4.11</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1134 function calls are explained in <a href="#3.4.10">§3.4.10</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1135 table constructors are explained in <a href="#3.4.9">§3.4.9</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1136 Vararg expressions,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1137 denoted by three dots ('<tt>...</tt>'), can only be used when
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1138 directly inside a vararg function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1139 they are explained in <a href="#3.4.11">§3.4.11</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1143 Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1144 relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1145 and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1146 Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1147 the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1148 and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1152 Both function calls and vararg expressions can result in multiple values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1153 If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1154 then its return list is adjusted to zero elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1155 thus discarding all returned values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1156 If an expression is used as the last (or the only) element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1157 of a list of expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1158 then no adjustment is made
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1159 (unless the expression is enclosed in parentheses).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1160 In all other contexts,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1161 Luan adjusts the result list to one element,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1162 either discarding all values except the first one
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1163 or adding a single <b>nil</b> if there are no values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1166 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1167 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1168
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1169 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1170 f() -- adjusted to 0 results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1171 g(f(), x) -- f() is adjusted to 1 result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1172 g(x, f()) -- g gets x plus all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1173 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1174 a,b = ... -- a gets the first vararg parameter, b gets
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1175 -- the second (both a and b can get nil if there
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1176 -- is no corresponding vararg parameter)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1178 a,b,c = x, f() -- f() is adjusted to 2 results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1179 a,b,c = f() -- f() is adjusted to 3 results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1180 return f() -- returns all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1181 return ... -- returns all received vararg parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1182 return x,y,f() -- returns x, y, and all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1183 {f()} -- creates a list with all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1184 {...} -- creates a list with all vararg parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1185 {f(), nil} -- f() is adjusted to 1 result
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1186 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1188 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1189 Any expression enclosed in parentheses always results in only one value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1190 Thus,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1191 <tt>(f(x,y,z))</tt> is always a single value,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1192 even if <tt>f</tt> returns several values.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1193 (The value of <tt>(f(x,y,z))</tt> is the first value returned by <tt>f</tt>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1194 or <b>nil</b> if <tt>f</tt> does not return any values.)
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1195
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1196
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1197
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1198 <h4 margin-top="1em"><a name="arithmetic">Arithmetic Operators</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1199
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1200 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1201 Luan supports the following arithmetic operators:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1203 <ul>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1204 <li><b><tt>+</tt>: </b>addition</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1205 <li><b><tt>-</tt>: </b>subtraction</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1206 <li><b><tt>*</tt>: </b>multiplication</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1207 <li><b><tt>/</tt>: </b>division</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1208 <li><b><tt>%</tt>: </b>modulo</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1209 <li><b><tt>^</tt>: </b>exponentiation</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1210 <li><b><tt>-</tt>: </b>unary minus</li>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1211 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1213 <p>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1214 Addition, subtraction, multiplication, division, and unary minus are the same as these operators in Java. Exponentiation uses Java's <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Math.html#pow(double,%20double)">Math.pow</a> function.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1216 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1217 Modulo is defined as the remainder of a division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1218 that rounds the quotient towards minus infinite (floor division).
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1219 (The Java modulo operator is not used.)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1222
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1223 <h4 margin-top="1em"><a name="conversions">Coercions and Conversions</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1224
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1225 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1226 Luan provides some automatic conversions between some
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1227 types and representations at run time.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1228 String concatenation converts all of its arguments to strings.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1229
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1230 Luan also converts strings to numbers
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1231 whenever a number is expected.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1233
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1234
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1235
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1236
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1237 <h4 margin-top="1em"><a name="relational">Relational Operators</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1238
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1239 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1240 Luan supports the following relational operators:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1242 <ul>
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1243 <li><b><tt>==</tt>: </b>equality</li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1244 <li><b><tt>~=</tt>: </b>inequality</li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1245 <li><b><tt><</tt>: </b>less than</li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1246 <li><b><tt>></tt>: </b>greater than</li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1247 <li><b><tt><=</tt>: </b>less or equal</li>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1248 <li><b><tt>>=</tt>: </b>greater or equal</li>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1249 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1250 These operators always result in <b>false</b> or <b>true</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1253 <p>
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1254 Equality (<tt>==</tt>) first compares the type of its operands.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1255 If the types are different, then the result is <b>false</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1256 Otherwise, the values of the operands are compared.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1257 Strings, numbers, and binary values are compared in the obvious way (by value).
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1258
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1259 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1260 Tables
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1261 are compared by reference:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1262 two objects are considered equal only if they are the same object.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1263 Every time you create a new table,
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1264 it is different from any previously existing table.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1265 Closures are also compared by reference.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1266
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1267 <p>
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1268 You can change the way that Luan compares tables
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1269 by using the "eq" metamethod (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1270
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1271 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1272 Userdata are Java objects. They are compared for equality with the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object)"><tt>equals</tt></a> method.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1275 Equality comparisons do not convert strings to numbers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1276 or vice versa.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1277 Thus, <tt>"0"==0</tt> evaluates to <b>false</b>,
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1278 and <tt>t[0]</tt> and <tt>t["0"]</tt> denote different
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1279 entries in a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1282 <p>
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1283 The operator <tt>~=</tt> is exactly the negation of equality (<tt>==</tt>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1286 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1287 The order operators work as follows.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1288
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1289 If both arguments are numbers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1290 then they are compared following
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1291 the usual rule for binary operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1292 Otherwise, if both arguments are strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1293 then their values are compared according to the current locale.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1294 Otherwise, Luan tries to call the "lt" or the "le"
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1295 metamethod (see <a href="#2.4">§2.4</a>).
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1296 A comparison <tt>a > b</tt> is translated to <tt>b < a</tt>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1297 and <tt>a >= b</tt> is translated to <tt>b <= a</tt>.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1298
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1299
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1300
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1301
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1302
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1303 <h4 margin-top="1em"><a name="logical_ops">Logical Operators</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1304
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1305 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1306 The logical operators in Luan are
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1307 <b>and</b>, <b>or</b>, and <b>not</b>.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1308 The <b>and</b> and <b>or</b> operators consider both <b>false</b> and <b>nil</b> as false
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1309 and anything else as true.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1310 Like the control structures (see <a href="#3.3.4">§3.3.4</a>),
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1311 the <b>not</b> operator requires a boolean value.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1313 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1314 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1315 The conjunction operator <b>and</b> returns its first argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1316 if this value is <b>false</b> or <b>nil</b>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1317 otherwise, <b>and</b> returns its second argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1318 The disjunction operator <b>or</b> returns its first argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1319 if this value is different from <b>nil</b> and <b>false</b>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1320 otherwise, <b>or</b> returns its second argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1321 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1322 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1323 the second operand is evaluated only if necessary.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1324 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1325
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1326 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1327 10 or 20 --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1328 10 or error() --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1329 nil or "a" --> "a"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1330 nil and 10 --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1331 false and error() --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1332 false and nil --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1333 false or nil --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1334 10 and 20 --> 20
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1335 </pre></tt></p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1336
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1337 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1338 (In this manual,
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1339 <tt>--></tt> indicates the result of the preceding expression.)
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1340
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1341
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1342
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1343 <h4 margin-top="1em"><a name="concatenation">Concatenation</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1344
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1345 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1346 The string concatenation operator in Luan is
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1347 denoted by two dots ('<tt>..</tt>').
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1348 All operands are converted to strings.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1349
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1350
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1351
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1352 <h4 margin-top="1em"><a name="length">The Length Operator</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1353
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1354 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1355 The length operator is denoted by the unary prefix operator <tt>#</tt>.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1356 The length of a string is its number of characters.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1357 The length of a binary is its number of bytes.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1360 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1361 A program can modify the behavior of the length operator for
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1362 any table through the <tt>__len</tt> metamethod (see <a href="#2.4">§2.4</a>).
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1363
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1364
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1365 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1366 Unless a <tt>__len</tt> metamethod is given,
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1367 the length of a table <tt>t</tt> is defined
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1368 as the number of elements in <em>sequence</em>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1369 that is,
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1370 the size of the set of its positive numeric keys is equal to <em>{1..n}</em>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1371 for some non-negative integer <em>n</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1372 In that case, <em>n</em> is its length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1373 Note that a table like
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1374
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1375 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1376 {10, 20, nil, 40}
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1377 </pre></tt></p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1378
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1379 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1380 has a length of <tt>2</tt>, because that is the last key in sequence.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1381
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1382
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1383
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1384
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1385
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1386 <h4 margin-top="1em"><a name="precedence">Precedence</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1387
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1388 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1389 Operator precedence in Luan follows the table below,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1390 from lower to higher priority:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1391
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1392 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1393 or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1394 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1395 < > <= >= ~= ==
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1396 ..
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1397 + -
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1398 * / %
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1399 unary operators (not # -)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1400 ^
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1401 </pre></tt></p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1402
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1403 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1404 As usual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1405 you can use parentheses to change the precedences of an expression.
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1406 The concatenation ('<tt>..</tt>') and exponentiation ('<tt>^</tt>')
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1407 operators are right associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1408 All other binary operators are left associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1413
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1414 <h4 margin-top="1em"><a name="constructors">Table Constructors</a></h4>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1415
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1416 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1417 Table constructors are expressions that create tables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1418 Every time a constructor is evaluated, a new table is created.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1419 A constructor can be used to create an empty table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1420 or to create a table and initialize some of its fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1421 The general syntax for constructors is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1422
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1423 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1424 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1425 fieldlist ::= field {fieldsep field} [fieldsep]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1426 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp \| Name ‘<b>=</b>’ exp \| exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1427 fieldsep ::= ‘<b>,</b>’ \| ‘<b>;</b>’
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1428 </pre></tt></p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1429
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1430 <p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1431 Each field of the form <tt>[exp1] = exp2</tt> adds to the new table an entry
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1432 with key <tt>exp1</tt> and value <tt>exp2</tt>.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1433 A field of the form <tt>name = exp</tt> is equivalent to
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1434 <tt>["name"] = exp</tt>.
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1435 Finally, fields of the form <tt>exp</tt> are equivalent to
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1436 <tt>[i] = exp</tt>, where <tt>i</tt> are consecutive integers
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1437 starting with 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1438 Fields in the other formats do not affect this counting.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1439 For example,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1440
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1441 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1442 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1443 </pre></tt></p>
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1444
ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1445 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1446 is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1447
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1448 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1449 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1450 local t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1451 t[f(1)] = g
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1452 t[1] = "x" -- 1st exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1453 t[2] = "y" -- 2nd exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1454 t.x = 1 -- t["x"] = 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1455 t[3] = f(x) -- 3rd exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1456 t[30] = 23
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1457 t[4] = 45 -- 4th exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1458 a = t
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1459 end
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1460 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1462 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1463 The order of the assignments in a constructor is undefined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1464 (This order would be relevant only when there are repeated keys.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1467 <p>
396 ba8b0aae6453 work on manual; Franklin Schmidt <fschmidt@gmail.com> parents: 395 diff changeset	1468 If the last field in the list has the form <tt>exp</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1469 and the expression is a function call or a vararg expression,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1470 then all values returned by this expression enter the list consecutively
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1471 (see <a href="#3.4.10">§3.4.10</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1474 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1475 The field list can have an optional trailing separator,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1476 as a convenience for machine-generated code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1481
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1482 <h4 margin-top="1em"><a name="fn_calls">Function Calls</a></h4>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1483
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1484 <p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1485 A function call in Luan has the following syntax:
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1486
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1487 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1488 functioncall ::= prefixexp args
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1489 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1490
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1491 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1492 In a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1493 first prefixexp and args are evaluated.
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1494 If the value of prefixexp has type <i>function</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1495 then this function is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1496 with the given arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1497 Otherwise, the prefixexp "call" metamethod is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1498 having as first parameter the value of prefixexp,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1499 followed by the original call arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1500 (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1503 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1504 Arguments have the following syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1505
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1506 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1507 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1508 args ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1509 args ::= LiteralString
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1510 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1511
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1512 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1513 All argument expressions are evaluated before the call.
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1514 A call of the form <tt>f{<i>fields</i>}</tt> is
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1515 syntactic sugar for <tt>f({<i>fields</i>})</tt>;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1516 that is, the argument list is a single new table.
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1517 A call of the form <tt>f'<i>string</i>'</tt>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1518 (or <tt>f"<i>string</i>"</tt> or <tt>f[[<i>string</i>]]</tt>)
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1519 is syntactic sugar for <tt>f('<i>string</i>')</tt>;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1520 that is, the argument list is a single literal string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1523 <p>
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1524 A call of the form <tt>return <i>functioncall</i></tt> is called
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1525 a <i>tail call</i>.
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1526 Luan implements <i>proper tail calls</i>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1527 (or <i>proper tail recursion</i>):
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1528 in a tail call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1529 the called function reuses the stack entry of the calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1530 Therefore, there is no limit on the number of nested tail calls that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1531 a program can execute.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1532 However, a tail call erases any debug information about the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1533 calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1534 Note that a tail call only happens with a particular syntax,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1535 where the <b>return</b> has one single function call as argument;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1536 this syntax makes the calling function return exactly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1537 the returns of the called function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1538 So, none of the following examples are tail calls:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1539
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1540 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1541 return (f(x)) -- results adjusted to 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1542 return 2 * f(x)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1543 return x, f(x) -- additional results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1544 f(x); return -- results discarded
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1545 return x or f(x) -- results adjusted to 1
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1546 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1547
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1548
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1549
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1550
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1551 <h4 margin-top="1em"><a name="fn_def">Function Definitions</a></h4>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1553 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1554 The syntax for function definition is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1555
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1556 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1557 functiondef ::= <b>function</b> funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1558 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b>
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1559 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1561 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1562 The following syntactic sugar simplifies function definitions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1563
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1564 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1565 stat ::= <b>function</b> funcname funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1566 stat ::= <b>local</b> <b>function</b> Name funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1567 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name]
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1568 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1569
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1570 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1571 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1572
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1573 <p><tt><pre>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1574 function f () <i>body</i> end
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1575 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1576
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1577 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1578 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1579
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1580 <p><tt><pre>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1581 f = function () <i>body</i> end
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1582 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1583
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1584 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1585 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1586
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1587 <p><tt><pre>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1588 function t.a.b.c.f () <i>body</i> end
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1589 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1590
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1591 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1592 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1593
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1594 <p><tt><pre>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1595 t.a.b.c.f = function () <i>body</i> end
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1596 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1597
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1598 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1599 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1600
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1601 <p><tt><pre>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1602 local function f () <i>body</i> end
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1603 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1604
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1605 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1606 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1607
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1608 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1609 local f; f = function () <em>body</em> end
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1610 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1611
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1612 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1613 not to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1614
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1615 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1616 local f = function () <em>body</em> end
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1617 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1618
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1619 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1620 (This only makes a difference when the body of the function
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1621 contains references to <tt>f</tt>.)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1624 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1625 A function definition is an executable expression,
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1626 whose value has type <i>function</i>.
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1627 When Luan precompiles a chunk,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1628 all its function bodies are precompiled too.
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1629 Then, whenever Luan executes the function definition,
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1630 the function is <i>instantiated</i> (or <i>closed</i>).
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1631 This function instance (or <i>closure</i>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1632 is the final value of the expression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1635 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1636 Parameters act as local variables that are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1637 initialized with the argument values:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1638
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1639 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1640 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] \| ‘<b>...</b>’
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1641 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1642
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1643 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1644 When a function is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1645 the list of arguments is adjusted to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1646 the length of the list of parameters,
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1647 unless the function is a <i>vararg function</i>,
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1648 which is indicated by three dots ('<tt>...</tt>')
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1649 at the end of its parameter list.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1650 A vararg function does not adjust its argument list;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1651 instead, it collects all extra arguments and supplies them
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1652 to the function through a <i>vararg expression</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1653 which is also written as three dots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1654 The value of this expression is a list of all actual extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1655 similar to a function with multiple results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1656 If a vararg expression is used inside another expression
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1657 or in the middle of a list of expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1658 then its return list is adjusted to one element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1659 If the expression is used as the last element of a list of expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1660 then no adjustment is made
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1661 (unless that last expression is enclosed in parentheses).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1664 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1665 As an example, consider the following definitions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1666
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1667 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1668 function f(a, b) end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1669 function g(a, b, ...) end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1670 function r() return 1,2,3 end
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1671 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1672
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1673 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1674 Then, we have the following mapping from arguments to parameters and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1675 to the vararg expression:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1676
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1677 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1678 CALL PARAMETERS
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1680 f(3) a=3, b=nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1681 f(3, 4) a=3, b=4
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1682 f(3, 4, 5) a=3, b=4
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1683 f(r(), 10) a=1, b=10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1684 f(r()) a=1, b=2
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1686 g(3) a=3, b=nil, ... --> (nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1687 g(3, 4) a=3, b=4, ... --> (nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1688 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1689 g(5, r()) a=5, b=1, ... --> 2 3
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1690 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1692 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1693 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1694 If control reaches the end of a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1695 without encountering a <b>return</b> statement,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1696 then the function returns with no results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1698
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1699
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1700
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1701 <h3 margin-top="1em"><a name="visibility">Visibility Rules</a></h3>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1702
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1703 <p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1704 Luan is a lexically scoped language.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1705 The scope of a local variable begins at the first statement after
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1706 its declaration and lasts until the last non-void statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1707 of the innermost block that includes the declaration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1708 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1709
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1710 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1711 x = 10 -- global variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1712 do -- new block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1713 local x = x -- new 'x', with value 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1714 print(x) --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1715 x = x+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1716 do -- another block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1717 local x = x+1 -- another 'x'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1718 print(x) --> 12
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1719 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1720 print(x) --> 11
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1721 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1722 print(x) --> 10 (the global one)
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1723 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1724
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1725 <p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1726 Notice that, in a declaration like <tt>local x = x</tt>,
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1727 the new <tt>x</tt> being declared is not in scope yet,
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1728 and so the second <tt>x</tt> refers to the outside variable.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1732 Because of the lexical scoping rules,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1733 local variables can be freely accessed by functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1734 defined inside their scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1735 A local variable used by an inner function is called
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1736 an <i>upvalue</i>, or <i>external local variable</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1737 inside the inner function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1740 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1741 Notice that each execution of a <b>local</b> statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1742 defines new local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1743 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1744
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1745 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1746 a = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1747 local x = 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1748 for i=1,10 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1749 local y = 0
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1750 a[i] = function () y=y+1; return x+y end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1751 end
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1752 </pre></tt></p>
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1753
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1754 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1755 The loop creates ten closures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1756 (that is, ten instances of the anonymous function).
417 a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1757 Each of these closures uses a different <tt>y</tt> variable,
a40e99cf0b0b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 396 diff changeset	1758 while all of them share the same <tt>x</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1764 <h1>4 – <a name="4">The Application Program Interface</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1768 This section describes the C API for Lua, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1769 the set of C functions available to the host program to communicate
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1770 with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1771 All API functions and related types and constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1772 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1775 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1776 Even when we use the term "function",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1777 any facility in the API may be provided as a macro instead.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1778 Except where stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1779 all such macros use each of their arguments exactly once
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1780 (except for the first argument, which is always a Lua state),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1781 and so do not generate any hidden side-effects.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1784 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1785 As in most C libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1786 the Lua API functions do not check their arguments for validity or consistency.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1787 However, you can change this behavior by compiling Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1788 with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1792 <h2>4.1 – <a name="4.1">The Stack</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1794 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1795 Lua uses a <em>virtual stack</em> to pass values to and from C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1796 Each element in this stack represents a Lua value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1797 (<b>nil</b>, number, string, etc.).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1800 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1801 Whenever Lua calls C, the called function gets a new stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1802 which is independent of previous stacks and of stacks of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1803 C functions that are still active.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1804 This stack initially contains any arguments to the C function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1805 and it is where the C function pushes its results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1806 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1809 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1810 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1811 most query operations in the API do not follow a strict stack discipline.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1812 Instead, they can refer to any element in the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1813 by using an <em>index</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1814 A positive index represents an absolute stack position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1815 (starting at 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1816 a negative index represents an offset relative to the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1817 More specifically, if the stack has <em>n</em> elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1818 then index 1 represents the first element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1819 (that is, the element that was pushed onto the stack first)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1820 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1821 index <em>n</em> represents the last element;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1822 index -1 also represents the last element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1823 (that is, the element at the top)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1824 and index <em>-n</em> represents the first element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1830 <h2>4.2 – <a name="4.2">Stack Size</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1832 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1833 When you interact with the Lua API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1834 you are responsible for ensuring consistency.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1835 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1836 <em>you are responsible for controlling stack overflow</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1837 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1838 to ensure that the stack has enough space for pushing new elements.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1841 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1842 Whenever Lua calls C,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1843 it ensures that the stack has space for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1844 at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1845 <code>LUA_MINSTACK</code> is defined as 20,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1846 so that usually you do not have to worry about stack space
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1847 unless your code has loops pushing elements onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1850 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1851 When you call a Lua function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1852 without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1853 Lua ensures that the stack has enough space for all results,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1854 but it does not ensure any extra space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1855 So, before pushing anything in the stack after such a call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1856 you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1862 <h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1864 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1865 Any function in the API that receives stack indices
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1866 works only with <em>valid indices</em> or <em>acceptable indices</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1869 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1870 A <em>valid index</em> is an index that refers to a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1871 real position within the stack, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1872 its position lies between 1 and the stack top
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1873 (<code>1 ≤ abs(index) ≤ top</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1875 Usually, functions that can modify the value at an index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1876 require valid indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1879 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1880 Unless otherwise noted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1881 any function that accepts valid indices also accepts <em>pseudo-indices</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1882 which represent some Lua values that are accessible to C code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1883 but which are not in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1884 Pseudo-indices are used to access the registry
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1885 and the upvalues of a C function (see <a href="#4.4">§4.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1888 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1889 Functions that do not need a specific stack position,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1890 but only a value in the stack (e.g., query functions),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1891 can be called with acceptable indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1892 An <em>acceptable index</em> can be any valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1893 including the pseudo-indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1894 but it also can be any positive index after the stack top
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1895 within the space allocated for the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1896 that is, indices up to the stack size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1897 (Note that 0 is never an acceptable index.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1898 Except when noted otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1899 functions in the API work with acceptable indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1902 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1903 Acceptable indices serve to avoid extra tests
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1904 against the stack top when querying the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1905 For instance, a C function can query its third argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1906 without the need to first check whether there is a third argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1907 that is, without the need to check whether 3 is a valid index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1910 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1911 For functions that can be called with acceptable indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1912 any non-valid index is treated as if it
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1913 contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1914 which behaves like a nil value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1920 <h2>4.4 – <a name="4.4">C Closures</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1922 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1923 When a C function is created,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1924 it is possible to associate some values with it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1925 thus creating a <em>C closure</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1926 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1927 these values are called <em>upvalues</em> and are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1928 accessible to the function whenever it is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1931 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1932 Whenever a C function is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1933 its upvalues are located at specific pseudo-indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1934 These pseudo-indices are produced by the macro
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1935 <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1936 The first value associated with a function is at position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1937 <code>lua_upvalueindex(1)</code>, and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1938 Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1939 where <em>n</em> is greater than the number of upvalues of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1940 current function (but not greater than 256),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1941 produces an acceptable but invalid index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1947 <h2>4.5 – <a name="4.5">Registry</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1949 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1950 Lua provides a <em>registry</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1951 a predefined table that can be used by any C code to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1952 store whatever Lua values it needs to store.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1953 The registry table is always located at pseudo-index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1954 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1955 which is a valid index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1956 Any C library can store data into this table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1957 but it must take care to choose keys
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1958 that are different from those used
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1959 by other libraries, to avoid collisions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1960 Typically, you should use as key a string containing your library name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1961 or a light userdata with the address of a C object in your code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1962 or any Lua object created by your code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1963 As with variable names,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1964 string keys starting with an underscore followed by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1965 uppercase letters are reserved for Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1968 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1969 The integer keys in the registry are used
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1970 by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1971 and by some predefined values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1972 Therefore, integer keys must not be used for other purposes.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1975 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1976 When you create a new Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1977 its registry comes with some predefined values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1978 These predefined values are indexed with integer keys
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1979 defined as constants in <code>lua.h</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1980 The following constants are defined:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1982 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1983 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1984 the main thread of the state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1985 (The main thread is the one created together with the state.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1986 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1988 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1989 the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1990 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1991 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1996 <h2>4.6 – <a name="4.6">Error Handling in C</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1998 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1999 Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2000 (Lua will use exceptions if you compile it as C++;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2001 search for <code>LUAI_THROW</code> in the source code for details.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2002 When Lua faces any error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2003 (such as a memory allocation error, type errors, syntax errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2004 and runtime errors)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2005 it <em>raises</em> an error;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2006 that is, it does a long jump.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2007 A <em>protected environment</em> uses <code>setjmp</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2008 to set a recovery point;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2009 any error jumps to the most recent active recovery point.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2012 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2013 If an error happens outside any protected environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2014 Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2015 and then calls <code>abort</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2016 thus exiting the host application.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2017 Your panic function can avoid this exit by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2018 never returning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2019 (e.g., doing a long jump to your own recovery point outside Lua).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2022 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2023 The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2024 in particular, the error message is at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2025 However, there is no guarantee about stack space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2026 To push anything on the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2027 the panic function must first check the available space (see <a href="#4.2">§4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2031 Most functions in the API can raise an error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2032 for instance due to a memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2033 The documentation for each function indicates whether
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2034 it can raise errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2038 Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2044 <h2>4.7 – <a name="4.7">Handling Yields in C</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2046 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2047 Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2048 Therefore, if a C function <code>foo</code> calls an API function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2049 and this API function yields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2050 (directly or indirectly by calling another function that yields),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2051 Lua cannot return to <code>foo</code> any more,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2052 because the <code>longjmp</code> removes its frame from the C stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2056 To avoid this kind of problem,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2057 Lua raises an error whenever it tries to yield across an API call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2058 except for three functions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2059 <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2060 All those functions receive a <em>continuation function</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2061 (as a parameter named <code>k</code>) to continue execution after a yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2065 We need to set some terminology to explain continuations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2066 We have a C function called from Lua which we will call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2067 the <em>original function</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2068 This original function then calls one of those three functions in the C API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2069 which we will call the <em>callee function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2070 that then yields the current thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2071 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2072 or when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2073 and the function called by them yields.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2076 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2077 Suppose the running thread yields while executing the callee function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2078 After the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2079 it eventually will finish running the callee function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2080 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2081 the callee function cannot return to the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2082 because its frame in the C stack was destroyed by the yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2083 Instead, Lua calls a <em>continuation function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2084 which was given as an argument to the callee function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2085 As the name implies,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2086 the continuation function should continue the task
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2087 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2090 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2091 As an illustration, consider the following function:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2093 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2094 int original_function (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2095 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2096 status = lua_pcall(L, n, m, h); /* calls Lua */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2097 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2098 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2099 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2100 Now we want to allow
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2101 the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2102 First, we can rewrite our function like here:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2104 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2105 int k (lua_State *L, int status, lua_KContext ctx) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2106 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2107 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2109 int original_function (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2110 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2111 return k(L, lua_pcall(L, n, m, h), ctx);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2112 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2113 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2114 In the above code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2115 the new function <code>k</code> is a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2116 <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2117 which should do all the work that the original function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2118 was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2119 Now, we must inform Lua that it must call <code>k</code> if the Lua code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2120 being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2121 (errors or yielding),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2122 so we rewrite the code as here,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2123 replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2125 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2126 int original_function (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2127 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2128 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2129 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2130 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2131 Note the external, explicit call to the continuation:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2132 Lua will call the continuation only if needed, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2133 in case of errors or resuming after a yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2134 If the called function returns normally without ever yielding,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2135 <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2136 (Of course, instead of calling the continuation in that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2137 you can do the equivalent work directly inside the original function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2141 Besides the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2142 the continuation function has two other parameters:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2143 the final status of the call plus the context value (<code>ctx</code>) that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2144 was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2145 (Lua does not use this context value;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2146 it only passes this value from the original function to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2147 continuation function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2148 For <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2149 the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2150 except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2151 (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2152 For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2153 the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2154 (For these two functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2155 Lua will not call the continuation in case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2156 because they do not handle errors.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2157 Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2158 you should call the continuation function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2159 with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2160 (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2161 directly the continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2162 because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2165 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2166 Lua treats the continuation function as if it were the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2167 The continuation function receives the same Lua stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2168 from the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2169 in the same state it would be if the callee function had returned.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2170 (For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2171 after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2172 removed from the stack and replaced by the results from the call.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2173 It also has the same upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2174 Whatever it returns is handled by Lua as if it were the return
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2175 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2181 <h2>4.8 – <a name="4.8">Functions and Types</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2184 Here we list all functions and types from the C API in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2185 alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2186 Each function has an indicator like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2187 <span class="apii">[-o, +p, <em>x</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2190 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2191 The first field, <code>o</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2192 is how many elements the function pops from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2193 The second field, <code>p</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2194 is how many elements the function pushes onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2195 (Any function always pushes its results after popping its arguments.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2196 A field in the form <code>x\|y</code> means the function can push (or pop)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2197 <code>x</code> or <code>y</code> elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2198 depending on the situation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2199 an interrogation mark '<code>?</code>' means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2200 we cannot know how many elements the function pops/pushes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2201 by looking only at its arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2202 (e.g., they may depend on what is on the stack).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2203 The third field, <code>x</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2204 tells whether the function may raise errors:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2205 '<code>-</code>' means the function never raises any error;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2206 '<code>e</code>' means the function may raise errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2207 '<code>v</code>' means the function may raise an error on purpose.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2211 <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2212 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2213 <pre>int lua_absindex (lua_State *L, int idx);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2215 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2216 Converts the acceptable index <code>idx</code> into an absolute index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2217 (that is, one that does not depend on the stack top).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2223 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2224 <pre>typedef void * (lua_Alloc) (void ud,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2225 void *ptr,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2226 size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2227 size_t nsize);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2229 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2230 The type of the memory-allocation function used by Lua states.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2231 The allocator function must provide a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2232 functionality similar to <code>realloc</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2233 but not exactly the same.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2234 Its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2235 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2236 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2237 <code>osize</code>, the original size of the block or some code about what
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2238 is being allocated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2239 and <code>nsize</code>, the new size of the block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2242 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2243 When <code>ptr</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2244 <code>osize</code> is the size of the block pointed by <code>ptr</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2245 that is, the size given when it was allocated or reallocated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2248 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2249 When <code>ptr</code> is <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2250 <code>osize</code> encodes the kind of object that Lua is allocating.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2251 <code>osize</code> is any of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2252 <a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2253 <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2254 Lua is creating a new object of that type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2255 When <code>osize</code> is some other value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2256 Lua is allocating memory for something else.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2259 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2260 Lua assumes the following behavior from the allocator function:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2263 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2264 When <code>nsize</code> is zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2265 the allocator must behave like <code>free</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2266 and return <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2269 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2270 When <code>nsize</code> is not zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2271 the allocator must behave like <code>realloc</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2272 The allocator returns <code>NULL</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2273 if and only if it cannot fulfill the request.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2274 Lua assumes that the allocator never fails when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2275 <code>osize >= nsize</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2278 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2279 Here is a simple implementation for the allocator function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2280 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2282 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2283 static void l_alloc (void ud, void *ptr, size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2284 size_t nsize) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2285 (void)ud; (void)osize; /* not used */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2286 if (nsize == 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2287 free(ptr);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2288 return NULL;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2289 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2290 else
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2291 return realloc(ptr, nsize);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2292 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2293 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2294 Note that Standard C ensures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2295 that <code>free(NULL)</code> has no effect and that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2296 <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2297 This code assumes that <code>realloc</code> does not fail when shrinking a block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2298 (Although Standard C does not ensure this behavior,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2299 it seems to be a safe assumption.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2305 <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2306 <span class="apii">[-(2\|1), +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2307 <pre>void lua_arith (lua_State *L, int op);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2309 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2310 Performs an arithmetic or bitwise operation over the two values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2311 (or one, in the case of negations)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2312 at the top of the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2313 with the value at the top being the second operand,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2314 pops these values, and pushes the result of the operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2315 The function follows the semantics of the corresponding Lua operator
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2316 (that is, it may call metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2319 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2320 The value of <code>op</code> must be one of the following constants:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2322 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2324 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2325 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2326 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2327 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2328 <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2329 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2330 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2331 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2332 <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise negation (<code>~</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2333 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2334 <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise or (<code>\|</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2335 <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive or (<code>~</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2336 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2337 <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2339 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2344 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2345 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2346 <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2348 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2349 Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2355 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2356 <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2357 <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2359 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2360 Calls a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2363 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2364 To call a function you must use the following protocol:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2365 first, the function to be called is pushed onto the stack;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2366 then, the arguments to the function are pushed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2367 in direct order;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2368 that is, the first argument is pushed first.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2369 Finally you call <a href="#lua_call"><code>lua_call</code></a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2370 <code>nargs</code> is the number of arguments that you pushed onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2371 All arguments and the function value are popped from the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2372 when the function is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2373 The function results are pushed onto the stack when the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2374 The number of results is adjusted to <code>nresults</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2375 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2376 In this case, all results from the function are pushed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2377 Lua takes care that the returned values fit into the stack space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2378 The function results are pushed onto the stack in direct order
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2379 (the first result is pushed first),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2380 so that after the call the last result is on the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2384 Any error inside the called function is propagated upwards
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2385 (with a <code>longjmp</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2388 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2389 The following example shows how the host program can do the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2390 equivalent to this Lua code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2392 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2393 a = f("how", t.x, 14)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2394 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2395 Here it is in C:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2397 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2398 lua_getglobal(L, "f"); /* function to be called */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2399 lua_pushliteral(L, "how"); /* 1st argument */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2400 lua_getglobal(L, "t"); /* table to be indexed */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2401 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2402 lua_remove(L, -2); /* remove 't' from the stack */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2403 lua_pushinteger(L, 14); /* 3rd argument */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2404 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2405 lua_setglobal(L, "a"); /* set global 'a' */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2406 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2407 Note that the code above is <em>balanced</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2408 at its end, the stack is back to its original configuration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2409 This is considered good programming practice.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2415 <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2416 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2417 <pre>void lua_callk (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2418 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2419 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2420 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2421 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2423 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2424 This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2425 but allows the called function to yield (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2431 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2432 <pre>typedef int (lua_CFunction) (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2434 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2435 Type for C functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2438 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2439 In order to communicate properly with Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2440 a C function must use the following protocol,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2441 which defines the way parameters and results are passed:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2442 a C function receives its arguments from Lua in its stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2443 in direct order (the first argument is pushed first).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2444 So, when the function starts,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2445 <code>lua_gettop(L)</code> returns the number of arguments received by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2446 The first argument (if any) is at index 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2447 and its last argument is at index <code>lua_gettop(L)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2448 To return values to Lua, a C function just pushes them onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2449 in direct order (the first result is pushed first),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2450 and returns the number of results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2451 Any other value in the stack below the results will be properly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2452 discarded by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2453 Like a Lua function, a C function called by Lua can also return
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2454 many results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2457 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2458 As an example, the following function receives a variable number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2459 of numerical arguments and returns their average and their sum:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2461 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2462 static int foo (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2463 int n = lua_gettop(L); /* number of arguments */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2464 lua_Number sum = 0.0;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2465 int i;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2466 for (i = 1; i <= n; i++) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2467 if (!lua_isnumber(L, i)) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2468 lua_pushliteral(L, "incorrect argument");
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2469 lua_error(L);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2470 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2471 sum += lua_tonumber(L, i);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2472 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2473 lua_pushnumber(L, sum/n); /* first result */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2474 lua_pushnumber(L, sum); /* second result */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2475 return 2; /* number of results */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2476 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2477 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2482 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2483 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2484 <pre>int lua_checkstack (lua_State *L, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2486 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2487 Ensures that the stack has space for at least <code>n</code> extra slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2488 It returns false if it cannot fulfill the request,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2489 either because it would cause the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2490 to be larger than a fixed maximum size
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2491 (typically at least several thousand elements) or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2492 because it cannot allocate memory for the extra space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2493 This function never shrinks the stack;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2494 if the stack is already larger than the new size,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2495 it is left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2501 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2502 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2503 <pre>void lua_close (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2506 Destroys all objects in the given Lua state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2507 (calling the corresponding garbage-collection metamethods, if any)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2508 and frees all dynamic memory used by this state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2509 On several platforms, you may not need to call this function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2510 because all resources are naturally released when the host program ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2511 On the other hand, long-running programs that create multiple states,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2512 such as daemons or web servers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2513 will probably need to close states as soon as they are not needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2518
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2519 <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2520 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2521 <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2524 Compares two Lua values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2525 Returns 1 if the value at index <code>index1</code> satisfies <code>op</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2526 when compared with the value at index <code>index2</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2527 following the semantics of the corresponding Lua operator
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2528 (that is, it may call metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2529 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2530 Also returns 0 if any of the indices is not valid.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2533 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2534 The value of <code>op</code> must be one of the following constants:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2536 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2538 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2539 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2540 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2542 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2547 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2548 <span class="apii">[-n, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2549 <pre>void lua_concat (lua_State *L, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2551 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2552 Concatenates the <code>n</code> values at the top of the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2553 pops them, and leaves the result at the top.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2554 If <code>n</code> is 1, the result is the single value on the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2555 (that is, the function does nothing);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2556 if <code>n</code> is 0, the result is the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2557 Concatenation is performed following the usual semantics of Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2558 (see <a href="#3.4.6">§3.4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2564 <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2565 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2566 <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2568 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2569 Copies the element at index <code>fromidx</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2570 into the valid index <code>toidx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2571 replacing the value at that position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2572 Values at other positions are not affected.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2578 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2579 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2580 <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2583 Creates a new empty table and pushes it onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2584 Parameter <code>narr</code> is a hint for how many elements the table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2585 will have as a sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2586 parameter <code>nrec</code> is a hint for how many other elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2587 the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2588 Lua may use these hints to preallocate memory for the new table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2589 This pre-allocation is useful for performance when you know in advance
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2590 how many elements the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2591 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2597 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2598 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2599 <pre>int lua_dump (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2600 lua_Writer writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2601 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2602 int strip);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2604 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2605 Dumps a function as a binary chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2606 Receives a Lua function on the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2607 and produces a binary chunk that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2608 if loaded again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2609 results in a function equivalent to the one dumped.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2610 As it produces parts of the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2611 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2612 with the given <code>data</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2613 to write them.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2616 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2617 If <code>strip</code> is true,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2618 the binary representation is created without debug information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2619 about the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2622 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2623 The value returned is the error code returned by the last
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2624 call to the writer;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2625 0 means no errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2628 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2629 This function does not pop the Lua function from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2635 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2636 <span class="apii">[-1, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2637 <pre>int lua_error (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2639 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2640 Generates a Lua error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2641 using the value at the top of the stack as the error object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2642 This function does a long jump,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2643 and therefore never returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2644 (see <a href="#luaL_error"><code>luaL_error</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2650 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2651 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2652 <pre>int lua_gc (lua_State *L, int what, int data);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2654 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2655 Controls the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2658 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2659 This function performs several tasks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2660 according to the value of the parameter <code>what</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2662 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2664 <li><b><code>LUA_GCSTOP</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2665 stops the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2666 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2668 <li><b><code>LUA_GCRESTART</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2669 restarts the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2670 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2672 <li><b><code>LUA_GCCOLLECT</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2673 performs a full garbage-collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2674 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2676 <li><b><code>LUA_GCCOUNT</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2677 returns the current amount of memory (in Kbytes) in use by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2678 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2680 <li><b><code>LUA_GCCOUNTB</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2681 returns the remainder of dividing the current amount of bytes of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2682 memory in use by Lua by 1024.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2683 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2685 <li><b><code>LUA_GCSTEP</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2686 performs an incremental step of garbage collection.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2687 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2689 <li><b><code>LUA_GCSETPAUSE</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2690 sets <code>data</code> as the new value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2691 for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2692 and returns the previous value of the pause.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2693 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2695 <li><b><code>LUA_GCSETSTEPMUL</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2696 sets <code>data</code> as the new value for the <em>step multiplier</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2697 the collector (see <a href="#2.5">§2.5</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2698 and returns the previous value of the step multiplier.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2699 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2701 <li><b><code>LUA_GCISRUNNING</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2702 returns a boolean that tells whether the collector is running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2703 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2704 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2706 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2708 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2709 For more details about these options,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2710 see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2716 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2717 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2718 <pre>lua_Alloc lua_getallocf (lua_State L, void *ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2720 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2721 Returns the memory-allocation function of a given state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2722 If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2723 opaque pointer given when the memory-allocator function was set.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2729 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2730 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2731 <pre>int lua_getfield (lua_State L, int index, const char k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2733 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2734 Pushes onto the stack the value <code>t[k]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2735 where <code>t</code> is the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2736 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2737 for the "index" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2740 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2741 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2744
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2747 <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2748 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2749 <pre>void lua_getextraspace (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2751 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2752 Returns a pointer to a raw memory area associated with the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2753 given Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2754 The application can use this area for any purpose;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2755 Lua does not use it for anything.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2758 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2759 Each new thread has this area initialized with a copy
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2760 of the area of the main thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2763 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2764 By default, this area has the size of a pointer to void,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2765 but you can recompile Lua with a different size for this area.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2766 (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2772 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2773 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2774 <pre>int lua_getglobal (lua_State L, const char name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2776 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2777 Pushes onto the stack the value of the global <code>name</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2778 Returns the type of that value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2784 <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2785 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2786 <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2788 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2789 Pushes onto the stack the value <code>t[i]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2790 where <code>t</code> is the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2791 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2792 for the "index" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2795 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2796 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2802 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2803 <span class="apii">[-0, +(0\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2804 <pre>int lua_getmetatable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2806 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2807 If the value at the given index has a metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2808 the function pushes that metatable onto the stack and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2809 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2810 the function returns 0 and pushes nothing on the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2816 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2817 <span class="apii">[-1, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2818 <pre>int lua_gettable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2820 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2821 Pushes onto the stack the value <code>t[k]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2822 where <code>t</code> is the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2823 and <code>k</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2826 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2827 This function pops the key from the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2828 pushing the resulting value in its place.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2829 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2830 for the "index" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2833 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2834 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2840 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2841 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2842 <pre>int lua_gettop (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2844 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2845 Returns the index of the top element in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2846 Because indices start at 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2847 this result is equal to the number of elements in the stack;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2848 in particular, 0 means an empty stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2854 <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2855 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2856 <pre>int lua_getuservalue (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2858 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2859 Pushes onto the stack the Lua value associated with the userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2860 at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2863 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2864 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2870 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2871 <span class="apii">[-1, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2872 <pre>void lua_insert (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2874 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2875 Moves the top element into the given valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2876 shifting up the elements above this index to open space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2877 This function cannot be called with a pseudo-index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2878 because a pseudo-index is not an actual stack position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2884 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2885 <pre>typedef ... lua_Integer;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2887 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2888 The type of integers in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2891 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2892 By default this type is <code>long long</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2893 (usually a 64-bit two-complement integer),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2894 but that can be changed to <code>long</code> or <code>int</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2895 (usually a 32-bit two-complement integer).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2896 (See <code>LUA_INT</code> in <code>luaconf.h</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2899 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2900 Lua also defines the constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2901 <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2902 with the minimum and the maximum values that fit in this type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2908 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2909 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2910 <pre>int lua_isboolean (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2912 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2913 Returns 1 if the value at the given index is a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2914 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2920 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2921 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2922 <pre>int lua_iscfunction (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2924 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2925 Returns 1 if the value at the given index is a C function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2926 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2932 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2933 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2934 <pre>int lua_isfunction (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2937 Returns 1 if the value at the given index is a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2938 (either C or Lua), and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2944 <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2945 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2946 <pre>int lua_isinteger (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2948 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2949 Returns 1 if the value at the given index is an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2950 (that is, the value is a number and is represented as an integer),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2951 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2957 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2958 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2959 <pre>int lua_islightuserdata (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2961 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2962 Returns 1 if the value at the given index is a light userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2963 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2969 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2970 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2971 <pre>int lua_isnil (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2973 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2974 Returns 1 if the value at the given index is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2975 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2981 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2982 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2983 <pre>int lua_isnone (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2985 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2986 Returns 1 if the given index is not valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2987 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2993 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2994 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2995 <pre>int lua_isnoneornil (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2997 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2998 Returns 1 if the given index is not valid
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2999 or if the value at this index is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3000 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3006 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3007 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3008 <pre>int lua_isnumber (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3010 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3011 Returns 1 if the value at the given index is a number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3012 or a string convertible to a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3013 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3019 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3020 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3021 <pre>int lua_isstring (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3023 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3024 Returns 1 if the value at the given index is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3025 or a number (which is always convertible to a string),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3026 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3032 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3033 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3034 <pre>int lua_istable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3036 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3037 Returns 1 if the value at the given index is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3038 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3044 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3045 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3046 <pre>int lua_isthread (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3049 Returns 1 if the value at the given index is a thread,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3050 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3056 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3057 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3058 <pre>int lua_isuserdata (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3060 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3061 Returns 1 if the value at the given index is a userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3062 (either full or light), and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3064
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3068 <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3069 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3070 <pre>int lua_isyieldable (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3072 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3073 Returns 1 if the given coroutine can yield,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3074 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3080 <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3081 <pre>typedef ... lua_KContext;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3083 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3084 The type for continuation-function contexts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3085 It must be a numerical type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3086 This type is defined as <code>intptr_t</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3087 when <code>intptr_t</code> is available,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3088 so that it can store pointers too.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3089 Otherwise, it is defined as <code>ptrdiff_t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3095 <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3096 <pre>typedef int (lua_KFunction) (lua_State L, int status, lua_KContext ctx);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3098 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3099 Type for continuation functions (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3105 <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3106 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3107 <pre>void lua_len (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3109 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3110 Returns the length of the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3111 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3112 may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3113 The result is pushed on the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3119 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3120 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3121 <pre>int lua_load (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3122 lua_Reader reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3123 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3124 const char *chunkname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3125 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3127 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3128 Loads a Lua chunk without running it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3129 If there are no errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3130 <code>lua_load</code> pushes the compiled chunk as a Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3131 function on top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3132 Otherwise, it pushes an error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3133
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3135 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3136 The return values of <code>lua_load</code> are:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3138 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3140 <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3142 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3143 syntax error during precompilation;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3145 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3146 memory allocation error;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3148 <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3149 error while running a <code>__gc</code> metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3150 (This error has no relation with the chunk being loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3151 It is generated by the garbage collector.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3152 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3154 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3156 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3157 The <code>lua_load</code> function uses a user-supplied <code>reader</code> function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3158 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3159 The <code>data</code> argument is an opaque value passed to the reader function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3162 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3163 The <code>chunkname</code> argument gives a name to the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3164 which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3168 <code>lua_load</code> automatically detects whether the chunk is text or binary
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3169 and loads it accordingly (see program <code>luac</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3170 The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3171 with the addition that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3172 a <code>NULL</code> value is equivalent to the string "<code>bt</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3175 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3176 <code>lua_load</code> uses the stack internally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3177 so the reader function must always leave the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3178 unmodified when returning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3181 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3182 If the resulting function has upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3183 its first upvalue is set to the value of the global environment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3184 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3185 When loading main chunks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3186 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3187 Other upvalues are initialized with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3193 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3194 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3195 <pre>lua_State lua_newstate (lua_Alloc f, void ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3197 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3198 Creates a new thread running in a new, independent state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3199 Returns <code>NULL</code> if it cannot create the thread or the state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3200 (due to lack of memory).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3201 The argument <code>f</code> is the allocator function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3202 Lua does all memory allocation for this state through this function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3203 The second argument, <code>ud</code>, is an opaque pointer that Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3204 passes to the allocator in every call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3210 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3211 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3212 <pre>void lua_newtable (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3214 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3215 Creates a new empty table and pushes it onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3216 It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3222 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3223 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3224 <pre>lua_State lua_newthread (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3226 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3227 Creates a new thread, pushes it on the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3228 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3229 The new thread returned by this function shares with the original thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3230 its global environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3231 but has an independent execution stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3235 There is no explicit function to close or to destroy a thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3236 Threads are subject to garbage collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3237 like any Lua object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3243 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3244 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3245 <pre>void lua_newuserdata (lua_State L, size_t size);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3247 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3248 This function allocates a new block of memory with the given size,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3249 pushes onto the stack a new full userdata with the block address,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3250 and returns this address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3251 The host program can freely use this memory.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3257 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3258 <span class="apii">[-1, +(2\|0), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3259 <pre>int lua_next (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3261 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3262 Pops a key from the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3263 and pushes a key–value pair from the table at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3264 (the "next" pair after the given key).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3265 If there are no more elements in the table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3266 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3269 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3270 A typical traversal looks like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3272 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3273 /* table is in the stack at index 't' */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3274 lua_pushnil(L); /* first key */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3275 while (lua_next(L, t) != 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3276 /* uses 'key' (at index -2) and 'value' (at index -1) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3277 printf("%s - %s\n",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3278 lua_typename(L, lua_type(L, -2)),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3279 lua_typename(L, lua_type(L, -1)));
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3280 /* removes 'value'; keeps 'key' for next iteration */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3281 lua_pop(L, 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3282 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3283 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3285 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3286 While traversing a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3287 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3288 unless you know that the key is actually a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3289 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3290 the value at the given index;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3291 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3295 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3296 the table during its traversal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3302 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3303 <pre>typedef double lua_Number;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3305 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3306 The type of floats in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3309 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3310 By default this type is double,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3311 but that can be changed to a single float.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3312 (See <code>LUA_REAL</code> in <code>luaconf.h</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3318 <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3319 <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3322 Converts a Lua float to a Lua integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3323 This macro assumes that <code>n</code> has an integral value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3324 If that value is within the range of Lua integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3325 it is converted to an integer and assigned to <code>*p</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3326 The macro results in a boolean indicating whether the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3327 conversion was successful.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3328 (Note that this range test can be tricky to do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3329 correctly without this macro,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3330 due to roundings.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3333 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3334 This macro may evaluate its arguments more than once.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3340 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3341 <span class="apii">[-(nargs + 1), +(nresults\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3342 <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3344 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3345 Calls a function in protected mode.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3348 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3349 Both <code>nargs</code> and <code>nresults</code> have the same meaning as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3350 in <a href="#lua_call"><code>lua_call</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3351 If there are no errors during the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3352 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3353 However, if there is any error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3354 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3355 pushes a single value on the stack (the error message),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3356 and returns an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3357 Like <a href="#lua_call"><code>lua_call</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3358 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3359 and its arguments from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3362 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3363 If <code>msgh</code> is 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3364 then the error message returned on the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3365 is exactly the original error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3366 Otherwise, <code>msgh</code> is the stack index of a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3367 <em>message handler</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3368 (In the current implementation, this index cannot be a pseudo-index.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3369 In case of runtime errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3370 this function will be called with the error message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3371 and its return value will be the message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3372 returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3375 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3376 Typically, the message handler is used to add more debug
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3377 information to the error message, such as a stack traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3378 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3379 since by then the stack has unwound.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3382 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3383 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3384 (defined in <code>lua.h</code>):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3386 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3388 <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3389 success.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3391 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3392 a runtime error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3393 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3395 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3396 memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3397 For such errors, Lua does not call the message handler.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3398 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3400 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3401 error while running the message handler.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3402 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3404 <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3405 error while running a <code>__gc</code> metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3406 (This error typically has no relation with the function being called.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3407 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3409 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3414 <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3415 <span class="apii">[-(nargs + 1), +(nresults\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3416 <pre>int lua_pcallk (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3417 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3418 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3419 int msgh,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3420 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3421 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3423 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3424 This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3425 but allows the called function to yield (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3431 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3432 <span class="apii">[-n, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3433 <pre>void lua_pop (lua_State *L, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3436 Pops <code>n</code> elements from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3442 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3443 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3444 <pre>void lua_pushboolean (lua_State *L, int b);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3446 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3447 Pushes a boolean value with value <code>b</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3453 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3454 <span class="apii">[-n, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3455 <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3457 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3458 Pushes a new C closure onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3461 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3462 When a C function is created,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3463 it is possible to associate some values with it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3464 thus creating a C closure (see <a href="#4.4">§4.4</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3465 these values are then accessible to the function whenever it is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3466 To associate values with a C function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3467 first these values must be pushed onto the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3468 (when there are multiple values, the first value is pushed first).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3469 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3470 is called to create and push the C function onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3471 with the argument <code>n</code> telling how many values will be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3472 associated with the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3473 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3476 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3477 The maximum value for <code>n</code> is 255.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3480 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3481 When <code>n</code> is zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3482 this function creates a <em>light C function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3483 which is just a pointer to the C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3484 In that case, it never raises a memory error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3490 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3491 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3492 <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3494 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3495 Pushes a C function onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3496 This function receives a pointer to a C function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3497 and pushes onto the stack a Lua value of type <code>function</code> that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3498 when called, invokes the corresponding C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3501 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3502 Any function to be registered in Lua must
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3503 follow the correct protocol to receive its parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3504 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3507 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3508 <code>lua_pushcfunction</code> is defined as a macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3510 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3511 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3512 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3513 Note that <code>f</code> is used twice.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3518
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3519 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3520 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3521 <pre>const char lua_pushfstring (lua_State L, const char *fmt, ...);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3524 Pushes onto the stack a formatted string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3525 and returns a pointer to this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3526 It is similar to the ISO C function <code>sprintf</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3527 but has some important differences:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3529 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3531 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3532 You do not have to allocate space for the result:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3533 the result is a Lua string and Lua takes care of memory allocation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3534 (and deallocation, through garbage collection).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3535 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3537 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3538 The conversion specifiers are quite restricted.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3539 There are no flags, widths, or precisions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3540 The conversion specifiers can only be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3541 '<code>%%</code>' (inserts the character '<code>%</code>'),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3542 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3543 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3544 '<code>%L</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3545 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3546 '<code>%d</code>' (inserts an <code>int</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3547 '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3548 '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3549 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3551 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3556 <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3557 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3558 <pre>void lua_pushglobaltable (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3560 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3561 Pushes the global environment onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3567 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3568 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3569 <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3572 Pushes an integer with value <code>n</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3578 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3579 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3580 <pre>void lua_pushlightuserdata (lua_State L, void p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3583 Pushes a light userdata onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3586 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3587 Userdata represent C values in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3588 A <em>light userdata</em> represents a pointer, a <code>void*</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3589 It is a value (like a number):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3590 you do not create it, it has no individual metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3591 and it is not collected (as it was never created).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3592 A light userdata is equal to "any"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3593 light userdata with the same C address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3599 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3600 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3601 <pre>const char lua_pushliteral (lua_State L, const char *s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3603 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3604 This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3605 but can be used only when <code>s</code> is a literal string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3606 It automatically provides the string length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3612 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3613 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3614 <pre>const char lua_pushlstring (lua_State L, const char *s, size_t len);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3616 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3617 Pushes the string pointed to by <code>s</code> with size <code>len</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3618 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3619 Lua makes (or reuses) an internal copy of the given string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3620 so the memory at <code>s</code> can be freed or reused immediately after
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3621 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3622 The string can contain any binary data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3623 including embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3626 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3627 Returns a pointer to the internal copy of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3633 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3634 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3635 <pre>void lua_pushnil (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3637 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3638 Pushes a nil value onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3644 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3645 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3646 <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3649 Pushes a float with value <code>n</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3655 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3656 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3657 <pre>const char lua_pushstring (lua_State L, const char *s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3659 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3660 Pushes the zero-terminated string pointed to by <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3661 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3662 Lua makes (or reuses) an internal copy of the given string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3663 so the memory at <code>s</code> can be freed or reused immediately after
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3664 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3667 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3668 Returns a pointer to the internal copy of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3671 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3672 If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3678 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3679 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3680 <pre>int lua_pushthread (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3682 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3683 Pushes the thread represented by <code>L</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3684 Returns 1 if this thread is the main thread of its state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3690 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3691 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3692 <pre>void lua_pushvalue (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3694 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3695 Pushes a copy of the element at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3696 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3702 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3703 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3704 <pre>const char lua_pushvfstring (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3705 const char *fmt,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3706 va_list argp);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3708 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3709 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3710 instead of a variable number of arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3716 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3717 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3718 <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3720 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3721 Returns 1 if the two values in indices <code>index1</code> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3722 <code>index2</code> are primitively equal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3723 (that is, without calling metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3724 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3725 Also returns 0 if any of the indices are not valid.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3731 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3732 <span class="apii">[-1, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3733 <pre>int lua_rawget (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3735 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3736 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3737 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3743 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3744 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3745 <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3747 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3748 Pushes onto the stack the value <code>t[n]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3749 where <code>t</code> is the table at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3750 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3751 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3755 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3761 <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3762 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3763 <pre>int lua_rawgetp (lua_State L, int index, const void p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3765 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3766 Pushes onto the stack the value <code>t[k]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3767 where <code>t</code> is the table at the given index and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3768 <code>k</code> is the pointer <code>p</code> represented as a light userdata.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3769 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3770 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3773 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3774 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3780 <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3781 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3782 <pre>size_t lua_rawlen (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3784 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3785 Returns the raw "length" of the value at the given index:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3786 for strings, this is the string length;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3787 for tables, this is the result of the length operator ('<code>#</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3788 with no metamethods;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3789 for userdata, this is the size of the block of memory allocated
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3790 for the userdata;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3791 for other values, it is 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3797 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3798 <span class="apii">[-2, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3799 <pre>void lua_rawset (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3801 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3802 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3803 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3809 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3810 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3811 <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3813 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3814 Does the equivalent of <code>t[i] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3815 where <code>t</code> is the table at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3816 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3819 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3820 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3821 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3822 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3828 <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3829 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3830 <pre>void lua_rawsetp (lua_State L, int index, const void p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3832 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3833 Does the equivalent of <code>t[k] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3834 where <code>t</code> is the table at the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3835 <code>k</code> is the pointer <code>p</code> represented as a light userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3836 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3839 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3840 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3841 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3842 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3848 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3849 <pre>typedef const char * (lua_Reader) (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3850 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3851 size_t *size);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3853 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3854 The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3855 Every time it needs another piece of the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3856 <a href="#lua_load"><code>lua_load</code></a> calls the reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3857 passing along its <code>data</code> parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3858 The reader must return a pointer to a block of memory
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3859 with a new piece of the chunk
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3860 and set <code>size</code> to the block size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3861 The block must exist until the reader function is called again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3862 To signal the end of the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3863 the reader must return <code>NULL</code> or set <code>size</code> to zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3864 The reader function may return pieces of any size greater than zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3870 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3871 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3872 <pre>void lua_register (lua_State L, const char name, lua_CFunction f);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3874 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3875 Sets the C function <code>f</code> as the new value of global <code>name</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3876 It is defined as a macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3878 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3879 #define lua_register(L,n,f) \
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3880 (lua_pushcfunction(L, f), lua_setglobal(L, n))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3881 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3886 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3887 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3888 <pre>void lua_remove (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3890 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3891 Removes the element at the given valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3892 shifting down the elements above this index to fill the gap.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3893 This function cannot be called with a pseudo-index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3894 because a pseudo-index is not an actual stack position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3900 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3901 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3902 <pre>void lua_replace (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3904 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3905 Moves the top element into the given valid index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3906 without shifting any element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3907 (therefore replacing the value at the given index),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3908 and then pops the top element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3914 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3915 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3916 <pre>int lua_resume (lua_State L, lua_State from, int nargs);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3918 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3919 Starts and resumes a coroutine in a given thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3922 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3923 To start a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3924 you push onto the thread stack the main function plus any arguments;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3925 then you call <a href="#lua_resume"><code>lua_resume</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3926 with <code>nargs</code> being the number of arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3927 This call returns when the coroutine suspends or finishes its execution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3928 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3929 or all values returned by the body function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3930 <a href="#lua_resume"><code>lua_resume</code></a> returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3931 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3932 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3933 without errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3934 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3937 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3938 In case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3939 the stack is not unwound,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3940 so you can use the debug API over it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3941 The error message is on the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3944 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3945 To resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3946 you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3947 put on its stack only the values to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3948 be passed as results from <code>yield</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3949 and then call <a href="#lua_resume"><code>lua_resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3953 The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3954 If there is no such coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3955 this parameter can be <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3961 <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3962 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3963 <pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3965 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3966 Rotates the stack elements from <code>idx</code> to the top <code>n</code> positions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3967 in the direction of the top, for a positive <code>n</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3968 or <code>-n</code> positions in the direction of the bottom,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3969 for a negative <code>n</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3970 The absolute value of <code>n</code> must not be greater than the size
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3971 of the slice being rotated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3977 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3978 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3979 <pre>void lua_setallocf (lua_State L, lua_Alloc f, void ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3981 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3982 Changes the allocator function of a given state to <code>f</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3983 with user data <code>ud</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3989 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3990 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3991 <pre>void lua_setfield (lua_State L, int index, const char k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3993 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3994 Does the equivalent to <code>t[k] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3995 where <code>t</code> is the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3996 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3999 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4000 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4001 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4002 for the "newindex" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4008 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4009 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4010 <pre>void lua_setglobal (lua_State L, const char name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4012 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4013 Pops a value from the stack and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4014 sets it as the new value of global <code>name</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4020 <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4021 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4022 <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4024 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4025 Does the equivalent to <code>t[n] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4026 where <code>t</code> is the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4027 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4031 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4032 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4033 for the "newindex" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4039 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4040 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4041 <pre>void lua_setmetatable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4044 Pops a table from the stack and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4045 sets it as the new metatable for the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4051 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4052 <span class="apii">[-2, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4053 <pre>void lua_settable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4056 Does the equivalent to <code>t[k] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4057 where <code>t</code> is the value at the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4058 <code>v</code> is the value at the top of the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4059 and <code>k</code> is the value just below the top.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4063 This function pops both the key and the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4064 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4065 for the "newindex" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4071 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4072 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4073 <pre>void lua_settop (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4075 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4076 Accepts any index, or 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4077 and sets the stack top to this index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4078 If the new top is larger than the old one,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4079 then the new elements are filled with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4080 If <code>index</code> is 0, then all stack elements are removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4086 <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4087 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4088 <pre>void lua_setuservalue (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4090 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4091 Pops a value from the stack and sets it as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4092 the new value associated to the userdata at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4098 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4099 <pre>typedef struct lua_State lua_State;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4101 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4102 An opaque structure that points to a thread and indirectly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4103 (through the thread) to the whole state of a Lua interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4104 The Lua library is fully reentrant:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4105 it has no global variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4106 All information about a state is accessible through this structure.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4109 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4110 A pointer to this structure must be passed as the first argument to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4111 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4112 which creates a Lua state from scratch.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4118 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4119 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4120 <pre>int lua_status (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4122 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4123 Returns the status of the thread <code>L</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4126 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4127 The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4128 an error code if the thread finished the execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4129 of a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4130 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4133 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4134 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4135 You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4136 (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4137 (to resume a coroutine).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4143 <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4144 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4145 <pre>size_t lua_stringtonumber (lua_State L, const char s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4147 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4148 Converts the zero-terminated string <code>s</code> to a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4149 pushes that number into the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4150 and returns the total size of the string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4151 that is, its length plus one.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4152 The conversion can result in an integer or a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4153 according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4154 The string may have leading and trailing spaces and a sign.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4155 If the string is not a valid numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4156 returns 0 and pushes nothing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4157 (Note that the result can be used as a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4158 true if the conversion succeeds.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4164 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4165 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4166 <pre>int lua_toboolean (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4168 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4169 Converts the Lua value at the given index to a C boolean
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4170 value (0 or 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4171 Like all tests in Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4172 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4173 different from <b>false</b> and <b>nil</b>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4174 otherwise it returns false.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4175 (If you want to accept only actual boolean values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4176 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4182 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4183 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4184 <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4186 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4187 Converts a value at the given index to a C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4188 That value must be a C function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4189 otherwise, returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4195 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4196 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4197 <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4199 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4200 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4206 <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4207 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4208 <pre>lua_Integer lua_tointegerx (lua_State L, int index, int isnum);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4210 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4211 Converts the Lua value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4212 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4213 The Lua value must be an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4214 or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4215 otherwise, <code>lua_tointegerx</code> returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4218 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4219 If <code>isnum</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4220 its referent is assigned a boolean value that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4221 indicates whether the operation succeeded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4227 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4228 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4229 <pre>const char lua_tolstring (lua_State L, int index, size_t *len);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4231 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4232 Converts the Lua value at the given index to a C string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4233 If <code>len</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4234 it also sets <code>*len</code> with the string length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4235 The Lua value must be a string or a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4236 otherwise, the function returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4237 If the value is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4238 then <code>lua_tolstring</code> also
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4239 <em>changes the actual value in the stack to a string</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4240 (This change confuses <a href="#lua_next"><code>lua_next</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4241 when <code>lua_tolstring</code> is applied to keys during a table traversal.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4244 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4245 <code>lua_tolstring</code> returns a fully aligned pointer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4246 to a string inside the Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4247 This string always has a zero ('<code>\0</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4248 after its last character (as in C),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4249 but can contain other zeros in its body.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4252 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4253 Because Lua has garbage collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4254 there is no guarantee that the pointer returned by <code>lua_tolstring</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4255 will be valid after the corresponding Lua value is removed from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4261 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4262 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4263 <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4265 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4266 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4272 <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4273 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4274 <pre>lua_Number lua_tonumberx (lua_State L, int index, int isnum);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4276 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4277 Converts the Lua value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4278 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4279 The Lua value must be a number or a string convertible to a number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4280 (see <a href="#3.4.3">§3.4.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4281 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4284 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4285 If <code>isnum</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4286 its referent is assigned a boolean value that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4287 indicates whether the operation succeeded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4293 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4294 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4295 <pre>const void lua_topointer (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4297 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4298 Converts the value at the given index to a generic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4299 C pointer (<code>void*</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4300 The value can be a userdata, a table, a thread, or a function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4301 otherwise, <code>lua_topointer</code> returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4302 Different objects will give different pointers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4303 There is no way to convert the pointer back to its original value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4307 Typically this function is used only for debug information.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4313 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4314 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4315 <pre>const char lua_tostring (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4318 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4324 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4325 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4326 <pre>lua_State lua_tothread (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4328 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4329 Converts the value at the given index to a Lua thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4330 (represented as <code>lua_State*</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4331 This value must be a thread;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4332 otherwise, the function returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4338 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4339 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4340 <pre>void lua_touserdata (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4342 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4343 If the value at the given index is a full userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4344 returns its block address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4345 If the value is a light userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4346 returns its pointer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4347 Otherwise, returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4353 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4354 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4355 <pre>int lua_type (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4357 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4358 Returns the type of the value in the given valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4359 or <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4360 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4361 defined in <code>lua.h</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4362 <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4363 <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4364 <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4365 <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4366 <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4367 <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4368 <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4369 <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4370 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4371 <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4377 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4378 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4379 <pre>const char lua_typename (lua_State L, int tp);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4381 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4382 Returns the name of the type encoded by the value <code>tp</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4383 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4389 <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4390 <pre>typedef ... lua_Unsigned;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4392 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4393 The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4399 <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4400 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4401 <pre>int lua_upvalueindex (int i);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4403 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4404 Returns the pseudo-index that represents the <code>i</code>-th upvalue of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4405 the running function (see <a href="#4.4">§4.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4411 <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4412 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4413 <pre>const lua_Number lua_version (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4415 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4416 Returns the address of the version number stored in the Lua core.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4417 When called with a valid <a href="#lua_State"><code>lua_State</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4418 returns the address of the version used to create that state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4419 When called with <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4420 returns the address of the version running the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4426 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4427 <pre>typedef int (lua_Writer) (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4428 const void* p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4429 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4430 void* ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4432 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4433 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4434 Every time it produces another piece of chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4435 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4436 passing along the buffer to be written (<code>p</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4437 its size (<code>sz</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4438 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4441 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4442 The writer returns an error code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4443 0 means no errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4444 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4445 calling the writer again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4451 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4452 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4453 <pre>void lua_xmove (lua_State from, lua_State to, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4456 Exchange values between different threads of the same state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4459 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4460 This function pops <code>n</code> values from the stack <code>from</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4461 and pushes them onto the stack <code>to</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4467 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4468 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4469 <pre>int lua_yield (lua_State *L, int nresults);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4471 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4472 This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4473 but it has no continuation (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4474 Therefore, when the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4475 it continues the function that called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4476 the function calling <code>lua_yield</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4482 <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4483 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4484 <pre>int lua_yieldk (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4485 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4486 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4487 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4489 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4490 Yields a coroutine (thread).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4493 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4494 When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4495 the running coroutine suspends its execution,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4496 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4497 The parameter <code>nresults</code> is the number of values from the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4498 that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4501 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4502 When the coroutine is resumed again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4503 Lua calls the given continuation function <code>k</code> to continue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4504 the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4505 This continuation function receives the same stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4506 from the previous function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4507 with the <code>n</code> results removed and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4508 replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4509 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4510 the continuation function receives the value <code>ctx</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4511 that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4514 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4515 Usually, this function does not return;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4516 when the coroutine eventually resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4517 it continues executing the continuation function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4518 However, there is one special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4519 which is when this function is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4520 from inside a line hook (see <a href="#4.9">§4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4521 In that case, <code>lua_yieldk</code> should be called with no continuation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4522 (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4523 and the hook should return immediately after the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4524 Lua will yield and,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4525 when the coroutine resumes again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4526 it will continue the normal execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4527 of the (Lua) function that triggered the hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4530 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4531 This function can raise an error if it is called from a thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4532 with a pending C call with no continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4533 or it is called from a thread that is not running inside a resume
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4534 (e.g., the main thread).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4542 <h2>4.9 – <a name="4.9">The Debug Interface</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4544 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4545 Lua has no built-in debugging facilities.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4546 Instead, it offers a special interface
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4547 by means of functions and <em>hooks</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4548 This interface allows the construction of different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4549 kinds of debuggers, profilers, and other tools
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4550 that need "inside information" from the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4554 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4555 <pre>typedef struct lua_Debug {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4556 int event;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4557 const char name; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4558 const char namewhat; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4559 const char what; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4560 const char source; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4561 int currentline; /* (l) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4562 int linedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4563 int lastlinedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4564 unsigned char nups; /* (u) number of upvalues */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4565 unsigned char nparams; /* (u) number of parameters */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4566 char isvararg; /* (u) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4567 char istailcall; /* (t) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4568 char short_src[LUA_IDSIZE]; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4569 /* private part */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4570 <em>other fields</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4571 } lua_Debug;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4574 A structure used to carry different pieces of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4575 information about a function or an activation record.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4576 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4577 of this structure, for later use.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4578 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4579 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4583 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4585 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4587 <li><b><code>source</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4588 the name of the chunk that created the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4589 If <code>source</code> starts with a '<code>@</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4590 it means that the function was defined in a file where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4591 the file name follows the '<code>@</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4592 If <code>source</code> starts with a '<code>=</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4593 the remainder of its contents describe the source in a user-dependent manner.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4594 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4595 the function was defined in a string where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4596 <code>source</code> is that string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4597 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4599 <li><b><code>short_src</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4600 a "printable" version of <code>source</code>, to be used in error messages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4601 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4603 <li><b><code>linedefined</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4604 the line number where the definition of the function starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4605 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4607 <li><b><code>lastlinedefined</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4608 the line number where the definition of the function ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4609 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4611 <li><b><code>what</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4612 the string <code>"Lua"</code> if the function is a Lua function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4613 <code>"C"</code> if it is a C function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4614 <code>"main"</code> if it is the main part of a chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4615 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4617 <li><b><code>currentline</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4618 the current line where the given function is executing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4619 When no line information is available,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4620 <code>currentline</code> is set to -1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4621 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4623 <li><b><code>name</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4624 a reasonable name for the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4625 Because functions in Lua are first-class values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4626 they do not have a fixed name:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4627 some functions can be the value of multiple global variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4628 while others can be stored only in a table field.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4629 The <code>lua_getinfo</code> function checks how the function was
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4630 called to find a suitable name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4631 If it cannot find a name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4632 then <code>name</code> is set to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4633 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4635 <li><b><code>namewhat</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4636 explains the <code>name</code> field.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4637 The value of <code>namewhat</code> can be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4638 <code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4639 <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4640 according to how the function was called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4641 (Lua uses the empty string when no other option seems to apply.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4642 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4644 <li><b><code>istailcall</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4645 true if this function invocation was called by a tail call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4646 In this case, the caller of this level is not in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4647 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4649 <li><b><code>nups</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4650 the number of upvalues of the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4651 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4653 <li><b><code>nparams</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4654 the number of fixed parameters of the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4655 (always 0 for C functions).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4656 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4658 <li><b><code>isvararg</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4659 true if the function is a vararg function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4660 (always true for C functions).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4661 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4663 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4668 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4669 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4670 <pre>lua_Hook lua_gethook (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4672 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4673 Returns the current hook function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4679 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4680 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4681 <pre>int lua_gethookcount (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4683 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4684 Returns the current hook count.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4690 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4691 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4692 <pre>int lua_gethookmask (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4694 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4695 Returns the current hook mask.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4701 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4702 <span class="apii">[-(0\|1), +(0\|1\|2), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4703 <pre>int lua_getinfo (lua_State L, const char what, lua_Debug *ar);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4705 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4706 Gets information about a specific function or function invocation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4710 To get information about a function invocation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4711 the parameter <code>ar</code> must be a valid activation record that was
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4712 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4713 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4716 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4717 To get information about a function you push it onto the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4718 and start the <code>what</code> string with the character '<code>></code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4719 (In that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4720 <code>lua_getinfo</code> pops the function from the top of the stack.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4721 For instance, to know in which line a function <code>f</code> was defined,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4722 you can write the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4724 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4725 lua_Debug ar;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4726 lua_getglobal(L, "f"); /* get global 'f' */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4727 lua_getinfo(L, ">S", &ar);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4728 printf("%d\n", ar.linedefined);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4729 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4732 Each character in the string <code>what</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4733 selects some fields of the structure <code>ar</code> to be filled or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4734 a value to be pushed on the stack:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4736 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4738 <li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4739 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4741 <li><b>'<code>S</code>': </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4742 fills in the fields <code>source</code>, <code>short_src</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4743 <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4744 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4746 <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4747 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4749 <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4750 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4752 <li><b>'<code>u</code>': </b> fills in the fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4753 <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4754 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4756 <li><b>'<code>f</code>': </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4757 pushes onto the stack the function that is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4758 running at the given level;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4759 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4761 <li><b>'<code>L</code>': </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4762 pushes onto the stack a table whose indices are the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4763 numbers of the lines that are valid on the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4764 (A <em>valid line</em> is a line with some associated code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4765 that is, a line where you can put a break point.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4766 Non-valid lines include empty lines and comments.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4769 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4770 If this option is given together with option '<code>f</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4771 its table is pushed after the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4772 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4774 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4776 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4777 This function returns 0 on error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4778 (for instance, an invalid option in <code>what</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4784 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4785 <span class="apii">[-0, +(0\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4786 <pre>const char lua_getlocal (lua_State L, const lua_Debug *ar, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4788 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4789 Gets information about a local variable of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4790 a given activation record or a given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4793 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4794 In the first case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4795 the parameter <code>ar</code> must be a valid activation record that was
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4796 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4797 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4798 The index <code>n</code> selects which local variable to inspect;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4799 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4800 and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4804 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4805 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4808 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4809 In the second case, <code>ar</code> must be <code>NULL</code> and the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4810 to be inspected must be at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4811 In this case, only parameters of Lua functions are visible
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4812 (as there is no information about what variables are active)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4813 and no values are pushed onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4817 Returns <code>NULL</code> (and pushes nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4818 when the index is greater than
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4819 the number of active local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4825 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4826 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4827 <pre>int lua_getstack (lua_State L, int level, lua_Debug ar);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4829 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4830 Gets information about the interpreter runtime stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4833 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4834 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4835 an identification of the <em>activation record</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4836 of the function executing at a given level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4837 Level 0 is the current running function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4838 whereas level <em>n+1</em> is the function that has called level <em>n</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4839 (except for tail calls, which do not count on the stack).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4840 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4841 when called with a level greater than the stack depth,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4842 it returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4848 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4849 <span class="apii">[-0, +(0\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4850 <pre>const char lua_getupvalue (lua_State L, int funcindex, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4852 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4853 Gets information about a closure's upvalue.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4854 (For Lua functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4855 upvalues are the external local variables that the function uses,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4856 and that are consequently included in its closure.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4857 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4858 pushes the upvalue's value onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4859 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4860 <code>funcindex</code> points to the closure in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4861 (Upvalues have no particular order,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4862 as they are active through the whole function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4863 So, they are numbered in an arbitrary order.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4867 Returns <code>NULL</code> (and pushes nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4868 when the index is greater than the number of upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4869 For C functions, this function uses the empty string <code>""</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4870 as a name for all upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4876 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4877 <pre>typedef void (lua_Hook) (lua_State L, lua_Debug *ar);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4879 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4880 Type for debugging hook functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4883 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4884 Whenever a hook is called, its <code>ar</code> argument has its field
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4885 <code>event</code> set to the specific event that triggered the hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4886 Lua identifies these events with the following constants:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4887 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4888 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4889 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4890 Moreover, for line events, the field <code>currentline</code> is also set.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4891 To get the value of any other field in <code>ar</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4892 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4895 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4896 For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4897 the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4898 in this case, there will be no corresponding return event.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4901 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4902 While Lua is running a hook, it disables other calls to hooks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4903 Therefore, if a hook calls back Lua to execute a function or a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4904 this execution occurs without any calls to hooks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4907 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4908 Hook functions cannot have continuations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4909 that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4910 <a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4914 Hook functions can yield under the following conditions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4915 Only count and line events can yield
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4916 and they cannot yield any value;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4917 to yield a hook function must finish its execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4918 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4924 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4925 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4926 <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4928 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4929 Sets the debugging hook function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4932 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4933 Argument <code>f</code> is the hook function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4934 <code>mask</code> specifies on which events the hook will be called:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4935 it is formed by a bitwise or of the constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4936 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4937 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4938 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4939 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4940 The <code>count</code> argument is only meaningful when the mask
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4941 includes <code>LUA_MASKCOUNT</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4942 For each event, the hook is called as explained below:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4944 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4946 <li><b>The call hook: </b> is called when the interpreter calls a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4947 The hook is called just after Lua enters the new function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4948 before the function gets its arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4949 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4951 <li><b>The return hook: </b> is called when the interpreter returns from a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4952 The hook is called just before Lua leaves the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4953 There is no standard way to access the values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4954 to be returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4955 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4957 <li><b>The line hook: </b> is called when the interpreter is about to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4958 start the execution of a new line of code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4959 or when it jumps back in the code (even to the same line).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4960 (This event only happens while Lua is executing a Lua function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4961 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4963 <li><b>The count hook: </b> is called after the interpreter executes every
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4964 <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4965 (This event only happens while Lua is executing a Lua function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4966 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4968 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4970 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4971 A hook is disabled by setting <code>mask</code> to zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4977 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4978 <span class="apii">[-(0\|1), +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4979 <pre>const char lua_setlocal (lua_State L, const lua_Debug *ar, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4981 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4982 Sets the value of a local variable of a given activation record.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4983 Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4984 (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4985 <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4986 to the variable and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4987 It also pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4990 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4991 Returns <code>NULL</code> (and pops nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4992 when the index is greater than
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4993 the number of active local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4999 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5000 <span class="apii">[-(0\|1), +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5001 <pre>const char lua_setupvalue (lua_State L, int funcindex, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5003 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5004 Sets the value of a closure's upvalue.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5005 It assigns the value at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5006 to the upvalue and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5007 It also pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5008 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5009 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5012 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5013 Returns <code>NULL</code> (and pops nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5014 when the index is greater than the number of upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5020 <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5021 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5022 <pre>void lua_upvalueid (lua_State L, int funcindex, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5024 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5025 Returns a unique identifier for the upvalue numbered <code>n</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5026 from the closure at index <code>funcindex</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5027 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5028 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5029 (but <code>n</code> cannot be greater than the number of upvalues).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5032 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5033 These unique identifiers allow a program to check whether different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5034 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5035 Lua closures that share an upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5036 (that is, that access a same external local variable)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5037 will return identical ids for those upvalue indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5043 <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5044 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5045 <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5046 int funcindex2, int n2);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5049 Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5050 refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5058 <h1>5 – <a name="5">The Auxiliary Library</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5060 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5062 The <em>auxiliary library</em> provides several convenient functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5063 to interface C with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5064 While the basic API provides the primitive functions for all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5065 interactions between C and Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5066 the auxiliary library provides higher-level functions for some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5067 common tasks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5071 All functions and types from the auxiliary library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5072 are defined in header file <code>lauxlib.h</code> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5073 have a prefix <code>luaL_</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5076 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5077 All functions in the auxiliary library are built on
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5078 top of the basic API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5079 and so they provide nothing that cannot be done with that API.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5080 Nevertheless, the use of the auxiliary library ensures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5081 more consistency to your code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5084 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5085 Several functions in the auxiliary library use internally some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5086 extra stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5087 When a function in the auxiliary library uses less than five slots,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5088 it does not check the stack size;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5089 it simply assumes that there are enough slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5093 Several functions in the auxiliary library are used to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5094 check C function arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5095 Because the error message is formatted for arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5096 (e.g., "<code>bad argument #1</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5097 you should not use these functions for other stack values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5100 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5101 Functions called <code>luaL_check*</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5102 always raise an error if the check is not satisfied.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5106 <h2>5.1 – <a name="5.1">Functions and Types</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5108 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5109 Here we list all functions and types from the auxiliary library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5110 in alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5114 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5115 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5116 <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5118 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5119 Adds the byte <code>c</code> to the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5120 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5126 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5127 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5128 <pre>void luaL_addlstring (luaL_Buffer B, const char s, size_t l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5130 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5131 Adds the string pointed to by <code>s</code> with length <code>l</code> to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5132 the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5133 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5134 The string can contain embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5140 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5141 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5142 <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5144 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5145 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5146 a string of length <code>n</code> previously copied to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5147 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5153 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5154 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5155 <pre>void luaL_addstring (luaL_Buffer B, const char s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5157 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5158 Adds the zero-terminated string pointed to by <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5159 to the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5160 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5166 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5167 <span class="apii">[-1, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5168 <pre>void luaL_addvalue (luaL_Buffer *B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5170 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5171 Adds the value at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5172 to the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5173 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5174 Pops the value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5178 This is the only function on string buffers that can (and must)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5179 be called with an extra element on the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5180 which is the value to be added to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5186 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5187 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5188 <pre>void luaL_argcheck (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5189 int cond,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5190 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5191 const char *extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5193 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5194 Checks whether <code>cond</code> is true.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5195 If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5201 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5202 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5203 <pre>int luaL_argerror (lua_State L, int arg, const char extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5205 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5206 Raises an error reporting a problem with argument <code>arg</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5207 of the C function that called it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5208 using a standard message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5209 that includes <code>extramsg</code> as a comment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5211 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5212 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5213 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5214 This function never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5220 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5221 <pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5223 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5224 Type for a <em>string buffer</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5227 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5228 A string buffer allows C code to build Lua strings piecemeal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5229 Its pattern of use is as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5231 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5233 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5235 <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5237 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5238 Then add string pieces to the buffer calling any of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5239 the <code>luaL_add*</code> functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5240 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5242 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5243 Finish by calling <code>luaL_pushresult(&b)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5244 This call leaves the final string on the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5245 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5247 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5249 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5250 If you know beforehand the total size of the resulting string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5251 you can use the buffer like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5253 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5255 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5257 <li>Then initialize it and preallocate a space of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5258 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5260 <li>Then copy the string into that space.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5262 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5263 Finish by calling <code>luaL_pushresultsize(&b, sz)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5264 where <code>sz</code> is the total size of the resulting string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5265 copied into that space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5266 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5268 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5270 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5271 During its normal operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5272 a string buffer uses a variable number of stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5273 So, while using a buffer, you cannot assume that you know where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5274 the top of the stack is.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5275 You can use the stack between successive calls to buffer operations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5276 as long as that use is balanced;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5277 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5278 when you call a buffer operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5279 the stack is at the same level
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5280 it was immediately after the previous buffer operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5281 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5282 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5283 level when the buffer was initialized,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5284 plus the final string on its top.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5287
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5290 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5291 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5292 <pre>void luaL_buffinit (lua_State L, luaL_Buffer B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5295 Initializes a buffer <code>B</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5296 This function does not allocate any space;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5297 the buffer must be declared as a variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5298 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5304 <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5305 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5306 <pre>char luaL_buffinitsize (lua_State L, luaL_Buffer *B, size_t sz);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5308 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5309 Equivalent to the sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5310 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5316 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5317 <span class="apii">[-0, +(0\|1), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5318 <pre>int luaL_callmeta (lua_State L, int obj, const char e);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5320 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5321 Calls a metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5324 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5325 If the object at index <code>obj</code> has a metatable and this
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5326 metatable has a field <code>e</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5327 this function calls this field passing the object as its only argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5328 In this case this function returns true and pushes onto the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5329 stack the value returned by the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5330 If there is no metatable or no metamethod,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5331 this function returns false (without pushing any value on the stack).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5337 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5338 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5339 <pre>void luaL_checkany (lua_State *L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5342 Checks whether the function has an argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5343 of any type (including <b>nil</b>) at position <code>arg</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5349 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5350 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5351 <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5353 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5354 Checks whether the function argument <code>arg</code> is an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5355 (or can be converted to an integer)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5356 and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5362 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5363 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5364 <pre>const char luaL_checklstring (lua_State L, int arg, size_t *l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5366 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5367 Checks whether the function argument <code>arg</code> is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5368 and returns this string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5369 if <code>l</code> is not <code>NULL</code> fills <code>*l</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5370 with the string's length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5373 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5374 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5375 so all conversions and caveats of that function apply here.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5381 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5382 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5383 <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5385 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5386 Checks whether the function argument <code>arg</code> is a number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5387 and returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5393 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5394 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5395 <pre>int luaL_checkoption (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5396 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5397 const char *def,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5398 const char *const lst[]);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5400 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5401 Checks whether the function argument <code>arg</code> is a string and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5402 searches for this string in the array <code>lst</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5403 (which must be NULL-terminated).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5404 Returns the index in the array where the string was found.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5405 Raises an error if the argument is not a string or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5406 if the string cannot be found.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5409 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5410 If <code>def</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5411 the function uses <code>def</code> as a default value when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5412 there is no argument <code>arg</code> or when this argument is <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5415 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5416 This is a useful function for mapping strings to C enums.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5417 (The usual convention in Lua libraries is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5418 to use strings instead of numbers to select options.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5424 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5425 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5426 <pre>void luaL_checkstack (lua_State L, int sz, const char msg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5428 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5429 Grows the stack size to <code>top + sz</code> elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5430 raising an error if the stack cannot grow to that size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5431 <code>msg</code> is an additional text to go into the error message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5432 (or <code>NULL</code> for no additional text).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5438 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5439 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5440 <pre>const char luaL_checkstring (lua_State L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5442 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5443 Checks whether the function argument <code>arg</code> is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5444 and returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5447 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5448 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5449 so all conversions and caveats of that function apply here.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5455 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5456 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5457 <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5459 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5460 Checks whether the function argument <code>arg</code> has type <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5461 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5467 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5468 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5469 <pre>void luaL_checkudata (lua_State L, int arg, const char *tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5471 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5472 Checks whether the function argument <code>arg</code> is a userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5473 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5474 returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5480 <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5481 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5482 <pre>void luaL_checkversion (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5484 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5485 Checks whether the core running the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5486 the core that created the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5487 and the code making the call are all using the same version of Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5488 Also checks whether the core running the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5489 and the core that created the Lua state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5490 are using the same address space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5496 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5497 <span class="apii">[-0, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5498 <pre>int luaL_dofile (lua_State L, const char filename);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5500 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5501 Loads and runs the given file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5502 It is defined as the following macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5504 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5505 (luaL_loadfile(L, filename) \|\| lua_pcall(L, 0, LUA_MULTRET, 0))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5506 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5507 It returns false if there are no errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5508 or true in case of errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5514 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5515 <span class="apii">[-0, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5516 <pre>int luaL_dostring (lua_State L, const char str);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5518 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5519 Loads and runs the given string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5520 It is defined as the following macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5522 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5523 (luaL_loadstring(L, str) \|\| lua_pcall(L, 0, LUA_MULTRET, 0))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5524 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5525 It returns false if there are no errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5526 or true in case of errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5532 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5533 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5534 <pre>int luaL_error (lua_State L, const char fmt, ...);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5536 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5537 Raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5538 The error message format is given by <code>fmt</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5539 plus any extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5540 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5541 It also adds at the beginning of the message the file name and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5542 the line number where the error occurred,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5543 if this information is available.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5547 This function never returns,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5548 but it is an idiom to use it in C functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5549 as <code>return luaL_error(<em>args</em>)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5555 <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5556 <span class="apii">[-0, +3, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5557 <pre>int luaL_execresult (lua_State *L, int stat);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5560 This function produces the return values for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5561 process-related functions in the standard library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5562 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5568 <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5569 <span class="apii">[-0, +(1\|3), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5570 <pre>int luaL_fileresult (lua_State L, int stat, const char fname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5572 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5573 This function produces the return values for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5574 file-related functions in the standard library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5575 (<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5581 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5582 <span class="apii">[-0, +(0\|1), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5583 <pre>int luaL_getmetafield (lua_State L, int obj, const char e);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5585 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5586 Pushes onto the stack the field <code>e</code> from the metatable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5587 of the object at index <code>obj</code> and returns the type of pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5588 If the object does not have a metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5589 or if the metatable does not have this field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5590 pushes nothing and returns <code>LUA_TNIL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5596 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5597 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5598 <pre>int luaL_getmetatable (lua_State L, const char tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5600 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5601 Pushes onto the stack the metatable associated with name <code>tname</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5602 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5603 If there is no metatable associated with <code>tname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5604 returns false and pushes <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5610 <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5611 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5612 <pre>int luaL_getsubtable (lua_State L, int idx, const char fname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5615 Ensures that the value <code>t[fname]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5616 where <code>t</code> is the value at index <code>idx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5617 is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5618 and pushes that table onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5619 Returns true if it finds a previous table there
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5620 and false if it creates a new table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5626 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5627 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5628 <pre>const char luaL_gsub (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5629 const char *s,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5630 const char *p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5631 const char *r);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5633 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5634 Creates a copy of string <code>s</code> by replacing
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5635 any occurrence of the string <code>p</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5636 with the string <code>r</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5637 Pushes the resulting string on the stack and returns it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5643 <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5644 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5645 <pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5647 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5648 Returns the "length" of the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5649 as a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5650 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5651 Raises an error if the result of the operation is not an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5652 (This case only can happen through metamethods.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5655
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5658 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5659 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5660 <pre>int luaL_loadbuffer (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5661 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5662 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5663 const char *name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5665 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5666 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5672 <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5673 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5674 <pre>int luaL_loadbufferx (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5675 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5676 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5677 const char *name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5678 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5680 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5681 Loads a buffer as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5682 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5683 buffer pointed to by <code>buff</code> with size <code>sz</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5687 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5688 <code>name</code> is the chunk name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5689 used for debug information and error messages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5690 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5696 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5697 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5698 <pre>int luaL_loadfile (lua_State L, const char filename);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5700 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5701 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5707 <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5708 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5709 <pre>int luaL_loadfilex (lua_State L, const char filename,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5710 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5712 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5713 Loads a file as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5714 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5715 named <code>filename</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5716 If <code>filename</code> is <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5717 then it loads from the standard input.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5718 The first line in the file is ignored if it starts with a <code>#</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5721 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5722 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5726 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5727 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5728 if it cannot open/read the file or the file has a wrong mode.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5732 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5733 it does not run it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5739 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5740 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5741 <pre>int luaL_loadstring (lua_State L, const char s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5743 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5744 Loads a string as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5745 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5746 the zero-terminated string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5749 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5750 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5753 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5754 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5755 it does not run it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5761 <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5762 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5763 <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5765 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5766 Creates a new table and registers there
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5767 the functions in list <code>l</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5770 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5771 It is implemented as the following macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5773 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5774 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5775 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5776 The array <code>l</code> must be the actual array,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5777 not a pointer to it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5783 <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5784 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5785 <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5787 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5788 Creates a new table with a size optimized
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5789 to store all entries in the array <code>l</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5790 (but does not actually store them).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5791 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5792 (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5795 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5796 It is implemented as a macro.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5797 The array <code>l</code> must be the actual array,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5798 not a pointer to it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5804 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5805 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5806 <pre>int luaL_newmetatable (lua_State L, const char tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5808 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5809 If the registry already has the key <code>tname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5810 returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5811 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5812 creates a new table to be used as a metatable for userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5813 adds to this new table the pair <code>__name = tname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5814 adds to the registry the pair <code>[tname] = new table</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5815 and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5816 (The entry <code>__name</code> is used by some error-reporting functions.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5819 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5820 In both cases pushes onto the stack the final value associated
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5821 with <code>tname</code> in the registry.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5827 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5828 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5829 <pre>lua_State *luaL_newstate (void);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5831 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5832 Creates a new Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5833 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5834 allocator based on the standard C <code>realloc</code> function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5835 and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5836 an error message to the standard error output in case of fatal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5837 errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5840 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5841 Returns the new state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5842 or <code>NULL</code> if there is a memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5848 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5849 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5850 <pre>void luaL_openlibs (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5852 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5853 Opens all standard Lua libraries into the given state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5859 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5860 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5861 <pre>lua_Integer luaL_optinteger (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5862 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5863 lua_Integer d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5865 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5866 If the function argument <code>arg</code> is an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5867 (or convertible to an integer),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5868 returns this integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5869 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5870 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5871 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5877 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5878 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5879 <pre>const char luaL_optlstring (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5880 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5881 const char *d,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5882 size_t *l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5884 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5885 If the function argument <code>arg</code> is a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5886 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5887 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5888 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5889 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5892 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5893 If <code>l</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5894 fills the position <code>*l</code> with the result's length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5900 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5901 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5902 <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5904 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5905 If the function argument <code>arg</code> is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5906 returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5907 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5908 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5909 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5915 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5916 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5917 <pre>const char luaL_optstring (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5918 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5919 const char *d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5921 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5922 If the function argument <code>arg</code> is a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5923 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5924 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5925 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5926 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5932 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5933 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5934 <pre>char luaL_prepbuffer (luaL_Buffer B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5937 Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5938 with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5944 <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5945 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5946 <pre>char luaL_prepbuffsize (luaL_Buffer B, size_t sz);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5948 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5949 Returns an address to a space of size <code>sz</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5950 where you can copy a string to be added to buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5951 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5952 After copying the string into this space you must call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5953 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5954 it to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5960 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5961 <span class="apii">[-?, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5962 <pre>void luaL_pushresult (luaL_Buffer *B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5965 Finishes the use of buffer <code>B</code> leaving the final string on
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5966 the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5972 <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5973 <span class="apii">[-?, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5974 <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5976 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5977 Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5983 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5984 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5985 <pre>int luaL_ref (lua_State *L, int t);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5987 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5988 Creates and returns a <em>reference</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5989 in the table at index <code>t</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5990 for the object at the top of the stack (and pops the object).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5993 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5994 A reference is a unique integer key.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5995 As long as you do not manually add integer keys into table <code>t</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5996 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5997 You can retrieve an object referred by reference <code>r</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5998 by calling <code>lua_rawgeti(L, t, r)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5999 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6002 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6003 If the object at the top of the stack is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6004 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6005 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6006 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6012 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6013 <pre>typedef struct luaL_Reg {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6014 const char *name;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6015 lua_CFunction func;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6016 } luaL_Reg;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6019 Type for arrays of functions to be registered by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6020 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6021 <code>name</code> is the function name and <code>func</code> is a pointer to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6022 the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6023 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6024 in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6030 <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6031 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6032 <pre>void luaL_requiref (lua_State L, const char modname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6033 lua_CFunction openf, int glb);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6035 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6036 If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6037 calls function <code>openf</code> with string <code>modname</code> as an argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6038 and sets the call result in <code>package.loaded[modname]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6039 as if that function has been called through <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6042 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6043 If <code>glb</code> is true,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6044 also stores the module into global <code>modname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6047 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6048 Leaves a copy of the module on the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6054 <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6055 <span class="apii">[-nup, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6056 <pre>void luaL_setfuncs (lua_State L, const luaL_Reg l, int nup);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6059 Registers all functions in the array <code>l</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6060 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6061 (below optional upvalues, see next).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6065 When <code>nup</code> is not zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6066 all functions are created sharing <code>nup</code> upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6067 which must be previously pushed on the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6068 on top of the library table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6069 These values are popped from the stack after the registration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6075 <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6076 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6077 <pre>void luaL_setmetatable (lua_State L, const char tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6079 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6080 Sets the metatable of the object at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6081 as the metatable associated with name <code>tname</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6082 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6088 <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6089 <pre>typedef struct luaL_Stream {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6090 FILE *f;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6091 lua_CFunction closef;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6092 } luaL_Stream;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6095 The standard representation for file handles,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6096 which is used by the standard I/O library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6099 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6100 A file handle is implemented as a full userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6101 with a metatable called <code>LUA_FILEHANDLE</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6102 (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6103 The metatable is created by the I/O library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6104 (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6107 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6108 This userdata must start with the structure <code>luaL_Stream</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6109 it can contain other data after this initial structure.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6110 Field <code>f</code> points to the corresponding C stream
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6111 (or it can be <code>NULL</code> to indicate an incompletely created handle).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6112 Field <code>closef</code> points to a Lua function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6113 that will be called to close the stream
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6114 when the handle is closed or collected;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6115 this function receives the file handle as its sole argument and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6116 must return either <b>true</b> (in case of success)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6117 or <b>nil</b> plus an error message (in case of error).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6118 Once Lua calls this field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6119 the field value is changed to <code>NULL</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6120 to signal that the handle is closed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6126 <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6127 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6128 <pre>void luaL_testudata (lua_State L, int arg, const char *tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6130 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6131 This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6132 except that, when the test fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6133 it returns <code>NULL</code> instead of raising an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6139 <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6140 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6141 <pre>const char luaL_tolstring (lua_State L, int idx, size_t *len);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6143 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6144 Converts any Lua value at the given index to a C string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6145 in a reasonable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6146 The resulting string is pushed onto the stack and also
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6147 returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6148 If <code>len</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6149 the function also sets <code>*len</code> with the string length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6152 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6153 If the value has a metatable with a <code>"__tostring"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6154 then <code>luaL_tolstring</code> calls the corresponding metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6155 with the value as argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6156 and uses the result of the call as its result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6157
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6162 <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6163 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6164 <pre>void luaL_traceback (lua_State L, lua_State L1, const char *msg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6165 int level);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6168 Creates and pushes a traceback of the stack <code>L1</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6169 If <code>msg</code> is not <code>NULL</code> it is appended
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6170 at the beginning of the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6171 The <code>level</code> parameter tells at which level
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6172 to start the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6178 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6179 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6180 <pre>const char luaL_typename (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6182 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6183 Returns the name of the type of the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6189 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6190 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6191 <pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6193 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6194 Releases reference <code>ref</code> from the table at index <code>t</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6195 (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6196 The entry is removed from the table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6197 so that the referred object can be collected.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6198 The reference <code>ref</code> is also freed to be used again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6201 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6202 If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6203 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6209 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6210 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6211 <pre>void luaL_where (lua_State *L, int lvl);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6213 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6214 Pushes onto the stack a string identifying the current position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6215 of the control at level <code>lvl</code> in the call stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6216 Typically this string has the following format:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6218 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6219 <em>chunkname</em>:<em>currentline</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6220 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6221 Level 0 is the running function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6222 level 1 is the function that called the running function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6223 etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6226 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6227 This function is used to build a prefix for error messages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6235 <h1>6 – <a name="6">Standard Libraries</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6237 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6238 The standard Lua libraries provide useful functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6239 that are implemented directly through the C API.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6240 Some of these functions provide essential services to the language
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6241 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6242 others provide access to "outside" services (e.g., I/O);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6243 and others could be implemented in Lua itself,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6244 but are quite useful or have critical performance requirements that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6245 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6248 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6249 All libraries are implemented through the official C API
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6250 and are provided as separate C modules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6251 Currently, Lua has the following standard libraries:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6253 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6255 <li>basic library (<a href="#6.1">§6.1</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6257 <li>coroutine library (<a href="#6.2">§6.2</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6259 <li>package library (<a href="#6.3">§6.3</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6261 <li>string manipulation (<a href="#6.4">§6.4</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6263 <li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6265 <li>table manipulation (<a href="#6.6">§6.6</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6267 <li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6269 <li>input and output (<a href="#6.8">§6.8</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6271 <li>operating system facilities (<a href="#6.9">§6.9</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6273 <li>debug facilities (<a href="#6.10">§6.10</a>).</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6275 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6276 Except for the basic and the package libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6277 each library provides all its functions as fields of a global table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6278 or as methods of its objects.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6281 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6282 To have access to these libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6283 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6284 which opens all standard libraries.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6285 Alternatively,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6286 the host program can open them individually by using
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6287 <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6288 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6289 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6290 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6291 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6292 <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6293 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6294 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6295 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6296 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6297 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6298 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6302 <h2>6.1 – <a name="6.1">Basic Functions</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6304 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6305 The basic library provides core functions to Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6306 If you do not include this library in your application,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6307 you should check carefully whether you need to provide
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6308 implementations for some of its facilities.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6311 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6312 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6315 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6316 Calls <a href="#pdf-error"><code>error</code></a> if
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6317 the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6318 otherwise, returns all its arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6319 In case of error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6320 <code>message</code> is the error object;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6321 when absent, it defaults to "<code>assertion failed!</code>"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6326 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6327 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6330 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6331 This function is a generic interface to the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6332 It performs different functions according to its first argument, <code>opt</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6334 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6336 <li><b>"<code>collect</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6337 performs a full garbage-collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6338 This is the default option.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6339 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6341 <li><b>"<code>stop</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6342 stops automatic execution of the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6343 The collector will run only when explicitly invoked,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6344 until a call to restart it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6345 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6347 <li><b>"<code>restart</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6348 restarts automatic execution of the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6349 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6351 <li><b>"<code>count</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6352 returns the total memory in use by Lua in Kbytes.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6353 The value has a fractional part,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6354 so that it multiplied by 1024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6355 gives the exact number of bytes in use by Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6356 (except for overflows).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6357 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6359 <li><b>"<code>step</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6360 performs a garbage-collection step.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6361 The step "size" is controlled by <code>arg</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6362 With a zero value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6363 the collector will perform one basic (indivisible) step.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6364 For non-zero values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6365 the collector will perform as if that amount of memory
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6366 (in KBytes) had been allocated by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6367 Returns <b>true</b> if the step finished a collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6368 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6370 <li><b>"<code>setpause</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6371 sets <code>arg</code> as the new value for the <em>pause</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6372 the collector (see <a href="#2.5">§2.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6373 Returns the previous value for <em>pause</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6374 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6376 <li><b>"<code>setstepmul</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6377 sets <code>arg</code> as the new value for the <em>step multiplier</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6378 the collector (see <a href="#2.5">§2.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6379 Returns the previous value for <em>step</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6380 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6382 <li><b>"<code>isrunning</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6383 returns a boolean that tells whether the collector is running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6384 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6385 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6387 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6391 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6392 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6393 Opens the named file and executes its contents as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6394 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6395 <code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6396 Returns all values returned by the chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6397 In case of errors, <code>dofile</code> propagates the error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6398 to its caller (that is, <code>dofile</code> does not run in protected mode).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6403 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6404 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6405 Terminates the last protected function called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6406 and returns <code>message</code> as the error object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6407 Function <code>error</code> never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6410 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6411 Usually, <code>error</code> adds some information about the error position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6412 at the beginning of the message, if the message is a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6413 The <code>level</code> argument specifies how to get the error position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6414 With level 1 (the default), the error position is where the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6415 <code>error</code> function was called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6416 Level 2 points the error to where the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6417 that called <code>error</code> was called; and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6418 Passing a level 0 avoids the addition of error position information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6419 to the message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6424 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6425 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6426 A global variable (not a function) that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6427 holds the global environment (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6428 Lua itself does not use this variable;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6429 changing its value does not affect any environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6430 nor vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6436 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6439 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6440 If <code>object</code> does not have a metatable, returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6441 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6442 if the object's metatable has a <code>"__metatable"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6443 returns the associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6444 Otherwise, returns the metatable of the given object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6449 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6450 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6453 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6454 Returns three values (an iterator function, the table <code>t</code>, and 0)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6455 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6457 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6458 for i,v in ipairs(t) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6459 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6460 will iterate over the key–value pairs
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6461 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6462 up to the first nil value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6467 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6468 <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6471 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6472 Loads a chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6475 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6476 If <code>chunk</code> is a string, the chunk is this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6477 If <code>chunk</code> is a function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6478 <code>load</code> calls it repeatedly to get the chunk pieces.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6479 Each call to <code>chunk</code> must return a string that concatenates
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6480 with previous results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6481 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6484 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6485 If there are no syntactic errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6486 returns the compiled chunk as a function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6487 otherwise, returns <b>nil</b> plus the error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6490 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6491 If the resulting function has upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6492 the first upvalue is set to the value of <code>env</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6493 if that parameter is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6494 or to the value of the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6495 Other upvalues are initialized with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6496 (When you load a main chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6497 the resulting function will always have exactly one upvalue,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6498 the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6499 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6500 when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6501 the resulting function can have an arbitrary number of upvalues.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6502 All upvalues are fresh, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6503 they are not shared with any other function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6506 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6507 <code>chunkname</code> is used as the name of the chunk for error messages
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6508 and debug information (see <a href="#4.9">§4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6509 When absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6510 it defaults to <code>chunk</code>, if <code>chunk</code> is a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6511 or to "<code>=(load)</code>" otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6514 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6515 The string <code>mode</code> controls whether the chunk can be text or binary
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6516 (that is, a precompiled chunk).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6517 It may be the string "<code>b</code>" (only binary chunks),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6518 "<code>t</code>" (only text chunks),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6519 or "<code>bt</code>" (both binary and text).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6520 The default is "<code>bt</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6524 Lua does not check the consistency of binary chunks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6525 Maliciously crafted binary chunks can crash
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6526 the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6531 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6532 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6536 Similar to <a href="#pdf-load"><code>load</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6537 but gets the chunk from file <code>filename</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6538 or from the standard input,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6539 if no file name is given.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6544 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6545 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6548 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6549 Allows a program to traverse all fields of a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6550 Its first argument is a table and its second argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6551 is an index in this table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6552 <code>next</code> returns the next index of the table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6553 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6554 When called with <b>nil</b> as its second argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6555 <code>next</code> returns an initial index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6556 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6557 When called with the last index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6558 or with <b>nil</b> in an empty table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6559 <code>next</code> returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6560 If the second argument is absent, then it is interpreted as <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6561 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6562 you can use <code>next(t)</code> to check whether a table is empty.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6565 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6566 The order in which the indices are enumerated is not specified,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6567 <em>even for numeric indices</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6568 (To traverse a table in numeric order,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6569 use a numerical <b>for</b>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6572 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6573 The behavior of <code>next</code> is undefined if,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6574 during the traversal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6575 you assign any value to a non-existent field in the table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6576 You may however modify existing fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6577 In particular, you may clear existing fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6583 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6586 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6587 If <code>t</code> has a metamethod <code>__pairs</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6588 calls it with <code>t</code> as argument and returns the first three
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6589 results from the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6592 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6593 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6594 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6595 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6597 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6598 for k,v in pairs(t) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6599 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6600 will iterate over all key–value pairs of table <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6603 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6604 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6605 the table during its traversal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6610 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6611 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6615 Calls function <code>f</code> with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6616 the given arguments in <em>protected mode</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6617 This means that any error inside <code>f</code> is not propagated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6618 instead, <code>pcall</code> catches the error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6619 and returns a status code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6620 Its first result is the status code (a boolean),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6621 which is true if the call succeeds without errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6622 In such case, <code>pcall</code> also returns all results from the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6623 after this first result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6624 In case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6629 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6630 <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6631 Receives any number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6632 and prints their values to <code>stdout</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6633 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6634 <code>print</code> is not intended for formatted output,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6635 but only as a quick way to show a value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6636 for instance for debugging.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6637 For complete control over the output,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6638 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6643 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6644 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6645 Checks whether <code>v1</code> is equal to <code>v2</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6646 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6647 Returns a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6653 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6654 Gets the real value of <code>table[index]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6655 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6656 <code>table</code> must be a table;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6657 <code>index</code> may be any value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6662 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6663 <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6664 Returns the length of the object <code>v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6665 which must be a table or a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6666 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6667 Returns an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6672 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6673 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6674 Sets the real value of <code>table[index]</code> to <code>value</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6675 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6676 <code>table</code> must be a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6677 <code>index</code> any value different from <b>nil</b> and NaN,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6678 and <code>value</code> any Lua value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6681 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6682 This function returns <code>table</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6687 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6688 <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6691 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6692 If <code>index</code> is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6693 returns all arguments after argument number <code>index</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6694 a negative number indexes from the end (-1 is the last argument).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6695 Otherwise, <code>index</code> must be the string <code>"#"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6696 and <code>select</code> returns the total number of extra arguments it received.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6701 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6702 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6705 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6706 Sets the metatable for the given table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6707 (You cannot change the metatable of other types from Lua, only from C.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6708 If <code>metatable</code> is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6709 removes the metatable of the given table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6710 If the original metatable has a <code>"__metatable"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6711 raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6714 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6715 This function returns <code>table</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6720 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6721 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6724 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6725 When called with no <code>base</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6726 <code>tonumber</code> tries to convert its argument to a number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6727 If the argument is already a number or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6728 a string convertible to a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6729 then <code>tonumber</code> returns this number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6730 otherwise, it returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6733 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6734 The conversion of strings can result in integers or floats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6735 according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6736 (The string may have leading and trailing spaces and a sign.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6739 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6740 When called with <code>base</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6741 then <code>e</code> must be a string to be interpreted as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6742 an integer numeral in that base.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6743 The base may be any integer between 2 and 36, inclusive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6744 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6745 represents 10, '<code>B</code>' represents 11, and so forth,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6746 with '<code>Z</code>' representing 35.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6747 If the string <code>e</code> is not a valid numeral in the given base,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6748 the function returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6753 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6754 <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6755 Receives a value of any type and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6756 converts it to a string in a human-readable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6757 Floats always produce strings with some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6758 floating-point indication (either a decimal dot or an exponent).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6759 (For complete control of how numbers are converted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6760 use <a href="#pdf-string.format"><code>string.format</code></a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6763 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6764 If the metatable of <code>v</code> has a <code>"__tostring"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6765 then <code>tostring</code> calls the corresponding value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6766 with <code>v</code> as argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6767 and uses the result of the call as its result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6772 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6773 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6774 Returns the type of its only argument, coded as a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6775 The possible results of this function are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6776 "<code>nil</code>" (a string, not the value <b>nil</b>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6777 "<code>number</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6778 "<code>string</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6779 "<code>boolean</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6780 "<code>table</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6781 "<code>function</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6782 "<code>thread</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6783 and "<code>userdata</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6788 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6789 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6790 A global variable (not a function) that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6791 holds a string containing the current interpreter version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6792 The current value of this variable is "<code>Lua 5.3</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6797 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6798 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6801 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6802 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6803 except that it sets a new message handler <code>msgh</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6811 <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6813 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6814 The operations related to coroutines comprise a sub-library of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6815 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6816 See <a href="#2.6">§2.6</a> for a general description of coroutines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6819 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6820 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6823 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6824 Creates a new coroutine, with body <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6825 <code>f</code> must be a Lua function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6826 Returns this new coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6827 an object with type <code>"thread"</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6832 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6833 <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6836 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6837 Returns true when the running coroutine can yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6840 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6841 A running coroutine is yieldable if it is not the main thread and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6842 it is not inside a non-yieldable C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6847 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6848 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6851 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6852 Starts or continues the execution of coroutine <code>co</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6853 The first time you resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6854 it starts running its body.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6855 The values <code>val1</code>, ... are passed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6856 as the arguments to the body function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6857 If the coroutine has yielded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6858 <code>resume</code> restarts it;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6859 the values <code>val1</code>, ... are passed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6860 as the results from the yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6863 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6864 If the coroutine runs without any errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6865 <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6866 (when the coroutine yields) or any values returned by the body function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6867 (when the coroutine terminates).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6868 If there is any error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6869 <code>resume</code> returns <b>false</b> plus the error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6874 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6875 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6878 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6879 Returns the running coroutine plus a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6880 true when the running coroutine is the main one.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6885 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6886 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6890 Returns the status of coroutine <code>co</code>, as a string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6891 <code>"running"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6892 if the coroutine is running (that is, it called <code>status</code>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6893 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6894 or if it has not started running yet;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6895 <code>"normal"</code> if the coroutine is active but not running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6896 (that is, it has resumed another coroutine);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6897 and <code>"dead"</code> if the coroutine has finished its body function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6898 or if it has stopped with an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6903 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6904 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6907 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6908 Creates a new coroutine, with body <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6909 <code>f</code> must be a Lua function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6910 Returns a function that resumes the coroutine each time it is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6911 Any arguments passed to the function behave as the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6912 extra arguments to <code>resume</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6913 Returns the same values returned by <code>resume</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6914 except the first boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6915 In case of error, propagates the error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6920 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6921 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6924 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6925 Suspends the execution of the calling coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6926 Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6934 <h2>6.3 – <a name="6.3">Modules</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6937 The package library provides basic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6938 facilities for loading modules in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6939 It exports one function directly in the global environment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6940 <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6941 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6944 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6945 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6948 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6949 Loads the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6950 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6951 to determine whether <code>modname</code> is already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6952 If it is, then <code>require</code> returns the value stored
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6953 at <code>package.loaded[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6954 Otherwise, it tries to find a <em>loader</em> for the module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6957 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6958 To find a loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6959 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6960 By changing this sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6961 we can change how <code>require</code> looks for a module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6962 The following explanation is based on the default configuration
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6963 for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6966 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6967 First <code>require</code> queries <code>package.preload[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6968 If it has a value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6969 this value (which must be a function) is the loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6970 Otherwise <code>require</code> searches for a Lua loader using the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6971 path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6972 If that also fails, it searches for a C loader using the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6973 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6974 If that also fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6975 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6979 Once a loader is found,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6980 <code>require</code> calls the loader with two arguments:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6981 <code>modname</code> and an extra value dependent on how it got the loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6982 (If the loader came from a file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6983 this extra value is the file name.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6984 If the loader returns any non-nil value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6985 <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6986 If the loader does not return a non-nil value and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6987 has not assigned any value to <code>package.loaded[modname]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6988 then <code>require</code> assigns <b>true</b> to this entry.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6989 In any case, <code>require</code> returns the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6990 final value of <code>package.loaded[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6993 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6994 If there is any error loading or running the module,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6995 or if it cannot find any loader for the module,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6996 then <code>require</code> raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7002 <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7005 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7006 A string describing some compile-time configurations for packages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7007 This string is a sequence of lines:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7009 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7011 <li>The first line is the directory separator string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7012 Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7014 <li>The second line is the character that separates templates in a path.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7015 Default is '<code>;</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7017 <li>The third line is the string that marks the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7018 substitution points in a template.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7019 Default is '<code>?</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7021 <li>The fourth line is a string that, in a path in Windows,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7022 is replaced by the executable's directory.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7023 Default is '<code>!</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7025 <li>The fifth line is a mark to ignore all text after it
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7026 when building the <code>luaopen_</code> function name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7027 Default is '<code>-</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7029 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7033 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7034 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7038 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7041 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7042 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7043 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7044 using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7045 or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7046 or a default path defined in <code>luaconf.h</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7051 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7052 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7056 A table used by <a href="#pdf-require"><code>require</code></a> to control which
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7057 modules are already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7058 When you require a module <code>modname</code> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7059 <code>package.loaded[modname]</code> is not false,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7060 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7063 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7064 This variable is only a reference to the real table;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7065 assignments to this variable do not change the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7066 table used by <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7071 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7072 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7075 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7076 Dynamically links the host program with the C library <code>libname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7079 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7080 If <code>funcname</code> is "<code>*</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7081 then it only links with the library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7082 making the symbols exported by the library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7083 available to other dynamically linked libraries.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7084 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7085 it looks for a function <code>funcname</code> inside the library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7086 and returns this function as a C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7087 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7088 (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7091 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7092 This is a low-level function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7093 It completely bypasses the package and module system.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7094 Unlike <a href="#pdf-require"><code>require</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7095 it does not perform any path searching and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7096 does not automatically adds extensions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7097 <code>libname</code> must be the complete file name of the C library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7098 including if necessary a path and an extension.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7099 <code>funcname</code> must be the exact name exported by the C library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7100 (which may depend on the C compiler and linker used).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7103 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7104 This function is not supported by Standard C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7105 As such, it is only available on some platforms
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7106 (Windows, Linux, Mac OS X, Solaris, BSD,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7107 plus other Unix systems that support the <code>dlfcn</code> standard).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7112 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7113 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7116 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7117 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7120 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7121 At start-up, Lua initializes this variable with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7122 the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7123 the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7124 with a default path defined in <code>luaconf.h</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7125 if those environment variables are not defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7126 Any "<code>;;</code>" in the value of the environment variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7127 is replaced by the default path.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7133 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7136 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7137 A table to store loaders for specific modules
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7138 (see <a href="#pdf-require"><code>require</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7141 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7142 This variable is only a reference to the real table;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7143 assignments to this variable do not change the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7144 table used by <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7149 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7150 <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7153 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7154 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7157 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7158 Each entry in this table is a <em>searcher function</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7159 When looking for a module,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7160 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7161 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7162 sole parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7163 The function can return another function (the module <em>loader</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7164 plus an extra value that will be passed to that loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7165 or a string explaining why it did not find that module
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7166 (or <b>nil</b> if it has nothing to say).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7169 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7170 Lua initializes this table with four searcher functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7173 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7174 The first searcher simply looks for a loader in the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7175 <a href="#pdf-package.preload"><code>package.preload</code></a> table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7178 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7179 The second searcher looks for a loader as a Lua library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7180 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7181 The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7184 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7185 The third searcher looks for a loader as a C library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7186 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7187 Again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7188 the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7189 For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7190 if the C path is the string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7192 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7193 "./?.so;./?.dll;/usr/local/?/init.so"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7194 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7195 the searcher for module <code>foo</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7196 will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7197 and <code>/usr/local/foo/init.so</code>, in that order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7198 Once it finds a C library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7199 this searcher first uses a dynamic link facility to link the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7200 application with the library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7201 Then it tries to find a C function inside the library to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7202 be used as the loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7203 The name of this C function is the string "<code>luaopen_</code>"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7204 concatenated with a copy of the module name where each dot
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7205 is replaced by an underscore.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7206 Moreover, if the module name has a hyphen,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7207 its suffix after (and including) the first hyphen is removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7208 For instance, if the module name is <code>a.b.c-v2.1</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7209 the function name will be <code>luaopen_a_b_c</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7213 The fourth searcher tries an <em>all-in-one loader</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7214 It searches the C path for a library for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7215 the root name of the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7216 For instance, when requiring <code>a.b.c</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7217 it will search for a C library for <code>a</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7218 If found, it looks into it for an open function for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7219 the submodule;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7220 in our example, that would be <code>luaopen_a_b_c</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7221 With this facility, a package can pack several C submodules
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7222 into one single library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7223 with each submodule keeping its original open function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7226 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7227 All searchers except the first one (preload) return as the extra value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7228 the file name where the module was found,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7229 as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7230 The first searcher returns no extra value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7235 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7236 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7239 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7240 Searches for the given <code>name</code> in the given <code>path</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7244 A path is a string containing a sequence of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7245 <em>templates</em> separated by semicolons.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7246 For each template,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7247 the function replaces each interrogation mark (if any)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7248 in the template with a copy of <code>name</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7249 wherein all occurrences of <code>sep</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7250 (a dot, by default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7251 were replaced by <code>rep</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7252 (the system's directory separator, by default),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7253 and then tries to open the resulting file name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7256 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7257 For instance, if the path is the string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7259 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7260 "./?.lua;./?.lc;/usr/local/?/init.lua"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7261 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7262 the search for the name <code>foo.a</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7263 will try to open the files
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7264 <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7265 <code>/usr/local/foo/a/init.lua</code>, in that order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7268 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7269 Returns the resulting name of the first file that it can
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7270 open in read mode (after closing the file),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7271 or <b>nil</b> plus an error message if none succeeds.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7272 (This error message lists all file names it tried to open.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7280 <h2>6.4 – <a name="6.4">String Manipulation</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7282 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7283 This library provides generic functions for string manipulation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7284 such as finding and extracting substrings, and pattern matching.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7285 When indexing a string in Lua, the first character is at position 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7286 (not at 0, as in C).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7287 Indices are allowed to be negative and are interpreted as indexing backwards,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7288 from the end of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7289 Thus, the last character is at position -1, and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7292 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7293 The string library provides all its functions inside the table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7294 <a name="pdf-string"><code>string</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7295 It also sets a metatable for strings
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7296 where the <code>__index</code> field points to the <code>string</code> table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7297 Therefore, you can use the string functions in object-oriented style.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7298 For instance, <code>string.byte(s,i)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7299 can be written as <code>s:byte(i)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7302 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7303 The string library assumes one-byte character encodings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7307 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7308 Returns the internal numerical codes of the characters <code>s[i]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7309 <code>s[i+1]</code>, ..., <code>s[j]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7310 The default value for <code>i</code> is 1;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7311 the default value for <code>j</code> is <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7312 These indices are corrected
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7313 following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7316 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7317 Numerical codes are not necessarily portable across platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7322 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7323 <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7324 Receives zero or more integers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7325 Returns a string with length equal to the number of arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7326 in which each character has the internal numerical code equal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7327 to its corresponding argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7330 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7331 Numerical codes are not necessarily portable across platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7336 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7337 <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7340 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7341 Returns a string containing a binary representation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7342 (a <em>binary chunk</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7343 of the given function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7344 so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7345 a copy of the function (but with new upvalues).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7346 If <code>strip</code> is a true value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7347 the binary representation is created without debug information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7348 about the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7349 (local variable names, lines, etc.).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7352 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7353 Functions with upvalues have only their number of upvalues saved.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7354 When (re)loaded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7355 those upvalues receive fresh instances containing <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7356 (You can use the debug library to serialize
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7357 and reload the upvalues of a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7358 in a way adequate to your needs.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7363 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7364 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7367 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7368 Looks for the first match of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7369 <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7370 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7371 where this occurrence starts and ends;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7372 otherwise, it returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7373 A third, optional numerical argument <code>init</code> specifies
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7374 where to start the search;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7375 its default value is 1 and can be negative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7376 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7377 turns off the pattern matching facilities,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7378 so the function does a plain "find substring" operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7379 with no characters in <code>pattern</code> being considered magic.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7380 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7384 If the pattern has captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7385 then in a successful match
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7386 the captured values are also returned,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7387 after the two indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7392 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7393 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7396 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7397 Returns a formatted version of its variable number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7398 following the description given in its first argument (which must be a string).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7399 The format string follows the same rules as the ISO C function <code>sprintf</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7400 The only differences are that the options/modifiers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7401 <code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7402 and <code>p</code> are not supported
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7403 and that there is an extra option, <code>q</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7404 The <code>q</code> option formats a string between double quotes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7405 using escape sequences when necessary to ensure that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7406 it can safely be read back by the Lua interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7407 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7409 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7410 string.format('%q', 'a string with "quotes" and \n new line')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7411 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7412 may produce the string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7414 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7415 "a string with \"quotes\" and \
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7416 new line"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7417 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7419 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7420 Options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7421 <code>A</code> and <code>a</code> (when available),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7422 <code>E</code>, <code>e</code>, <code>f</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7423 <code>G</code>, and <code>g</code> all expect a number as argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7424 Options <code>c</code>, <code>d</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7425 <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7426 expect an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7427 Option <code>q</code> expects a string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7428 option <code>s</code> expects a string without embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7429 If the argument to option <code>s</code> is not a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7430 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7436 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7437 Returns an iterator function that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7438 each time it is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7439 returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7440 over the string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7441 If <code>pattern</code> specifies no captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7442 then the whole match is produced in each call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7445 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7446 As an example, the following loop
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7447 will iterate over all the words from string <code>s</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7448 printing one per line:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7450 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7451 s = "hello world from Lua"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7452 for w in string.gmatch(s, "%a+") do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7453 print(w)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7454 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7455 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7456 The next example collects all pairs <code>key=value</code> from the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7457 given string into a table:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7459 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7460 t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7461 s = "from=world, to=Lua"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7462 for k, v in string.gmatch(s, "(%w+)=(%w+)") do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7463 t[k] = v
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7464 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7465 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7467 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7468 For this function, a caret '<code>^</code>' at the start of a pattern does not
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7469 work as an anchor, as this would prevent the iteration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7474 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7475 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7476 Returns a copy of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7477 in which all (or the first <code>n</code>, if given)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7478 occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7479 replaced by a replacement string specified by <code>repl</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7480 which can be a string, a table, or a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7481 <code>gsub</code> also returns, as its second value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7482 the total number of matches that occurred.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7483 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7486 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7487 If <code>repl</code> is a string, then its value is used for replacement.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7488 The character <code>%</code> works as an escape character:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7489 any sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7490 with <em>d</em> between 1 and 9,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7491 stands for the value of the <em>d</em>-th captured substring.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7492 The sequence <code>%0</code> stands for the whole match.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7493 The sequence <code>%%</code> stands for a single <code>%</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7496 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7497 If <code>repl</code> is a table, then the table is queried for every match,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7498 using the first capture as the key.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7501 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7502 If <code>repl</code> is a function, then this function is called every time a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7503 match occurs, with all captured substrings passed as arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7504 in order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7507 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7508 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7509 if the pattern specifies no captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7510 then it behaves as if the whole pattern was inside a capture.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7513 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7514 If the value returned by the table query or by the function call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7515 is a string or a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7516 then it is used as the replacement string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7517 otherwise, if it is <b>false</b> or <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7518 then there is no replacement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7519 (that is, the original match is kept in the string).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7522 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7523 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7525 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7526 x = string.gsub("hello world", "(%w+)", "%1 %1")
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7527 --> x="hello hello world world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7529 x = string.gsub("hello world", "%w+", "%0 %0", 1)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7530 --> x="hello hello world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7532 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7533 --> x="world hello Lua from"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7535 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7536 --> x="home = /home/roberto, user = roberto"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7538 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7539 return load(s)()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7540 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7541 --> x="4+5 = 9"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7543 local t = {name="lua", version="5.3"}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7544 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7545 --> x="lua-5.3.tar.gz"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7546 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7551 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7552 Receives a string and returns its length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7553 The empty string <code>""</code> has length 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7554 Embedded zeros are counted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7555 so <code>"a\000bc\000"</code> has length 5.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7560 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7561 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7562 Receives a string and returns a copy of this string with all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7563 uppercase letters changed to lowercase.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7564 All other characters are left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7565 The definition of what an uppercase letter is depends on the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7570 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7571 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7572 Looks for the first <em>match</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7573 <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7574 If it finds one, then <code>match</code> returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7575 the captures from the pattern;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7576 otherwise it returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7577 If <code>pattern</code> specifies no captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7578 then the whole match is returned.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7579 A third, optional numerical argument <code>init</code> specifies
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7580 where to start the search;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7581 its default value is 1 and can be negative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7586 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7587 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7590 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7591 Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7592 packed (that is, serialized in binary form)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7593 according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7598 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7599 <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7602 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7603 Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7604 with the given format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7605 The format string cannot have the variable-length options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7606 '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7611 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7612 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7613 Returns a string that is the concatenation of <code>n</code> copies of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7614 the string <code>s</code> separated by the string <code>sep</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7615 The default value for <code>sep</code> is the empty string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7616 (that is, no separator).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7617 Returns the empty string if <code>n</code> is not positive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7622 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7623 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7624 Returns a string that is the string <code>s</code> reversed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7629 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7630 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7631 Returns the substring of <code>s</code> that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7632 starts at <code>i</code> and continues until <code>j</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7633 <code>i</code> and <code>j</code> can be negative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7634 If <code>j</code> is absent, then it is assumed to be equal to -1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7635 (which is the same as the string length).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7636 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7637 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7638 with length <code>j</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7639 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7640 with length <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7643 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7644 If, after the translation of negative indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7645 <code>i</code> is less than 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7646 it is corrected to 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7647 If <code>j</code> is greater than the string length,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7648 it is corrected to that length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7649 If, after these corrections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7650 <code>i</code> is greater than <code>j</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7651 the function returns the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7655
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7656 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7657 <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7660 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7661 Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7662 according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7663 An optional <code>pos</code> marks where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7664 to start reading in <code>s</code> (default is 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7665 After the read values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7666 this function also returns the index of the first unread byte in <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7671 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7672 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7673 Receives a string and returns a copy of this string with all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7674 lowercase letters changed to uppercase.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7675 All other characters are left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7676 The definition of what a lowercase letter is depends on the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7682 <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7684 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7685 Patterns in Lua are described by regular strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7686 which are interpreted as patterns by the pattern-matching functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7687 <a href="#pdf-string.find"><code>string.find</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7688 <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7689 <a href="#pdf-string.gsub"><code>string.gsub</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7690 and <a href="#pdf-string.match"><code>string.match</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7691 This section describes the syntax and the meaning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7692 (that is, what they match) of these strings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7696 <h4>Character Class:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7697 A <em>character class</em> is used to represent a set of characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7698 The following combinations are allowed in describing a character class:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7700 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7702 <li><b><em>x</em>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7703 (where <em>x</em> is not one of the <em>magic characters</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7704 <code>^$()%.[]*+-?</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7705 represents the character <em>x</em> itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7706 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7708 <li><b><code>.</code>: </b> (a dot) represents all characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7710 <li><b><code>%a</code>: </b> represents all letters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7712 <li><b><code>%c</code>: </b> represents all control characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7714 <li><b><code>%d</code>: </b> represents all digits.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7716 <li><b><code>%g</code>: </b> represents all printable characters except space.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7718 <li><b><code>%l</code>: </b> represents all lowercase letters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7720 <li><b><code>%p</code>: </b> represents all punctuation characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7722 <li><b><code>%s</code>: </b> represents all space characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7724 <li><b><code>%u</code>: </b> represents all uppercase letters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7726 <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7728 <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7730 <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7731 represents the character <em>x</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7732 This is the standard way to escape the magic characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7733 Any non-alphanumeric character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7734 (including all punctuations, even the non-magical)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7735 can be preceded by a '<code>%</code>'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7736 when used to represent itself in a pattern.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7737 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7739 <li><b><code>[<em>set</em>]</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7740 represents the class which is the union of all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7741 characters in <em>set</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7742 A range of characters can be specified by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7743 separating the end characters of the range,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7744 in ascending order, with a '<code>-</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7745 All classes <code>%</code><em>x</em> described above can also be used as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7746 components in <em>set</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7747 All other characters in <em>set</em> represent themselves.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7748 For example, <code>[%w_]</code> (or <code>[_%w]</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7749 represents all alphanumeric characters plus the underscore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7750 <code>[0-7]</code> represents the octal digits,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7751 and <code>[0-7%l%-]</code> represents the octal digits plus
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7752 the lowercase letters plus the '<code>-</code>' character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7755 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7756 The interaction between ranges and classes is not defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7757 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7758 have no meaning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7759 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7761 <li><b><code>[^<em>set</em>]</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7762 represents the complement of <em>set</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7763 where <em>set</em> is interpreted as above.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7764 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7766 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7767 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7768 the corresponding uppercase letter represents the complement of the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7769 For instance, <code>%S</code> represents all non-space characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7772 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7773 The definitions of letter, space, and other character groups
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7774 depend on the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7775 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7781 <h4>Pattern Item:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7782 A <em>pattern item</em> can be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7784 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7786 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7787 a single character class,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7788 which matches any single character in the class;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7789 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7791 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7792 a single character class followed by '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7793 which matches zero or more repetitions of characters in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7794 These repetition items will always match the longest possible sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7795 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7797 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7798 a single character class followed by '<code>+</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7799 which matches one or more repetitions of characters in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7800 These repetition items will always match the longest possible sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7801 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7803 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7804 a single character class followed by '<code>-</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7805 which also matches zero or more repetitions of characters in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7806 Unlike '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7807 these repetition items will always match the shortest possible sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7808 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7810 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7811 a single character class followed by '<code>?</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7812 which matches zero or one occurrence of a character in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7813 It always matches one occurrence if possible;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7814 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7816 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7817 <code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7818 such item matches a substring equal to the <em>n</em>-th captured string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7819 (see below);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7820 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7822 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7823 <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7824 such item matches strings that start with <em>x</em>, end with <em>y</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7825 and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7826 This means that, if one reads the string from left to right,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7827 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7828 the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7829 For instance, the item <code>%b()</code> matches expressions with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7830 balanced parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7831 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7833 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7834 <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7835 such item matches an empty string at any position such that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7836 the next character belongs to <em>set</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7837 and the previous character does not belong to <em>set</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7838 The set <em>set</em> is interpreted as previously described.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7839 The beginning and the end of the subject are handled as if
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7840 they were the character '<code>\0</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7841 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7843 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7848 <h4>Pattern:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7849 A <em>pattern</em> is a sequence of pattern items.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7850 A caret '<code>^</code>' at the beginning of a pattern anchors the match at the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7851 beginning of the subject string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7852 A '<code>$</code>' at the end of a pattern anchors the match at the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7853 end of the subject string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7854 At other positions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7855 '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7861 <h4>Captures:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7862 A pattern can contain sub-patterns enclosed in parentheses;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7863 they describe <em>captures</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7864 When a match succeeds, the substrings of the subject string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7865 that match captures are stored (<em>captured</em>) for future use.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7866 Captures are numbered according to their left parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7867 For instance, in the pattern <code>"(a(.)%w(%s))"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7868 the part of the string matching <code>"a(.)%w(%s)"</code> is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7869 stored as the first capture (and therefore has number 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7870 the character matching "<code>.</code>" is captured with number 2,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7871 and the part matching "<code>%s*</code>" has number 3.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7874 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7875 As a special case, the empty capture <code>()</code> captures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7876 the current string position (a number).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7877 For instance, if we apply the pattern <code>"()aa()"</code> on the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7878 string <code>"flaaap"</code>, there will be two captures: 3 and 5.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7886 <h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7888 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7889 The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7890 <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7891 is a format string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7892 which describes the layout of the structure being created or read.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7895 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7896 A format string is a sequence of conversion options.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7897 The conversion options are as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7899 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7900 <li><b><code><</code>: </b>sets little endian</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7901 <li><b><code>></code>: </b>sets big endian</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7902 <li><b><code>=</code>: </b>sets native endian</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7903 <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7904 (default is native alignment)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7905 <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7906 <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7907 <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7908 <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7909 <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7910 <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7911 <li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7912 <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7913 <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7914 <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7915 (default is native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7916 <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7917 (default is native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7918 <li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7919 <li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7920 <li><b><code>n</code>: </b>a <code>lua_Number</code></li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7921 <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7922 <li><b><code>z</code>: </b>a zero-terminated string</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7923 <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7924 coded as an unsigned integer with <code>n</code> bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7925 (default is a <code>size_t</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7926 <li><b><code>x</code>: </b>one byte of padding</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7927 <li><b><code>X<em>op</em></code>: </b>an empty item that aligns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7928 according to option <code>op</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7929 (which is otherwise ignored)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7930 <li><b>'<code> </code>': </b>(empty space) ignored</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7931 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7932 (A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7933 Except for padding, spaces, and configurations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7934 (options "<code>xX <=>!</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7935 each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7936 or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7939 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7940 For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7941 <code>n</code> can be any integer between 1 and 16.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7942 All integral options check overflows;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7943 <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7944 <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7947 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7948 Any format string starts as if prefixed by "<code>!1=</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7949 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7950 with maximum alignment of 1 (no alignment)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7951 and native endianness.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7955 Alignment works as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7956 For each option,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7957 the format gets extra padding until the data starts
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7958 at an offset that is a multiple of the minimum between the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7959 option size and the maximum alignment;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7960 this minimum must be a power of 2.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7961 Options "<code>c</code>" and "<code>z</code>" are not aligned;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7962 option "<code>s</code>" follows the alignment of its starting integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7965 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7966 All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7967 (and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7975 <h2>6.5 – <a name="6.5">UTF-8 Support</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7977 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7978 This library provides basic support for UTF-8 encoding.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7979 It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7980 This library does not provide any support for Unicode other
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7981 than the handling of the encoding.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7982 Any operation that needs the meaning of a character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7983 such as character classification, is outside its scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7987 Unless stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7988 all functions that expect a byte position as a parameter
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7989 assume that the given position is either the start of a byte sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7990 or one plus the length of the subject string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7991 As in the string library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7992 negative indices count from the end of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7995 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7996 <hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7997 Receives zero or more integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7998 converts each one to its corresponding UTF-8 byte sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7999 and returns a string with the concatenation of all these sequences.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8005 <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8006 The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8007 (see <a href="#6.4.1">§6.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8008 which matches exactly one UTF-8 byte sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8009 assuming that the subject is a valid UTF-8 string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8014 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8015 <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8019 Returns values so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8021 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8022 for p, c in utf8.codes(s) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8023 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8024 will iterate over all characters in string <code>s</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8025 with <code>p</code> being the position (in bytes) and <code>c</code> the code point
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8026 of each character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8027 It raises an error if it meets any invalid byte sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8032 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8033 <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8034 Returns the codepoints (as integers) from all characters in <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8035 that start between byte position <code>i</code> and <code>j</code> (both included).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8036 The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8037 It raises an error if it meets any invalid byte sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8042 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8043 <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8044 Returns the number of UTF-8 characters in string <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8045 that start between positions <code>i</code> and <code>j</code> (both inclusive).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8046 The default for <code>i</code> is 1 and for <code>j</code> is -1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8047 If it finds any invalid byte sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8048 returns a false value plus the position of the first invalid byte.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8053 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8054 <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8055 Returns the position (in bytes) where the encoding of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8056 <code>n</code>-th character of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8057 (counting from position <code>i</code>) starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8058 A negative <code>n</code> gets characters before position <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8059 The default for <code>i</code> is 1 when <code>n</code> is non-negative
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8060 and <code>#s + 1</code> otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8061 so that <code>utf8.offset(s, -n)</code> gets the offset of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8062 <code>n</code>-th character from the end of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8063 If the specified character is neither in the subject
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8064 nor right after its end,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8065 the function returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8068 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8069 As a special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8070 when <code>n</code> is 0 the function returns the start of the encoding
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8071 of the character that contains the <code>i</code>-th byte of <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8075 This function assumes that <code>s</code> is a valid UTF-8 string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8083 <h2>6.6 – <a name="6.6">Table Manipulation</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8085 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8086 This library provides generic functions for table manipulation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8087 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8090 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8091 Remember that, whenever an operation needs the length of a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8092 the table must be a proper sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8093 or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8094 All functions ignore non-numeric keys
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8095 in the tables given as arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8098 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8099 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8102 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8103 Given a list where all elements are strings or numbers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8104 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8105 The default value for <code>sep</code> is the empty string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8106 the default for <code>i</code> is 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8107 and the default for <code>j</code> is <code>#list</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8108 If <code>i</code> is greater than <code>j</code>, returns the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8113 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8114 <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8117 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8118 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8119 shifting up the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8120 <code>list[pos], list[pos+1], ···, list[#list]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8121 The default value for <code>pos</code> is <code>#list+1</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8122 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8123 of list <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8128 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8129 <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8133 Moves elements from table <code>a1</code> to table <code>a2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8134 This function performs the equivalent to the following
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8135 multiple assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8136 <code>a2[t],··· = a1[f],···,a1[e]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8137 The default for <code>a2</code> is <code>a1</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8138 The destination range can overlap with the source range.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8139 Index <code>f</code> must be positive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8144 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8145 <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8148 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8149 Returns a new table with all parameters stored into keys 1, 2, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8150 and with a field "<code>n</code>" with the total number of parameters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8151 Note that the resulting table may not be a sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8156 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8157 <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8160 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8161 Removes from <code>list</code> the element at position <code>pos</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8162 returning the value of the removed element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8163 When <code>pos</code> is an integer between 1 and <code>#list</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8164 it shifts down the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8165 <code>list[pos+1], list[pos+2], ···, list[#list]</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8166 and erases element <code>list[#list]</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8167 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8168 or <code>#list + 1</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8169 in those cases, the function erases the element <code>list[pos]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8172 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8173 The default value for <code>pos</code> is <code>#list</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8174 so that a call <code>table.remove(l)</code> removes the last element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8175 of list <code>l</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8180 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8181 <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8184 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8185 Sorts list elements in a given order, <em>in-place</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8186 from <code>list[1]</code> to <code>list[#list]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8187 If <code>comp</code> is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8188 then it must be a function that receives two list elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8189 and returns true when the first element must come
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8190 before the second in the final order
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8191 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8192 If <code>comp</code> is not given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8193 then the standard Lua operator <code><</code> is used instead.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8196 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8197 The sort algorithm is not stable;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8198 that is, elements considered equal by the given order
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8199 may have their relative positions changed by the sort.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8204 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8205 <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8208 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8209 Returns the elements from the given list.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8210 This function is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8212 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8213 return list[i], list[i+1], ···, list[j]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8214 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8215 By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8223 <h2>6.7 – <a name="6.7">Mathematical Functions</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8225 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8226 This library provides basic mathematical functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8227 It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8228 Functions with the annotation "<code>integer/float</code>" give
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8229 integer results for integer arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8230 and float results for float (or mixed) arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8231 Rounding functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8232 (<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8233 return an integer when the result fits in the range of an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8234 or a float otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8235
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8237 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8238 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8242 Returns the absolute value of <code>x</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8247 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8248 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8252 Returns the arc cosine of <code>x</code> (in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8257 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8258 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8261 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8262 Returns the arc sine of <code>x</code> (in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8267 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8268 <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8271 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8273 Returns the arc tangent of <code>y/x</code> (in radians),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8274 but uses the signs of both parameters to find the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8275 quadrant of the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8276 (It also handles correctly the case of <code>x</code> being zero.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8279 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8280 The default value for <code>x</code> is 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8281 so that the call <code>math.atan(y)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8282 returns the arc tangent of <code>y</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8287 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8288 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8291 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8292 Returns the smallest integral value larger than or equal to <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8297 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8298 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8302 Returns the cosine of <code>x</code> (assumed to be in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8307 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8308 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8311 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8312 Converts the angle <code>x</code> from radians to degrees.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8318 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8322 Returns the value <em>e<sup>x</sup></em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8323 (where <code>e</code> is the base of natural logarithms).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8328 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8329 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8333 Returns the largest integral value smaller than or equal to <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8338 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8339 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8342 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8343 Returns the remainder of the division of <code>x</code> by <code>y</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8344 that rounds the quotient towards zero. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8349 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8350 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8353 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8354 The float value <code>HUGE_VAL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8355 a value larger than any other numerical value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8360 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8361 <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8364 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8365 Returns the logarithm of <code>x</code> in the given base.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8366 The default for <code>base</code> is <em>e</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8367 (so that the function returns the natural logarithm of <code>x</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8372 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8373 <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8376 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8377 Returns the argument with the maximum value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8378 according to the Lua operator <code><</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8384 <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8385 An integer with the maximum value for an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8390 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8391 <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8394 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8395 Returns the argument with the minimum value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8396 according to the Lua operator <code><</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8402 <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8403 An integer with the minimum value for an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8408 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8409 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8412 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8413 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8414 Its second result is always a float.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8417
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8419 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8420 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8423 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8424 The value of <em>π</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8429 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8430 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8433 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8434 Converts the angle <code>x</code> from degrees to radians.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8439 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8440 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8444 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8445 returns a pseudo-random float with uniform distribution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8446 in the range <em>[0,1)</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8447 When called with two integers <code>m</code> and <code>n</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8448 <code>math.random</code> returns a pseudo-random integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8449 with uniform distribution in the range <em>[m, n]</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8450 (The value <em>m-n</em> cannot be negative and must fit in a Lua integer.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8451 The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8454 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8455 This function is an interface to the underling
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8456 pseudo-random generator function provided by C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8457 No guarantees can be given for its statistical properties.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8462 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8463 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8466 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8467 Sets <code>x</code> as the "seed"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8468 for the pseudo-random generator:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8469 equal seeds produce equal sequences of numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8474 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8475 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8478 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8479 Returns the sine of <code>x</code> (assumed to be in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8484 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8485 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8488 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8489 Returns the square root of <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8490 (You can also use the expression <code>x^0.5</code> to compute this value.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8495 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8496 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8499 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8500 Returns the tangent of <code>x</code> (assumed to be in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8506 <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8509 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8510 If the value <code>x</code> is convertible to an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8511 returns that integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8512 Otherwise, returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8517 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8518 <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8521 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8522 Returns "<code>integer</code>" if <code>x</code> is an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8523 "<code>float</code>" if it is a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8524 or <b>nil</b> if <code>x</code> is not a number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8529 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8530 <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8533 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8534 Returns a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8535 true if integer <code>m</code> is below integer <code>n</code> when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8536 they are compared as unsigned integers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8544 <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8547 The I/O library provides two different styles for file manipulation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8548 The first one uses implicit file handles;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8549 that is, there are operations to set a default input file and a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8550 default output file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8551 and all input/output operations are over these default files.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8552 The second style uses explicit file handles.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8555 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8556 When using implicit file handles,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8557 all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8558 When using explicit file handles,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8559 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8560 and then all operations are supplied as methods of the file handle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8563 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8564 The table <code>io</code> also provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8565 three predefined file handles with their usual meanings from C:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8566 <a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8567 The I/O library never closes these files.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8570 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8571 Unless otherwise stated,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8572 all I/O functions return <b>nil</b> on failure
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8573 (plus an error message as a second result and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8574 a system-dependent error code as a third result)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8575 and some value different from <b>nil</b> on success.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8576 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8577 the computation of the error message and error code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8578 in case of errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8579 may be not thread safe,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8580 because they rely on the global C variable <code>errno</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8583 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8584 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8587 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8588 Equivalent to <code>file:close()</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8589 Without a <code>file</code>, closes the default output file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8594 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8595 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8598 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8599 Equivalent to <code>io.output():flush()</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8604 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8605 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8608 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8609 When called with a file name, it opens the named file (in text mode),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8610 and sets its handle as the default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8611 When called with a file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8612 it simply sets this file handle as the default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8613 When called without parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8614 it returns the current default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8618 In case of errors this function raises the error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8619 instead of returning an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8624 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8625 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8628 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8629 Opens the given file name in read mode
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8630 and returns an iterator function that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8631 works like <code>file:lines(···)</code> over the opened file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8632 When the iterator function detects the end of file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8633 it returns no values (to finish the loop) and automatically closes the file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8636 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8637 The call <code>io.lines()</code> (with no file name) is equivalent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8638 to <code>io.input():lines("*l")</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8639 that is, it iterates over the lines of the default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8640 In this case it does not close the file when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8643 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8644 In case of errors this function raises the error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8645 instead of returning an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8650 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8651 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8654 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8655 This function opens a file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8656 in the mode specified in the string <code>mode</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8657 It returns a new file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8658 or, in case of errors, <b>nil</b> plus an error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8661 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8662 The <code>mode</code> string can be any of the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8664 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8665 <li><b>"<code>r</code>": </b> read mode (the default);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8666 <li><b>"<code>w</code>": </b> write mode;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8667 <li><b>"<code>a</code>": </b> append mode;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8668 <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8669 <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8670 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8671 writing is only allowed at the end of file.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8672 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8673 The <code>mode</code> string can also have a '<code>b</code>' at the end,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8674 which is needed in some systems to open the file in binary mode.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8679 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8680 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8683 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8684 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8689 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8690 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8693 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8694 This function is system dependent and is not available
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8695 on all platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8698 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8699 Starts program <code>prog</code> in a separated process and returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8700 a file handle that you can use to read data from this program
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8701 (if <code>mode</code> is <code>"r"</code>, the default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8702 or to write data to this program
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8703 (if <code>mode</code> is <code>"w"</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8708 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8709 <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8712 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8713 Equivalent to <code>io.input():read(···)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8718 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8719 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8723 Returns a handle for a temporary file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8724 This file is opened in update mode
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8725 and it is automatically removed when the program ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8731 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8734 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8735 Checks whether <code>obj</code> is a valid file handle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8736 Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8737 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8738 or <b>nil</b> if <code>obj</code> is not a file handle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8743 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8744 <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8747 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8748 Equivalent to <code>io.output():write(···)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8753 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8754 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8757 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8758 Closes <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8759 Note that files are automatically closed when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8760 their handles are garbage collected,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8761 but that takes an unpredictable amount of time to happen.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8765 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8766 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8767 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8772 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8773 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8776 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8777 Saves any written data to <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8782 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8783 <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8786 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8787 Returns an iterator function that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8788 each time it is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8789 reads the file according to the given formats.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8790 When no format is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8791 uses "<code>l</code>" as a default.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8792 As an example, the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8794 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8795 for c in file:lines(1) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8796 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8797 will iterate over all characters of the file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8798 starting at the current position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8799 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8800 when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8804 In case of errors this function raises the error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8805 instead of returning an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8810 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8811 <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8814 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8815 Reads the file <code>file</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8816 according to the given formats, which specify what to read.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8817 For each format,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8818 the function returns a string or a number with the characters read,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8819 or <b>nil</b> if it cannot read data with the specified format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8820 (In this latter case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8821 the function does not read subsequent formats.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8822 When called without formats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8823 it uses a default format that reads the next line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8824 (see below).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8827 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8828 The available formats are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8830 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8832 <li><b>"<code>n</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8833 reads a numeral and returns it as a float or an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8834 following the lexical conventions of Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8835 (The numeral may have leading spaces and a sign.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8836 This format always reads the longest input sequence that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8837 is a valid prefix for a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8838 if that prefix does not form a valid number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8839 (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8840 it is discarded and the function returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8841 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8843 <li><b>"<code>i</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8844 reads an integral number and returns it as an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8845 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8847 <li><b>"<code>a</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8848 reads the whole file, starting at the current position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8849 On end of file, it returns the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8850 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8852 <li><b>"<code>l</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8853 reads the next line skipping the end of line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8854 returning <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8855 This is the default format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8856 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8858 <li><b>"<code>L</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8859 reads the next line keeping the end-of-line character (if present),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8860 returning <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8861 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8863 <li><b><em>number</em>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8864 reads a string with up to this number of bytes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8865 returning <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8866 If <code>number</code> is zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8867 it reads nothing and returns an empty string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8868 or <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8869 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8871 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8872 The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8877 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8878 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8882 Sets and gets the file position,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8883 measured from the beginning of the file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8884 to the position given by <code>offset</code> plus a base
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8885 specified by the string <code>whence</code>, as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8887 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8888 <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8889 <li><b>"<code>cur</code>": </b> base is current position;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8890 <li><b>"<code>end</code>": </b> base is end of file;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8891 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8892 In case of success, <code>seek</code> returns the final file position,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8893 measured in bytes from the beginning of the file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8894 If <code>seek</code> fails, it returns <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8895 plus a string describing the error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8898 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8899 The default value for <code>whence</code> is <code>"cur"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8900 and for <code>offset</code> is 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8901 Therefore, the call <code>file:seek()</code> returns the current
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8902 file position, without changing it;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8903 the call <code>file:seek("set")</code> sets the position to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8904 beginning of the file (and returns 0);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8905 and the call <code>file:seek("end")</code> sets the position to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8906 end of the file, and returns its size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8912 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8915 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8916 Sets the buffering mode for an output file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8917 There are three available modes:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8919 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8921 <li><b>"<code>no</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8922 no buffering; the result of any output operation appears immediately.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8923 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8925 <li><b>"<code>full</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8926 full buffering; output operation is performed only
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8927 when the buffer is full or when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8928 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8929 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8931 <li><b>"<code>line</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8932 line buffering; output is buffered until a newline is output
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8933 or there is any input from some special files
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8934 (such as a terminal device).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8935 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8937 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8938 For the last two cases, <code>size</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8939 specifies the size of the buffer, in bytes.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8940 The default is an appropriate size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8945 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8946 <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8949 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8950 Writes the value of each of its arguments to <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8951 The arguments must be strings or numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8955 In case of success, this function returns <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8956 Otherwise it returns <b>nil</b> plus a string describing the error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8964 <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8966 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8967 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8970 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8971 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8975 Returns an approximation of the amount in seconds of CPU time
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8976 used by the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8981 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8982 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8985 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8986 Returns a string or a table containing date and time,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8987 formatted according to the given string <code>format</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8990 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8991 If the <code>time</code> argument is present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8992 this is the time to be formatted
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8993 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8994 Otherwise, <code>date</code> formats the current time.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8997 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8998 If <code>format</code> starts with '<code>!</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8999 then the date is formatted in Coordinated Universal Time.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9000 After this optional character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9001 if <code>format</code> is the string "<code>*t</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9002 then <code>date</code> returns a table with the following fields:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9003 <code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9004 <code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9005 <code>wday</code> (weekday, Sunday is 1),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9006 <code>yday</code> (day of the year),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9007 and <code>isdst</code> (daylight saving flag, a boolean).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9008 This last field may be absent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9009 if the information is not available.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9012 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9013 If <code>format</code> is not "<code>*t</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9014 then <code>date</code> returns the date as a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9015 formatted according to the same rules as the ISO C function <code>strftime</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9019 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9020 <code>date</code> returns a reasonable date and time representation that depends on
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9021 the host system and on the current locale
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9022 (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9025 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9026 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9027 this function may be not thread safe
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9028 because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9033 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9034 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9038 Returns the difference, in seconds,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9039 from time <code>t1</code> to time <code>t2</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9040 (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9041 In POSIX, Windows, and some other systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9042 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9047 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9048 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9051 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9052 This function is equivalent to the ISO C function <code>system</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9053 It passes <code>command</code> to be executed by an operating system shell.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9054 Its first result is <b>true</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9055 if the command terminated successfully,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9056 or <b>nil</b> otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9057 After this first result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9058 the function returns a string plus a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9059 as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9061 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9063 <li><b>"<code>exit</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9064 the command terminated normally;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9065 the following number is the exit status of the command.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9066 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9068 <li><b>"<code>signal</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9069 the command was terminated by a signal;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9070 the following number is the signal that terminated the command.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9071 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9073 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9075 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9076 When called without a <code>command</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9077 <code>os.execute</code> returns a boolean that is true if a shell is available.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9083 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9086 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9087 Calls the ISO C function <code>exit</code> to terminate the host program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9088 If <code>code</code> is <b>true</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9089 the returned status is <code>EXIT_SUCCESS</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9090 if <code>code</code> is <b>false</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9091 the returned status is <code>EXIT_FAILURE</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9092 if <code>code</code> is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9093 the returned status is this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9094 The default value for <code>code</code> is <b>true</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9097 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9098 If the optional second argument <code>close</code> is true,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9099 closes the Lua state before exiting.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9104 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9105 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9108 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9109 Returns the value of the process environment variable <code>varname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9110 or <b>nil</b> if the variable is not defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9115 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9116 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9119 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9120 Deletes the file (or empty directory, on POSIX systems)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9121 with the given name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9122 If this function fails, it returns <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9123 plus a string describing the error and the error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9128 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9129 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9133 Renames file or directory named <code>oldname</code> to <code>newname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9134 If this function fails, it returns <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9135 plus a string describing the error and the error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9141 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9144 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9145 Sets the current locale of the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9146 <code>locale</code> is a system-dependent string specifying a locale;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9147 <code>category</code> is an optional string describing which category to change:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9148 <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9149 <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9150 the default category is <code>"all"</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9151 The function returns the name of the new locale,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9152 or <b>nil</b> if the request cannot be honored.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9155 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9156 If <code>locale</code> is the empty string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9157 the current locale is set to an implementation-defined native locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9158 If <code>locale</code> is the string "<code>C</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9159 the current locale is set to the standard C locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9162 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9163 When called with <b>nil</b> as the first argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9164 this function only returns the name of the current locale
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9165 for the given category.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9168 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9169 This function may be not thread safe
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9170 because of its reliance on C function <code>setlocale</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9175 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9176 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9179 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9180 Returns the current time when called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9181 or a time representing the date and time specified by the given table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9182 This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9183 and may have fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9184 <code>hour</code> (default is 12),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9185 <code>min</code> (default is 0),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9186 <code>sec</code> (default is 0),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9187 and <code>isdst</code> (default is <b>nil</b>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9188 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9191 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9192 The returned value is a number, whose meaning depends on your system.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9193 In POSIX, Windows, and some other systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9194 this number counts the number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9195 of seconds since some given start time (the "epoch").
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9196 In other systems, the meaning is not specified,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9197 and the number returned by <code>time</code> can be used only as an argument to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9198 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9203 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9204 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9207 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9208 Returns a string with a file name that can
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9209 be used for a temporary file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9210 The file must be explicitly opened before its use
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9211 and explicitly removed when no longer needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9214 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9215 On POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9216 this function also creates a file with that name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9217 to avoid security risks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9218 (Someone else might create the file with wrong permissions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9219 in the time between getting the name and creating the file.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9220 You still have to open the file to use it
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9221 and to remove it (even if you do not use it).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9224 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9225 When possible,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9226 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9227 which automatically removes the file when the program ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9235 <h2>6.10 – <a name="6.10">The Debug Library</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9237 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9238 This library provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9239 the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9240 You should exert care when using this library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9241 Several of its functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9242 violate basic assumptions about Lua code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9243 (e.g., that variables local to a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9244 cannot be accessed from outside;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9245 that userdata metatables cannot be changed by Lua code;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9246 that Lua programs do not crash)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9247 and therefore can compromise otherwise secure code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9248 Moreover, some functions in this library may be slow.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9252 All functions in this library are provided
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9253 inside the <a name="pdf-debug"><code>debug</code></a> table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9254 All functions that operate over a thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9255 have an optional first argument which is the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9256 thread to operate over.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9257 The default is always the current thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9260 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9261 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9264 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9265 Enters an interactive mode with the user,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9266 running each string that the user enters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9267 Using simple commands and other debug facilities,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9268 the user can inspect global and local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9269 change their values, evaluate expressions, and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9270 A line containing only the word <code>cont</code> finishes this function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9271 so that the caller continues its execution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9275 Note that commands for <code>debug.debug</code> are not lexically nested
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9276 within any function and so have no direct access to local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9281 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9282 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9285 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9286 Returns the current hook settings of the thread, as three values:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9287 the current hook function, the current hook mask,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9288 and the current hook count
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9289 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9295 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9298 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9299 Returns a table with information about a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9300 You can give the function directly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9301 or you can give a number as the value of <code>f</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9302 which means the function running at level <code>f</code> of the call stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9303 of the given thread:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9304 level 0 is the current function (<code>getinfo</code> itself);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9305 level 1 is the function that called <code>getinfo</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9306 (except for tail calls, which do not count on the stack);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9307 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9308 If <code>f</code> is a number larger than the number of active functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9309 then <code>getinfo</code> returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9312 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9313 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9314 with the string <code>what</code> describing which fields to fill in.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9315 The default for <code>what</code> is to get all information available,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9316 except the table of valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9317 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9318 the option '<code>f</code>'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9319 adds a field named <code>func</code> with the function itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9320 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9321 the option '<code>L</code>'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9322 adds a field named <code>activelines</code> with the table of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9323 valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9326 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9327 For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9328 a table with a name for the current function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9329 if a reasonable name can be found,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9330 and the expression <code>debug.getinfo(print)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9331 returns a table with all available information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9332 about the <a href="#pdf-print"><code>print</code></a> function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9337 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9338 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9342 This function returns the name and the value of the local variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9343 with index <code>local</code> of the function at level <code>f</code> of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9344 This function accesses not only explicit local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9345 but also parameters, temporaries, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9348 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9349 The first parameter or local variable has index 1, and so on,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9350 following the order that they are declared in the code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9351 counting only the variables that are active
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9352 in the current scope of the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9353 Negative indices refer to vararg parameters;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9354 -1 is the first vararg parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9355 The function returns <b>nil</b> if there is no variable with the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9356 and raises an error when called with a level out of range.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9357 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9360 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9361 Variable names starting with '<code>(</code>' (open parenthesis)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9362 represent variables with no known names
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9363 (internal variables such as loop control variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9364 and variables from chunks saved without debug information).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9367 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9368 The parameter <code>f</code> may also be a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9369 In that case, <code>getlocal</code> returns only the name of function parameters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9374 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9375 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9378 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9379 Returns the metatable of the given <code>value</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9380 or <b>nil</b> if it does not have a metatable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9385 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9386 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9389 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9390 Returns the registry table (see <a href="#4.5">§4.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9395 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9396 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9399 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9400 This function returns the name and the value of the upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9401 with index <code>up</code> of the function <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9402 The function returns <b>nil</b> if there is no upvalue with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9405 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9406 Variable names starting with '<code>(</code>' (open parenthesis)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9407 represent variables with no known names
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9408 (variables from chunks saved without debug information).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9413 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9414 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9417 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9418 Returns the Lua value associated to <code>u</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9419 If <code>u</code> is not a userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9420 returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9425 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9426 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9429 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9430 Sets the given function as a hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9431 The string <code>mask</code> and the number <code>count</code> describe
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9432 when the hook will be called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9433 The string mask may have any combination of the following characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9434 with the given meaning:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9436 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9437 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9438 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9439 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9440 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9441 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9442 with a <code>count</code> different from zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9443 the hook is called also after every <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9446 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9447 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9448 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9451 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9452 When the hook is called, its first parameter is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9453 describing the event that has triggered its call:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9454 <code>"call"</code> (or <code>"tail call"</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9455 <code>"return"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9456 <code>"line"</code>, and <code>"count"</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9457 For line events,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9458 the hook also gets the new line number as its second parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9459 Inside a hook,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9460 you can call <code>getinfo</code> with level 2 to get more information about
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9461 the running function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9462 (level 0 is the <code>getinfo</code> function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9463 and level 1 is the hook function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9468 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9469 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9472 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9473 This function assigns the value <code>value</code> to the local variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9474 with index <code>local</code> of the function at level <code>level</code> of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9475 The function returns <b>nil</b> if there is no local
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9476 variable with the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9477 and raises an error when called with a <code>level</code> out of range.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9478 (You can call <code>getinfo</code> to check whether the level is valid.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9479 Otherwise, it returns the name of the local variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9482 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9483 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9484 variable indices and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9489 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9490 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9493 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9494 Sets the metatable for the given <code>value</code> to the given <code>table</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9495 (which can be <b>nil</b>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9496 Returns <code>value</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9501 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9502 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9506 This function assigns the value <code>value</code> to the upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9507 with index <code>up</code> of the function <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9508 The function returns <b>nil</b> if there is no upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9509 with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9510 Otherwise, it returns the name of the upvalue.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9515 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9516 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9518
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9519 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9520 Sets the given <code>value</code> as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9521 the Lua value associated to the given <code>udata</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9522 <code>udata</code> must be a full userdata.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9525 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9526 Returns <code>udata</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9531 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9532 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9536 If <code>message</code> is present but is neither a string nor <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9537 this function returns <code>message</code> without further processing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9538 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9539 it returns a string with a traceback of the call stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9540 The optional <code>message</code> string is appended
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9541 at the beginning of the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9542 An optional <code>level</code> number tells at which level
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9543 to start the traceback
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9544 (default is 1, the function calling <code>traceback</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9549 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9550 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9553 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9554 Returns a unique identifier (as a light userdata)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9555 for the upvalue numbered <code>n</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9556 from the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9560 These unique identifiers allow a program to check whether different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9561 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9562 Lua closures that share an upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9563 (that is, that access a same external local variable)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9564 will return identical ids for those upvalue indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9569 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9570 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9574 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9575 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9583 <h1>7 – <a name="7">Lua Standalone</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9585 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9586 Although Lua has been designed as an extension language,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9587 to be embedded in a host C program,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9588 it is also frequently used as a standalone language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9589 An interpreter for Lua as a standalone language,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9590 called simply <code>lua</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9591 is provided with the standard distribution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9592 The standalone interpreter includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9593 all standard libraries, including the debug library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9594 Its usage is:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9596 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9597 lua [options] [script [args]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9598 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9599 The options are:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9601 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9602 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9603 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9604 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9605 <li><b><code>-v</code>: </b> prints version information;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9606 <li><b><code>-E</code>: </b> ignores environment variables;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9607 <li><b><code>--</code>: </b> stops handling options;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9608 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9609 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9610 After handling its options, <code>lua</code> runs the given <em>script</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9611 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9612 <code>lua</code> behaves as <code>lua -v -i</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9613 when the standard input (<code>stdin</code>) is a terminal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9614 and as <code>lua -</code> otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9618 When called without option <code>-E</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9619 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9620 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9621 before running any argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9622 If the variable content has the format <code>@<em>filename</em></code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9623 then <code>lua</code> executes the file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9624 Otherwise, <code>lua</code> executes the string itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9627 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9628 When called with option <code>-E</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9629 besides ignoring <code>LUA_INIT</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9630 Lua also ignores
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9631 the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9632 setting the values of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9633 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9634 with the default paths defined in <code>luaconf.h</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9637 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9638 All options are handled in order, except <code>-i</code> and <code>-E</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9639 For instance, an invocation like
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9641 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9642 $ lua -e'a=1' -e 'print(a)' script.lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9643 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9644 will first set <code>a</code> to 1, then print the value of <code>a</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9645 and finally run the file <code>script.lua</code> with no arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9646 (Here <code>$</code> is the shell prompt. Your prompt may be different.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9649 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9650 Before running any code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9651 <code>lua</code> collects all command-line arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9652 in a global table called <code>arg</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9653 The script name goes to index 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9654 the first argument after the script name goes to index 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9655 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9656 Any arguments before the script name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9657 (that is, the interpreter name plus its options)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9658 go to negative indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9659 For instance, in the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9661 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9662 $ lua -la b.lua t1 t2
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9663 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9664 the table is like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9666 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9667 arg = { [-2] = "lua", [-1] = "-la",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9668 [0] = "b.lua",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9669 [1] = "t1", [2] = "t2" }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9670 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9671 If there is no script in the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9672 the interpreter name goes to index 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9673 followed by the other arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9674 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9676 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9677 $ lua -e "print(arg[1])"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9678 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9679 will print "<code>-e</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9680 If there is a script,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9681 the script is called with parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9682 <code>arg[1]</code>, ···, <code>arg[#arg]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9683 (Like all chunks in Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9684 the script is compiled as a vararg function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9687 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9688 In interactive mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9689 Lua repeatedly prompts and waits for a line.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9690 After reading a line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9691 Lua first try to interpret the line as an expression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9692 If it succeeds, it prints its value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9693 Otherwise, it interprets the line as a statement.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9694 If you write an incomplete statement,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9695 the interpreter waits for its completion
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9696 by issuing a different prompt.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9699 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9700 In case of unprotected errors in the script,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9701 the interpreter reports the error to the standard error stream.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9702 If the error object is not a string but
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9703 has a metamethod <code>__tostring</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9704 the interpreter calls this metamethod to produce the final message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9705 Otherwise, the interpreter converts the error object to a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9706 and adds a stack traceback to it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9710 When finishing normally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9711 the interpreter closes its main Lua state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9712 (see <a href="#lua_close"><code>lua_close</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9713 The script can avoid this step by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9714 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9717 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9718 To allow the use of Lua as a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9719 script interpreter in Unix systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9720 the standalone interpreter skips
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9721 the first line of a chunk if it starts with <code>#</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9722 Therefore, Lua scripts can be made into executable programs
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9723 by using <code>chmod +x</code> and the <code>#!</code> form,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9724 as in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9726 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9727 #!/usr/local/bin/lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9728 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9729 (Of course,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9730 the location of the Lua interpreter may be different in your machine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9731 If <code>lua</code> is in your <code>PATH</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9732 then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9734 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9735 #!/usr/bin/env lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9736 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9737 is a more portable solution.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9741 <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9743 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9744 Here we list the incompatibilities that you may find when moving a program
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9745 from Lua 5.2 to Lua 5.3.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9746 You can avoid some incompatibilities by compiling Lua with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9747 appropriate options (see file <code>luaconf.h</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9748 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9749 all these compatibility options will be removed in the future.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9753 Lua versions can always change the C API in ways that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9754 do not imply source-code changes in a program,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9755 such as the numeric values for constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9756 or the implementation of functions as macros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9757 Therefore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9758 you should not assume that binaries are compatible between
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9759 different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9760 Always recompile clients of the Lua API when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9761 using a new version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9765 Similarly, Lua versions can always change the internal representation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9766 of precompiled chunks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9767 precompiled chunks are not compatible between different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9770 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9771 The standard paths in the official distribution may
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9772 change between versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9776 <h2>8.1 – <a name="8.1">Changes in the Language</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9777 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9779 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9780 The main difference between Lua 5.2 and Lua 5.3 is the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9781 introduction of an integer subtype for numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9782 Although this change should not affect "normal" computations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9783 some computations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9784 (mainly those that involve some kind of overflow)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9785 can give different results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9788 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9789 You can fix these differences by forcing a number to be a float
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9790 (in Lua 5.2 all numbers were float),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9791 in particular writing constants with an ending <code>.0</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9792 or using <code>x = x + 0.0</code> to convert a variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9793 (This recommendation is only for a quick fix
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9794 for an occasional incompatibility;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9795 it is not a general guideline for good programming.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9796 For good programming,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9797 use floats where you need floats
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9798 and integers where you need integers.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9799 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9801 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9802 The conversion of a float to a string now adds a <code>.0</code> suffix
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9803 to the result if it looks like an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9804 (For instance, the float 2.0 will be printed as <code>2.0</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9805 not as <code>2</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9806 You should always use an explicit format
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9807 when you need a specific format for numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9810 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9811 (Formally this is not an incompatibility,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9812 because Lua does not specify how numbers are formatted as strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9813 but some programs assumed a specific format.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9814 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9816 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9817 The generational mode for the garbage collector was removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9818 (It was an experimental feature in Lua 5.2.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9819 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9821 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9826 <h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9827 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9829 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9830 The <code>bit32</code> library has been deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9831 It is easy to require a compatible external library or,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9832 better yet, to replace its functions with appropriate bitwise operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9833 (Keep in mind that <code>bit32</code> operates on 32-bit integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9834 while the bitwise operators in standard Lua operate on 64-bit integers.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9835 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9837 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9838 The Table library now respects metamethods
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9839 for setting and getting elements.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9840 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9842 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9843 The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9844 its <code>__ipairs</code> metamethod has been deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9845 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9847 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9848 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9849 For compatibility, Lua will continue to ignore this character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9850 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9852 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9853 The following functions were deprecated in the mathematical library:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9854 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9855 <code>frexp</code>, and <code>ldexp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9856 You can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9857 you can replace <code>math.atan2</code> with <code>math.atan</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9858 which now accepts one or two parameters;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9859 you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9860 For the other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9861 you can either use an external library or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9862 implement them in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9863 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9865 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9866 The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9867 changed the way it handles versioned names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9868 Now, the version should come after the module name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9869 (as is usual in most other tools).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9870 For compatibility, that searcher still tries the old format
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9871 if it cannot find an open function according to the new style.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9872 (Lua 5.2 already worked that way,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9873 but it did not document the change.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9874 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9876 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9881 <h2>8.3 – <a name="8.3">Changes in the API</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9884 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9886 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9887 Continuation functions now receive as parameters what they needed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9888 to get through <code>lua_getctx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9889 so <code>lua_getctx</code> has been removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9890 Adapt your code accordingly.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9891 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9893 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9894 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9895 Use 0 as the value of this parameter to get the old behavior.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9896 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9898 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9899 Functions to inject/project unsigned integers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9900 (<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9901 <code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9902 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9903 Use their signed equivalents with a type cast.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9904 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9906 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9907 Macros to project non-default integer types
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9908 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9909 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9910 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9911 (or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9912 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9914 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9919 <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9921 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9922 Here is the complete syntax of Lua in extended BNF.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9923 As usual in extended BNF,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9924 {A} means 0 or more As,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9925 and [A] means an optional A.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9926 (For operator precedences, see <a href="#3.4.8">§3.4.8</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9927 for a description of the terminals
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9928 Name, Numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9929 and LiteralString, see <a href="#3.1">§3.1</a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9934 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9936 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9938 block ::= {stat} [retstat]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9940 stat ::= ‘<b>;</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9941 varlist ‘<b>=</b>’ explist \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9942 functioncall \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9943 label \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9944 <b>break</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9945 <b>goto</b> Name \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9946 <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9947 <b>while</b> exp <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9948 <b>repeat</b> block <b>until</b> exp \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9949 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9950 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9951 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9952 <b>function</b> funcname funcbody \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9953 <b>local</b> <b>function</b> Name funcbody \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9954 <b>local</b> namelist [‘<b>=</b>’ explist]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9956 retstat ::= <b>return</b> [explist] [‘<b>;</b>’]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9958 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9960 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9962 varlist ::= var {‘<b>,</b>’ var}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9964 var ::= Name \| prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ \| prefixexp ‘<b>.</b>’ Name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9966 namelist ::= Name {‘<b>,</b>’ Name}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9968 explist ::= exp {‘<b>,</b>’ exp}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9970 exp ::= <b>nil</b> \| <b>false</b> \| <b>true</b> \| Numeral \| LiteralString \| ‘<b>...</b>’ \| functiondef \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9971 prefixexp \| tableconstructor \| exp binop exp \| unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9973 prefixexp ::= var \| functioncall \| ‘<b>(</b>’ exp ‘<b>)</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9975 functioncall ::= prefixexp args \| prefixexp ‘<b>:</b>’ Name args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9977 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ \| tableconstructor \| LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9979 functiondef ::= <b>function</b> funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9981 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9983 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] \| ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9985 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9987 fieldlist ::= field {fieldsep field} [fieldsep]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9989 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp \| Name ‘<b>=</b>’ exp \| exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9991 fieldsep ::= ‘<b>,</b>’ \| ‘<b>;</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9993 binop ::= ‘<b>+</b>’ \| ‘<b>-</b>’ \| ‘<b>*</b>’ \| ‘<b>/</b>’ \| ‘<b>//</b>’ \| ‘<b>^</b>’ \| ‘<b>%</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9994 ‘<b>&</b>’ \| ‘<b>~</b>’ \| ‘<b>\|</b>’ \| ‘<b>>></b>’ \| ‘<b><<</b>’ \| ‘<b>..</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9995 ‘<b><</b>’ \| ‘<b><=</b>’ \| ‘<b>></b>’ \| ‘<b>>=</b>’ \| ‘<b>==</b>’ \| ‘<b>~=</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9996 <b>and</b> \| <b>or</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9998 unop ::= ‘<b>-</b>’ \| <b>not</b> \| ‘<b>#</b>’ \| ‘<b>~</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10000 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10002 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10011 <HR>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10012 <SMALL CLASS="footer">
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10013 Last update:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10014 Fri Jan 16 00:58:20 BRST 2015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10015 </SMALL>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10016 <!--
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10017 Last change: minor edit
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10018 -->
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10019
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10020 </div>
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	10021
391 2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	10022 <% Html.simply_html_body_bottom() %>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	10023 </body>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	10024 </html>
2f5cc9c2cbf0 replace Html.simply_html_page with simply_html_head and simply_html_body_bottom Franklin Schmidt <fschmidt@gmail.com> parents: 389 diff changeset	10025 <%
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	10026 end

Mercurial Hosting > luan

annotate website/src/manual.html.luan @ 417:a40e99cf0b0b