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

annotate website/src/manual.html.luan @ 395:a7cb58532846

work on manual

author	Franklin Schmidt <fschmidt@gmail.com>
date	Fri, 24 Apr 2015 17:42:22 -0600
parents	2f5cc9c2cbf0
children	ba8b0aae6453

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>
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	69 </ul>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	70 </li>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	71 </ul>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	72 </div>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	73
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	74 <hr/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	75
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	76
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	77 <h2 margin-top="1em"><a name="intro">Introduction</a></h2>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	78
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	79 <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	80
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	81 <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	82
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	83 <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	84
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	85
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	86 <h2 margin-top="1em"><a name="basic">Basic Concepts</a></h2>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	87
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	88 <p>This section describes the basic concepts of the language.</p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	89
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	90 <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	91
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	92 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	93 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	94 This means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	95 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	96 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	97 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	98
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	99
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	100 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	101 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	102 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	103 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	104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	106 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	107 There are eight basic types in Luan:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	108 <i>nil</i>, <i>boolean</i>, <i>number</i>,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	109 <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	110 and <i>table</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	111 <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	112 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	113 it usually represents the absence of a useful value.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	114 <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	115 <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	116 <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	117 <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	118 integer numbers and real (floating-point) numbers.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	119 <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	120 the underlying Java implementation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	121
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	122 <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	123 <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	124
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	125
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	126 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	127 Luan can call (and manipulate) functions written in Luan and
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	128 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	129 Both are represented by the type <i>function</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	130
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 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	133 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	134 be stored in Luan variables.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	135 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	136 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	137 except assignment and identity test.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	138 Userdata is useful then Java access is enabled in Luan
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	139
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>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	144 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	145 but with any Luan value except <b>nil</b>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	146 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	147 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	148 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	149 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	150 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	151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	153 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	154 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	155 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	156 symbol tables, sets, records, graphs, trees, etc.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	157 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	158 The language supports this representation by
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	159 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	160 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	161 (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	162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	164 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	165 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	166 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	167 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	168 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	169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	171 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	172 Like indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	173 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	174 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	175 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	176 table fields can contain functions.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	177 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	178
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	181 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	182 the definition of raw equality in the language.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	183 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	184 denote the same table element
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	185 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	186 (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	187 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	188 are equal to their respective integers
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	189 (e.g., <tt>1.0 == 1</tt>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	190
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	191
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	192 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	193 Luan values are <i>objects</i>:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	194 variables do not actually <i>contain</i> values,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	195 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	196 Assignment, parameter passing, and function returns
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	197 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	198 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	199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	201 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	202 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	203 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	204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	208
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	209 <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	210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	211 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	212 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	213 any reference to a free name
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	214 (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	215 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	216 Moreover, every chunk is compiled in the scope of
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	217 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	218 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	219
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	220
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	221 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	222 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	223 the translation of free names,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	224 <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	225 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	226 you can define new variables and parameters with that name.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	227 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	228 visible at that point in the program,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	229 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	230
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	231
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	232 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	233 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	234
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	235
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	236 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	237 When Luan loads a chunk,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	238 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	239
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	240 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	241 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	242
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	243
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 <h3 margin-top="1em"><a name="error">Error Handling</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	247
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	248 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	249 Luan code can explicitly generate an error by calling the
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	250 <a href="#pdf-error"><tt>error</tt></a> function.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	251 If you need to catch errors in Luan,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	252 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	253 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	254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	256 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	257 Whenever there is an error,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	258 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	259 is propagated with information about the error.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	260 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	261 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	262 any value as the error object.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	263 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	264
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	265
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	266
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	267
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	268
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	269 <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	270
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	271 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	272 Every table in Luan can have a <i>metatable</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	273 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	274 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	275 under certain special operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	276 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	277 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	278 For instance, when a table is the operand of an addition,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	279 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	280 If it finds one,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	281 Luan calls this function to perform the addition.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	282
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	283
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	284 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	285 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	286 the corresponding values are called <ii>metamethods</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	287 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	288 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	289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	291 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	292 You can query the metatable of any table
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	293 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	294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	296 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	297 You can replace the metatable of tables
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	298 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	299
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	300
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	301 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	302 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	303 arithmetic operations, bitwise operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	304 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	305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	307 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	308 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	309 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	310 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	311 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	312 for instance, the key for operation "add" is the
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	313 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	314 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	315 the access to a metamethod does not invoke other metamethods.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	316 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	317 with the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	318
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	319 <p><tt><pre>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	320 raw_get(get_metatable(obj) or {}, "__" .. event_name)
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	321 </pre></tt></p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	322
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	323 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	324 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	325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	326 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	328 <li><b>"add": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	329 the <tt>+</tt> operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	330
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	331 If any operand for an addition is a table,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	332 Luan will try to call a metamethod.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	333 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	334 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	335 then Luan will check the second operand.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	336 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	337 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	338 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	339 (adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	340 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	341 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	342 it raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	343 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	345 <li><b>"sub": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	346 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	347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	348 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	349 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	351 <li><b>"mul": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	352 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	353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	354 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	355 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	357 <li><b>"div": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	358 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	359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	360 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	361 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	363 <li><b>"mod": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	364 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	365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	366 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	367 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	369 <li><b>"pow": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	370 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	371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	372 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	373 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	375 <li><b>"unm": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	376 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	377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	378 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	379 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	381 <li><b>"concat": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	382 the <tt>..</tt> (concatenation) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	383
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	384 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	385 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	387 <li><b>"len": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	388 the <tt>#</tt> (length) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	389
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	390 If there is a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	391 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	392 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	393 (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	394 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	395 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	396 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	397 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	398 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	400 <li><b>"eq": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	401 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	402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	403 Behavior similar to the "add" operation,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	404 except that Luan will try a metamethod only when the values
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	405 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	406 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	407 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	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>"lt": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	411 the <tt><</tt> (less than) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	412
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	413 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	414 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	415 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	417 <li><b>"le": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	418 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	419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	420 Unlike other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	421 The less-equal operation can use two different events.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	422 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	423 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	424 If it cannot find such a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	425 then it will try the "<tt>__lt</tt>" event,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	426 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	427 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	428 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	429 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	431 <li><b>"index": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	432 The indexing access <tt>table[key]</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	433
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	434 This event happens
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	435 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	436 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	437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	439 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	440 Despite the name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	441 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	442 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	443 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	444 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	445 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	446 (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	447 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	448 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	450 <li><b>"newindex": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	451 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	452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	453 Like the index event,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	454 this event happens when
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	455 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	456 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	457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	459 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	460 Like with indexing,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	461 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	462 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	463 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	464 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	465 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	466 (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	467 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	468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	470 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	471 Whenever there is a "newindex" metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	472 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	473 (If necessary,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	474 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	475 to do the assignment.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	476 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	478 <li><b>"call": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	479 The call operation <tt>func(args)</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	480
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	481 This event happens when Luan tries to call a table.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	482 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	483 If present,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	484 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	485 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	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 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	492
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	493 <h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	494
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	495 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	496 Luan uses Java's garbage collection.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	497
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	498
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	499
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	500
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	501
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	502 <h2 margin-top="1em"><a name="lang">The Language</a></h2>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	503
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	504 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	505 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	506 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	507 this section describes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	508 which tokens are valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	509 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	510 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	511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	513 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	514 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	515 in which
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	516 {<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	517 [<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	518 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	519 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	520 and other terminal symbols are shown like ‘<b>=</b>’.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	521 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	522 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	523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	525
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	526 <h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	527
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	528 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	529 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	530 between lexical elements (tokens),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	531 except as delimiters between names and keywords.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	532 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	533
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	534 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	535 <i>Names</i>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	536 (also called <i>identifiers</i>)
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	537 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	538 digits, and underscores,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	539 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	540 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	541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	543 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	544 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	545 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	546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	547
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	548 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	549 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	550 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	551 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	552 then true until while
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	553 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	555 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	556 Luan is a case-sensitive language:
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	557 <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	558 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	559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	561 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	562 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	563
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	564 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	565 + - * / % ^ #
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	566 & ~ \| << >> //
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	567 == ~= <= >= < > =
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	568 ( ) { } [ ] ::
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	569 ; : , . .. ...
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	570 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	572 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	573 <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	574 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	575 and can contain the following C-like escape sequences:
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	576 '<tt>\a</tt>' (bell),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	577 '<tt>\b</tt>' (backspace),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	578 '<tt>\f</tt>' (form feed),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	579 '<tt>\n</tt>' (newline),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	580 '<tt>\r</tt>' (carriage return),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	581 '<tt>\t</tt>' (horizontal tab),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	582 '<tt>\v</tt>' (vertical tab),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	583 '<tt>\\</tt>' (backslash),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	584 '<tt>\"</tt>' (quotation mark [double quote]),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	585 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	586 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	587 results in a newline in the string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	588 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	589 of white-space characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	590 including line breaks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	591 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	592 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	593 into the string contents.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	596 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	597 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	598 This can be done
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	599 with the escape sequence <tt>\x<i>XX</i></tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	600 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	601 or with the escape sequence <tt>\<i>ddd</i></tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	602 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	603 (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	604 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	605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	607 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	608 Literal strings can also be defined using a long format
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	609 enclosed by <i>long brackets</i>.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	610 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	611 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	612 opening square bracket.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	613 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	614 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	615 and so on.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	616 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	617 for instance,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	618 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	619 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	620 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	621 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	622 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	623 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	624 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	625 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	626 (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	627 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	628 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	629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	631 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	632 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	633 explicitly affected by the previous rules represents itself.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	634 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	635 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	636 some control characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	637 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	638 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	639 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	640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	642 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	643 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	644 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	645 the newline is not included in the string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	646 As an example
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	647 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	648
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	649 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	650 a = 'alo\n123"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	651 a = "alo\n123\""
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	652 a = '\97lo\10\04923"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	653 a = [[alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	654 123"]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	655 a = [==[
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	656 alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	657 123"]==]
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	658 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	660 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	661 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	662 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	663 and an optional decimal exponent,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	664 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	665 Luan also accepts hexadecimal constants,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	666 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	667 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	668 plus an optional binary exponent,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	669 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	670 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	671 denotes a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	672 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	673 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	674
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	675 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	676 3 345 0xff 0xBEBADA
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	677 </pre></tt></p>
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	678
8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	679 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	680 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	681
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	682 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	683 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	684 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	685 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	687 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	688 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	689 anywhere outside a string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	690 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	691 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	692 which runs until the end of the line.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	693 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	694 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	695 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	696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	700
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	701 <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	702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	703 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	704 Variables are places that store values.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	705 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	706 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	710 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	711 (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	712 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	713
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	714 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	715 var ::= Name
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	716 </pre></tt></p>
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	717
8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	718 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	719 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	720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	723 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	724 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	725 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	726 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	727 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	728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	731 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	732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	734 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	735 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	736
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	737 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	738 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	739 </pre></tt></p>
382 8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	740
8557581740db added tutorial Franklin Schmidt <fschmidt@gmail.com> parents: 380 diff changeset	741 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	742 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	743 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	744 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	745 (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	746 <tt>gettable_event</tt> function.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	747 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	748 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	749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	751 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	752 The syntax <tt>var.Name</tt> is just syntactic sugar for
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	753 <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	754
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	755 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	756 var ::= prefixexp ‘<b>.</b>’ Name
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	757 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	759 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	760 An access to a global variable <tt>x</tt>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	761 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	762 Due to the way that chunks are compiled,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	763 <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	764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	768
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	769 <h3 margin-top="1em"><a name="stmts">Statements</a></h3>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	770
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	771 <p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	772 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	773 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	774 This set includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	775 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	776 and variable declarations.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	779
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	780 <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	781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	782 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	783 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	784 which are executed sequentially:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	785
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	786 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	787 block ::= {stat}
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	788 </pre></tt></p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	789
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	790 <p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	791 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	792 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	793 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	794 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	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 stat ::= ‘<b>;</b>’
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	798 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	800 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	801 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	802
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	803 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	804 stat ::= <b>do</b> block <b>end</b>
389 497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	805 </pre></tt></p>
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	806
497d4ef0a89f documentation work Franklin Schmidt <fschmidt@gmail.com> parents: 387 diff changeset	807 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	808 Explicit blocks are useful
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	809 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	810 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	811 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	812 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	813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	817
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	818 <h4 margin-top="1em"><a name="chunks">Chunks</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	819
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	820 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	821 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	822 Syntactically,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	823 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	824
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	825 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	826 chunk ::= block
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	827 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	828
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	829 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	830 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	831 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	832 (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	833 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	834 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	835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	837 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	838 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	839 To execute a chunk,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	840 Luan first <i>loads</i> it,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	841 compiling the chunk's code,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	842 and then Luan executes the compiled code.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	843
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	844
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	845
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	846
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	847
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	848 <h4 margin-top="1em"><a name="assignment">Assignment</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	849
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	850 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	851 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	852 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	853 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	854 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	855 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	856
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	857 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	858 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	859 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	860 explist ::= exp {‘<b>,</b>’ exp}
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	861 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	862
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	863 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	864 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	865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	867 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	868 Before the assignment,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	869 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	870 the list of variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	871 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	872 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	873 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	874 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	875 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	876 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	877 before the adjustment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	878 (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	879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	882 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	883 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	884 Thus the code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	885
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	886 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	887 i = 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	888 i, a[i] = i+1, 20
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	889 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	890
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	891 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	892 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	893 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	894 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	895 Similarly, the line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	896
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	897 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	898 x, y = y, x
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 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	903 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	904
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	905 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	906 x, y, z = y, z, x
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	907 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	908
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	909 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	910 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	911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	914 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	915 and table fields can be changed via metatables.
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	916 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	917 <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	918 (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	919 <tt>settable_event</tt> function.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	920 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	921 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	922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	924 <p>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	925 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	926 is equivalent to the assignment
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	927 <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	928
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	929
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	930
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	931
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	932 <h4 margin-top="1em"><a name="control">Control Structures</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	933
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	934 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	935 The control structures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	936 <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	937 familiar syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	938
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	939 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	940 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	941 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	942 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	943 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	944
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	945 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	946 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	947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	949 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	950 The condition expression of a
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	951 control structure must be a boolean.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	952 Any other value type will produce an error.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	953 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	954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	956 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	957 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	958 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	959 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	960 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	961 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	962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	965 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	966 <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	967 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	968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	969
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	970 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	971 stat ::= <b>break</b>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	972 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	973
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	974 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	975 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	976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	979 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	980 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	981 (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	982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	983 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	984 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	985
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	986 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	987 stat ::= <b>return</b> [explist] [‘<b>;</b>’]
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	988 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	989
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	990
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	991
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	992
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	993 <h4 margin-top="1em"><a name="for">For Statement</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	994
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	995 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	996 The <b>for</b> statement works over functions,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	997 called <i>iterators</i>.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	998 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	999 stopping when this new value is <b>nil</b>.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1000 The <b>for</b> loop has the following syntax:
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 <p><tt><pre>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1003 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	1004 namelist ::= Name {‘<b>,</b>’ Name}
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1005 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1006
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1007 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1008 A <b>for</b> statement like
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1009
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1010 <p><tt><pre>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1011 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	1012 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1013
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1014 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1015 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	1016
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1017 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1018 do
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1019 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	1020 while true do
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1021 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	1022 if <i>var_1</i> == nil then break end
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1023 <i>block</i>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1024 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1025 end
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1026 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1029 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1031 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1033 <li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1034 <tt><i>exp</i></tt> is evaluated only once.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1035 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	1036 </li>
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 <li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1039 <tt><i>f</i></tt> is an invisible variable.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1040 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	1041 </li>
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>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1044 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	1045 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1047 <li>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1048 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	1049 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	1050 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	1051 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	1052 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1054 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1055
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1058
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1059 <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	1060
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1061 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1062 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	1063 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	1064
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1065 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1066 stat ::= functioncall
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1067 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1068
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1069 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1070 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	1071 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	1072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1073
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 <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	1076
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1077 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1078 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	1079 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	1080
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1081 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1082 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist]
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1083 </pre></tt></p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1084
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1085 <p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1086 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	1087 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	1088 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	1089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1091 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1092 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	1093 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	1094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1096 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1097 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	1098
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
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1102 <h3 margin-top="1em"><a name="expressions">Expressions</a></h3>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1103
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1104 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1105 The basic expressions in Luan are the following:
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1106
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1107 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1108 exp ::= prefixexp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1109 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	1110 exp ::= Numeral
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1111 exp ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1112 exp ::= functiondef
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1113 exp ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1114 exp ::= ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1115 exp ::= exp binop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1116 exp ::= unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1117 prefixexp ::= var \| functioncall \| ‘<b>(</b>’ exp ‘<b>)</b>’
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1118 </pre></tt></p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1120 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1121 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	1122 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	1123 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	1124 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	1125 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	1126 Vararg expressions,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1127 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	1128 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	1129 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	1130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1133 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	1134 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	1135 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	1136 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	1137 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	1138 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	1139
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1142 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	1143 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	1144 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	1145 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	1146 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	1147 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	1148 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	1149 (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	1150 In all other contexts,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1151 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	1152 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	1153 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	1154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1156 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1157 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1158
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1159 <p><tt><pre>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1160 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	1161 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	1162 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	1163 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	1164 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	1165 -- 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	1166 -- 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	1167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1168 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	1169 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	1170 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	1171 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	1172 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	1173 {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	1174 {...} -- 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	1175 {f(), nil} -- f() is adjusted to 1 result
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1176 </pre></tt></p>
371 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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1179 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	1180 Thus,
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1181 <tt>(f(x,y,z))</tt> is always a single value,
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1182 even if <tt>f</tt> returns several values.
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1183 (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	1184 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	1185
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1186
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1187
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1188 <h4 margin-top="1em"><a name="arithmetic">Arithmetic Operators</a></h4>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1189
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1190 <p>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1191 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	1192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1193 <ul>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1194 <li><b><tt>+</tt>: </b>addition</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1195 <li><b><tt>-</tt>: </b>subtraction</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1196 <li><b><tt>*</tt>: </b>multiplication</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1197 <li><b><tt>/</tt>: </b>division</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1198 <li><b><tt>%</tt>: </b>modulo</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1199 <li><b><tt>^</tt>: </b>exponentiation</li>
a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1200 <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	1201 </ul>
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 <p>
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1204 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	1205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1206 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1207 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	1208 that rounds the quotient towards minus infinite (floor division).
395 a7cb58532846 work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 391 diff changeset	1209 (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	1210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1211
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 <h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1214 Lua provides some automatic conversions between some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1215 types and representations at run time.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1216 Bitwise operators always convert float operands to integers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1217 Exponentiation and float division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1218 always convert integer operands to floats.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1219 All other arithmetic operations applied to mixed numbers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1220 (integers and floats) convert the integer operand to a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1221 this is called the <em>usual rule</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1222 The C API also converts both integers to floats and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1223 floats to integers, as needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1224 Moreover, string concatenation accepts numbers as arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1225 besides strings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1228 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1229 Lua also converts strings to numbers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1230 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	1231
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1234 In a conversion from integer to float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1235 if the integer value has an exact representation as a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1236 that is the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1237 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1238 the conversion gets the nearest higher or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1239 the nearest lower representable value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1240 This kind of conversion never fails.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1244 The conversion from float to integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1245 checks whether the float has an exact representation as an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1246 (that is, the float has an integral value and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1247 it is in the range of integer representation).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1248 If it does, that representation is the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1249 Otherwise, the conversion fails.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1250
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1253 The conversion from strings to numbers goes as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1254 First, the string is converted to 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	1255 following its syntax and the rules of the Lua lexer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1256 (The string may have also 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	1257 Then, the resulting number is converted to the required type
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1258 (float or integer) according to the previous rules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1261 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1262 The conversion from numbers to strings uses a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1263 non-specified human-readable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1264 For complete control over how numbers are converted to strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1265 use the <code>format</code> function from the string library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1266 (see <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	1267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1272 <h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1273 Lua supports the following relational operators:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1275 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1276 <li><b><code>==</code>: </b>equality</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1277 <li><b><code>~=</code>: </b>inequality</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1278 <li><b><code><</code>: </b>less than</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1279 <li><b><code>></code>: </b>greater than</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1280 <li><b><code><=</code>: </b>less or equal</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1281 <li><b><code>>=</code>: </b>greater or equal</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1282 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1283 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	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 Equality (<code>==</code>) first compares the type of its operands.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1288 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	1289 Otherwise, the values of the operands are compared.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1290 Strings are compared in the obvious way.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1291 Numbers follow 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 if both operands are integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1293 they are compared as integers;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1294 otherwise, they are converted to floats
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1295 and compared as such.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1298 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1299 Tables, userdata, and threads
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1300 are compared by reference:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1301 two objects are considered equal only if they are the same object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1302 Every time you create a new object
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1303 (a table, userdata, or thread),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1304 this new object is different from any previously existing object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1305 Closures with the same reference are always equal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1306 Closures with any detectable difference
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1307 (different behavior, different definition) are always different.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1310 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1311 You can change the way that Lua compares tables and userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1312 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	1313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1315 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1316 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	1317 or vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1318 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1319 and <code>t[0]</code> and <code>t["0"]</code> denote different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1320 entries in a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1323 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1324 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1327 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1328 The order operators work as follows.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1329 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	1330 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	1331 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	1332 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	1333 then their values are compared according to the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1334 Otherwise, Lua tries to call the "lt" or the "le"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1335 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	1336 A comparison <code>a > b</code> is translated to <code>b < a</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1337 and <code>a >= b</code> is translated to <code>b <= a</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1343 <h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1344 The logical operators in Lua are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1345 <b>and</b>, <b>or</b>, and <b>not</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1346 Like the control structures (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	1347 all logical operators consider both <b>false</b> and <b>nil</b> as false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1348 and anything else as true.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1351 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1352 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	1353 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	1354 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	1355 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	1356 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	1357 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	1358 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	1359 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	1360 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1361 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	1362 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1364 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1365 10 or 20 --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1366 10 or error() --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1367 nil or "a" --> "a"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1368 nil and 10 --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1369 false and error() --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1370 false and nil --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1371 false or nil --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1372 10 and 20 --> 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1373 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1374 (In this manual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1375 <code>--></code> indicates the result of the preceding expression.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1381 <h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1382 The string concatenation operator in Lua is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1383 denoted by two dots ('<code>..</code>').
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1384 If both operands are strings or numbers, then they are converted to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1385 strings according to the rules described in <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	1386 Otherwise, the <code>__concat</code> metamethod is called (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	1387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1392 <h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1394 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1395 The length operator is denoted by the unary prefix operator <code>#</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1396 The length of a string is its number of bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1397 (that is, the usual meaning of string length when each
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1398 character is one byte).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1402 A program can modify the behavior of the length operator for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1403 any value but strings through the <code>__len</code> 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	1404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1406 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1407 Unless a <code>__len</code> metamethod is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1408 the length of a table <code>t</code> is only defined if the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1409 table is a <em>sequence</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1410 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1411 the set of its positive numeric keys is equal to <em>{1..n}</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1412 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	1413 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	1414 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	1415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1416 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1417 {10, 20, nil, 40}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1418 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1419 is not a sequence, because it has the key <code>4</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1420 but does not have the key <code>3</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1421 (So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1422 to the set of positive numeric keys of that table.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1423 Note, however, that non-numeric keys do not interfere
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1424 with whether a table is a sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1430 <h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1431 Operator precedence in Lua follows the table below,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1432 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	1433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1434 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1435 or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1436 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1437 < > <= >= ~= ==
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1438 \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1439 ~
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1440 &
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1441 << >>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1442 ..
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1443 + -
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1444 * / // %
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1445 unary operators (not # - ~)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1446 ^
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1447 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1448 As usual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1449 you can use parentheses to change the precedences of an expression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1450 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1451 operators are right associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1452 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	1453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1458 <h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1459 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	1460 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	1461 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	1462 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	1463 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	1464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1465 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1466 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	1467 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	1468 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	1469 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	1470 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1472 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1473 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1474 with key <code>exp1</code> and value <code>exp2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1475 A field of the form <code>name = exp</code> is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1476 <code>["name"] = exp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1477 Finally, fields of the form <code>exp</code> are equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1478 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1479 starting with 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1480 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	1481 For example,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1483 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1484 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1485 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1486 is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1488 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1489 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1490 local t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1491 t[f(1)] = g
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1492 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	1493 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	1494 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	1495 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	1496 t[30] = 23
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1497 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	1498 a = t
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1499 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1500 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1503 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	1504 (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	1505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1507 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1508 If the last field in the list has the form <code>exp</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1509 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	1510 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	1511 (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	1512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1514 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1515 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	1516 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	1517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1518
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1520
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 <h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1523 A function call in Lua has the following syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1525 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1526 functioncall ::= prefixexp args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1527 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1528 In a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1529 first prefixexp and args are evaluated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1530 If the value of prefixexp has type <em>function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1531 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	1532 with the given arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1533 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	1534 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	1535 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	1536 (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	1537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1539 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1540 The form
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1542 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1543 functioncall ::= 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	1544 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1545 can be used to call "methods".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1546 A call <code>v:name(<em>args</em>)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1547 is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1548 except that <code>v</code> is evaluated only once.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1551 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1552 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	1553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1554 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1555 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	1556 args ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1557 args ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1558 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1559 All argument expressions are evaluated before the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1560 A call of the form <code>f{<em>fields</em>}</code> is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1561 syntactic sugar for <code>f({<em>fields</em>})</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1562 that is, the argument list is a single new table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1563 A call of the form <code>f'<em>string</em>'</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1564 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1565 is syntactic sugar for <code>f('<em>string</em>')</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1566 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	1567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1569 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1570 A call of the form <code>return <em>functioncall</em></code> is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1571 a <em>tail call</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1572 Lua implements <em>proper tail calls</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1573 (or <em>proper tail recursion</em>):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1574 in a tail call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1575 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	1576 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	1577 a program can execute.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1578 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	1579 calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1580 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	1581 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	1582 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	1583 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	1584 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	1585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1586 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1587 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	1588 return 2 * f(x)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1589 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	1590 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	1591 return x or 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	1592 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1597 <h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1599 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1600 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	1601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1602 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1603 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	1604 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	1605 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1607 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1608 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	1609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1610 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1611 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	1612 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	1613 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	1614 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1615 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1617 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1618 function f () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1619 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1620 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1622 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1623 f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1624 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1625 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1627 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1628 function t.a.b.c.f () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1629 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1630 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1632 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1633 t.a.b.c.f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1634 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1635 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1637 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1638 local function f () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1639 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1640 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1642 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1643 local f; f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1644 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1645 not to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1647 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1648 local f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1649 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1650 (This only makes a difference when the body of the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1651 contains references to <code>f</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1654 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1655 A function definition is an executable expression,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1656 whose value has type <em>function</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1657 When Lua precompiles a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1658 all its function bodies are precompiled too.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1659 Then, whenever Lua executes the function definition,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1660 the function is <em>instantiated</em> (or <em>closed</em>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1661 This function instance (or <em>closure</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1662 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	1663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1665 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1666 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	1667 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	1668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1669 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1670 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	1671 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1672 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	1673 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	1674 the length of the list of parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1675 unless the function is a <em>vararg function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1676 which is indicated by three dots ('<code>...</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1677 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	1678 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	1679 instead, it collects all extra arguments and supplies them
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1680 to the function through a <em>vararg expression</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1681 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	1682 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	1683 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	1684 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	1685 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	1686 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	1687 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	1688 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	1689 (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	1690
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 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	1694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1695 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1696 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	1697 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	1698 function r() return 1,2,3 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1699 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1700 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	1701 to the vararg expression:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1703 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1704 CALL PARAMETERS
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1706 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	1707 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	1708 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	1709 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	1710 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	1711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1712 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	1713 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	1714 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	1715 g(5, r()) a=5, b=1, ... --> 2 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1716 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1718 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1719 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	1720 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	1721 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	1722 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	1723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1727 There is a system-dependent limit on the number of values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1728 that a function may return.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1729 This limit is guaranteed to be larger than 1000.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1733 The <em>colon</em> syntax
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1734 is used for defining <em>methods</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1735 that is, functions that have an implicit extra parameter <code>self</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1736 Thus, the statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1738 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1739 function t.a.b.c:f (<em>params</em>) <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1740 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1741 is syntactic sugar for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1743 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1744 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1745 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1752 <h2>3.5 – <a name="3.5">Visibility Rules</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1756 Lua is a lexically scoped language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1757 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	1758 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	1759 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	1760 Consider the following example:
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1763 x = 10 -- global variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1764 do -- new block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1765 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	1766 print(x) --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1767 x = x+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1768 do -- another block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1769 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	1770 print(x) --> 12
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1771 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1772 print(x) --> 11
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1773 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1774 print(x) --> 10 (the global one)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1775 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1777 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1778 Notice that, in a declaration like <code>local x = x</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1779 the new <code>x</code> being declared is not in scope yet,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1780 and so the second <code>x</code> refers to the outside variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1781
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1784 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	1785 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	1786 defined inside their scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1787 A local variable used by an inner function is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1788 an <em>upvalue</em>, or <em>external local variable</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1789 inside the inner function.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1793 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	1794 defines new local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1795 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1797 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1798 a = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1799 local x = 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1800 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	1801 local y = 0
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1802 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	1803 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1804 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1805 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	1806 (that is, ten instances of the anonymous function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1807 Each of these closures uses a different <code>y</code> variable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1808 while all of them share the same <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1814 <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	1815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1818 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	1819 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	1820 with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1821 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	1822 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	1823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1825 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1826 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	1827 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	1828 Except where stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1829 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	1830 (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	1831 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	1832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1834 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1835 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	1836 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	1837 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	1838 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1842 <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	1843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1844 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1845 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	1846 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	1847 (<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	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 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	1852 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	1853 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	1854 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	1855 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	1856 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1860 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1861 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	1862 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	1863 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	1864 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	1865 (starting at 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1866 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	1867 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	1868 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	1869 (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	1870 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1871 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	1872 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	1873 (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	1874 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	1875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1876
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1880 <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	1881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1882 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1883 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	1884 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	1885 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1886 <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	1887 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	1888 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	1889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1891 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1892 Whenever Lua calls C,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1893 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	1894 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	1895 <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	1896 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	1897 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	1898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1900 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1901 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	1902 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	1903 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	1904 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	1905 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	1906 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	1907
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1912 <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	1913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1914 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1915 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	1916 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1920 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	1921 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	1922 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	1923 (<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	1924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1925 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	1926 require valid indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1929 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1930 Unless otherwise noted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1931 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	1932 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	1933 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	1934 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	1935 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	1936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1938 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1939 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	1940 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	1941 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	1942 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	1943 including the pseudo-indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1944 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	1945 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	1946 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	1947 (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	1948 Except when noted otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1949 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	1950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1953 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	1954 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	1955 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	1956 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	1957 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	1958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1960 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1961 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	1962 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	1963 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	1964 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	1965
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1970 <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	1971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1972 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1973 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	1974 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	1975 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	1976 (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	1977 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	1978 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	1979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1981 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1982 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	1983 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	1984 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	1985 <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	1986 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	1987 <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	1988 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	1989 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	1990 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	1991 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1997 <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	1998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1999 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2000 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	2001 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	2002 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	2003 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	2004 <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	2005 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	2006 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	2007 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	2008 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	2009 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	2010 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	2011 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	2012 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	2013 As with variable names,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2014 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	2015 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	2016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2019 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	2020 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	2021 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	2022 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	2023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2025 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2026 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	2027 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	2028 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	2029 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	2030 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	2031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2032 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2033 <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	2034 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	2035 (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	2036 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2038 <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	2039 the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2040 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2041 </ul>
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
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 <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	2047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2048 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2049 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	2050 (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	2051 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	2052 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	2053 (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	2054 and runtime errors)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2055 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	2056 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	2057 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	2058 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	2059 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	2060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2063 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	2064 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	2065 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	2066 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	2067 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	2068 never returning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2069 (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	2070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2072 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2073 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	2074 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	2075 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	2076 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	2077 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	2078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2080 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2081 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	2082 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	2083 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	2084 it can raise errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2087 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2088 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	2089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2091
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2094 <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	2095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2096 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2097 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	2098 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	2099 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	2100 (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	2101 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	2102 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	2103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2106 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	2107 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	2108 except for three functions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2109 <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	2110 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	2111 (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	2112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2114 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2115 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	2116 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	2117 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	2118 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	2119 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	2120 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	2121 (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	2122 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	2123 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	2124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2126 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2127 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	2128 After the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2129 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	2130 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2131 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	2132 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	2133 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	2134 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	2135 As the name implies,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2136 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	2137 of 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 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	2142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2143 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2144 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	2145 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2146 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	2147 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2148 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2149 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2150 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	2151 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	2152 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	2153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2154 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2155 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	2156 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2157 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2159 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	2160 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2161 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	2162 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2163 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2164 In the above code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2165 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	2166 <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	2167 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	2168 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	2169 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	2170 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	2171 (errors or yielding),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2172 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	2173 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	2174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2175 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2176 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	2177 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2178 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	2179 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2180 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2181 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	2182 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	2183 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	2184 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	2185 <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	2186 (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	2187 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	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 Besides the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2192 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	2193 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	2194 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	2195 (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	2196 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	2197 continuation function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2198 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	2199 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	2200 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	2201 (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	2202 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	2203 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	2204 (For these two functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2205 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	2206 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	2207 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	2208 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	2209 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	2210 (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	2211 directly the continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2212 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	2213
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 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	2217 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	2218 from the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2219 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	2220 (For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2221 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	2222 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	2223 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	2224 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	2225 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2227
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2231 <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	2232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2233 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2234 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	2235 alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2236 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	2237 <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	2238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2240 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2241 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	2242 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	2243 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	2244 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	2245 (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	2246 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	2247 <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	2248 depending on the situation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2249 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	2250 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	2251 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	2252 (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	2253 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	2254 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	2255 '<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	2256 '<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	2257 '<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	2258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2261 <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	2262 <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	2263 <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	2264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2265 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2266 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	2267 (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	2268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2273 <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	2274 <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	2275 void *ptr,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2276 size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2277 size_t nsize);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2279 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2280 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	2281 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	2282 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	2283 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	2284 Its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2285 <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	2286 <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	2287 <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	2288 is being allocated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2289 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	2290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2292 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2293 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	2294 <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	2295 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	2296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2298 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2299 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	2300 <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	2301 <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	2302 <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	2303 <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	2304 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	2305 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	2306 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	2307
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 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	2311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2313 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2314 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	2315 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	2316 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	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 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	2321 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	2322 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	2323 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	2324 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	2325 <code>osize >= nsize</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2328 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2329 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	2330 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	2331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2332 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2333 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	2334 size_t nsize) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2335 (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	2336 if (nsize == 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2337 free(ptr);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2338 return NULL;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2339 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2340 else
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2341 return realloc(ptr, nsize);
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 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2344 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	2345 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	2346 <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	2347 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	2348 (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	2349 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	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_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	2356 <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	2357 <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	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 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	2361 (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	2362 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	2363 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	2364 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	2365 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	2366 (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	2367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2369 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2370 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	2371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2372 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2374 <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	2375 <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	2376 <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	2377 <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	2378 <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	2379 <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	2380 <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	2381 <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	2382 <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	2383 <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	2384 <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	2385 <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	2386 <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	2387 <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	2388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2389 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2390
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2394 <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	2395 <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	2396 <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	2397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2398 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2399 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	2400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2405 <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	2406 <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	2407 <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	2408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2409 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2410 Calls a function.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2414 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	2415 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	2416 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	2417 in direct order;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2418 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	2419 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	2420 <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	2421 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	2422 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	2423 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	2424 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	2425 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	2426 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	2427 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	2428 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	2429 (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	2430 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	2431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2433 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2434 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	2435 (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	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 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	2440 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	2441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2442 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2443 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	2444 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2445 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	2446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2447 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2448 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	2449 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	2450 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	2451 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	2452 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	2453 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	2454 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	2455 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	2456 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2457 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	2458 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	2459 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	2460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2465 <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	2466 <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	2467 <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	2468 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2469 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2470 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2471 lua_KFunction k);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2474 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	2475 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	2476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2477
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 <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	2482 <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	2483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2484 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2485 Type for C functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2488 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2489 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	2490 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	2491 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	2492 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	2493 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	2494 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	2495 <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	2496 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	2497 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	2498 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	2499 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	2500 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	2501 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	2502 discarded by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2503 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	2504 many results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2507 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2508 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	2509 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	2510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2511 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2512 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	2513 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	2514 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	2515 int i;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2516 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	2517 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	2518 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	2519 lua_error(L);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2520 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2521 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	2522 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2523 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	2524 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	2525 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	2526 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2527 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2530
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 <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	2533 <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	2534 <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	2535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2536 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2537 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	2538 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	2539 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	2540 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	2541 (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	2542 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	2543 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	2544 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	2545 it is left unchanged.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2549
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 <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	2552 <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	2553 <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	2554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2555 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2556 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	2557 (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	2558 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	2559 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	2560 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	2561 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	2562 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	2563 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	2564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2566
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2569 <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	2570 <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	2571 <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	2572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2574 Compares two Lua values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2575 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	2576 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	2577 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	2578 (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	2579 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2580 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	2581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2583 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2584 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	2585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2586 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2588 <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	2589 <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	2590 <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	2591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2592 </ul>
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_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	2598 <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	2599 <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	2600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2601 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2602 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	2603 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	2604 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	2605 (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	2606 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	2607 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	2608 (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	2609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2614 <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	2615 <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	2616 <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	2617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2618 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2619 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	2620 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	2621 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	2622 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	2623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2625
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 <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	2629 <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	2630 <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	2631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2633 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	2634 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	2635 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	2636 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	2637 the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2638 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	2639 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	2640 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	2641 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	2642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2644
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 <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	2648 <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	2649 <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	2650 lua_Writer writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2651 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2652 int strip);</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 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	2656 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	2657 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	2658 if loaded again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2659 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	2660 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	2661 <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	2662 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	2663 to write them.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2666 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2667 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	2668 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	2669 about the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2670
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2673 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	2674 call to the writer;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2675 0 means no errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2678 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2679 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	2680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2683
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 <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	2686 <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	2687 <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	2688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2689 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2690 Generates a Lua error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2691 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	2692 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	2693 and therefore never returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2694 (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	2695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2700 <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	2701 <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	2702 <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	2703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2704 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2705 Controls the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2706
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 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	2710 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	2711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2712 <ul>
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 <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	2715 stops the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2716 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2718 <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	2719 restarts the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2720 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2722 <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	2723 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	2724 </li>
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 <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	2727 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	2728 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2730 <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	2731 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	2732 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	2733 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2735 <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	2736 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	2737 </li>
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 <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	2740 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	2741 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	2742 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	2743 </li>
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 <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	2746 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	2747 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	2748 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	2749 </li>
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 <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	2752 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	2753 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2754 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2756 </ul>
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 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	2760 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2766 <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	2767 <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	2768 <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	2769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2770 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2771 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	2772 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	2773 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	2774
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2779 <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	2780 <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	2781 <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	2782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2783 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2784 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	2785 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	2786 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	2787 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	2788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2790 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2791 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	2792
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2797 <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	2798 <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	2799 <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	2800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2801 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2802 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	2803 given Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2804 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	2805 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	2806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2808 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2809 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	2810 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2814 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	2815 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	2816 (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	2817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2818
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2822 <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	2823 <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	2824 <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	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 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	2828 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	2829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2830
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2834 <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	2835 <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	2836 <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	2837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2839 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	2840 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	2841 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	2842 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	2843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2846 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	2847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2848
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 <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	2853 <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	2854 <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	2855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2856 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2857 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	2858 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	2859 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2860 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2864
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 <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	2867 <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	2868 <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	2869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2870 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2871 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	2872 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	2873 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	2874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2876 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2877 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	2878 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	2879 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	2880 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2884 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	2885
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2888
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 <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	2891 <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	2892 <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	2893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2894 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2895 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	2896 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	2897 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	2898 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	2899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2902
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 <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	2905 <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	2906 <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	2907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2908 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2909 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	2910 at the given index.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2914 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	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_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	2921 <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	2922 <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	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 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	2926 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	2927 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	2928 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2934 <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	2935 <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	2936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2937 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2938 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2942 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	2943 (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	2944 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	2945 (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	2946 (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	2947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2949 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2950 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	2951 <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	2952 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2958 <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	2959 <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	2960 <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	2961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2962 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2963 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	2964 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2970 <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	2971 <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	2972 <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	2973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2975 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	2976 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2982 <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	2983 <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	2984 <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	2985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2987 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	2988 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2994 <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	2995 <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	2996 <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	2997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2998 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2999 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	3000 (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	3001 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3007 <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	3008 <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	3009 <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	3010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3011 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3012 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	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_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	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_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	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 <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3025 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3026
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 <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	3032 <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	3033 <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	3034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3035 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3036 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	3037 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3038
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 <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	3044 <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	3045 <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	3046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3047 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3048 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	3049 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	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_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	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_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	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 number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3062 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	3063 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3069 <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	3070 <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	3071 <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	3072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3073 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3074 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	3075 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	3076 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3082 <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	3083 <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	3084 <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	3085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3086 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3087 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	3088 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3089
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 <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	3095 <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	3096 <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	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 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	3100 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3106 <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	3107 <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	3108 <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	3109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3110 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3111 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	3112 (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	3113
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 <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	3119 <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	3120 <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	3121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3122 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3123 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	3124 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3125
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3130 <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	3131 <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	3132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3133 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3134 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	3135 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	3136 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	3137 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	3138 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	3139 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	3140
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3143
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 <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	3146 <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	3147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3148 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3149 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	3150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3152
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3155 <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	3156 <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	3157 <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	3158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3159 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3160 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	3161 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	3162 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	3163 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	3164
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3169 <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	3170 <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	3171 <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	3172 lua_Reader reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3173 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3174 const char *chunkname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3175 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3178 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	3179 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	3180 <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	3181 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	3182 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	3183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3185 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3186 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	3187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3188 <ul>
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 <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	3191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3192 <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	3193 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	3194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3195 <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	3196 memory allocation error;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3198 <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	3199 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	3200 (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	3201 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	3202 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3204 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3207 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	3208 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	3209 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	3210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3213 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	3214 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	3215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3217 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3218 <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	3219 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	3220 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	3221 with the addition that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3222 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	3223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3225 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3226 <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	3227 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	3228 unmodified when returning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3231 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3232 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	3233 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	3234 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	3235 When loading main chunks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3236 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	3237 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	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_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	3244 <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	3245 <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	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 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	3249 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	3250 (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	3251 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	3252 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	3253 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	3254 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3260 <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	3261 <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	3262 <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	3263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3264 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3265 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	3266 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3270
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 <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	3273 <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	3274 <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	3275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3276 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3277 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	3278 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	3279 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	3280 its global environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3281 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	3282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3284 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3285 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	3286 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	3287 like any Lua object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3291
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 <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	3294 <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	3295 <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	3296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3297 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3298 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	3299 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	3300 and returns this address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3301 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	3302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3303
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3307 <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	3308 <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	3309 <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	3310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3311 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3312 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	3313 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	3314 (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	3315 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	3316 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	3317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3319 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3320 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	3321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3322 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3323 /* 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	3324 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	3325 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	3326 /* 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	3327 printf("%s - %s\n",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3328 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	3329 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	3330 /* 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	3331 lua_pop(L, 1);
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 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3335 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3336 While traversing a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3337 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	3338 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	3339 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	3340 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	3341 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	3342
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 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	3346 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	3347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3352 <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	3353 <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	3354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3355 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3356 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	3357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3359 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3360 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	3361 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	3362 (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	3363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3368 <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	3369 <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	3370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3371 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3372 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	3373 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	3374 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	3375 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	3376 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	3377 conversion was successful.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3378 (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	3379 correctly without this macro,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3380 due to roundings.)
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3384 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	3385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3386
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3390 <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	3391 <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	3392 <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	3393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3394 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3395 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	3396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3398 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3399 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	3400 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	3401 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	3402 <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	3403 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	3404 <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	3405 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	3406 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	3407 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	3408 <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	3409 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3413 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	3414 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	3415 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	3416 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	3417 <em>message handler</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3418 (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	3419 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	3420 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	3421 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	3422 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	3423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3425 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3426 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	3427 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	3428 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	3429 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	3430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3432 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3433 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	3434 (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	3435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3436 <ul>
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 <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	3439 success.</li>
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 <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	3442 a runtime error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3443 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3445 <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	3446 memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3447 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	3448 </li>
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 <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	3451 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	3452 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3454 <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	3455 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	3456 (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	3457 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3459 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3464 <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	3465 <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	3466 <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	3467 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3468 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3469 int msgh,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3470 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3471 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3473 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3474 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	3475 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	3476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3477
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3481 <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	3482 <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	3483 <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	3484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3485 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3486 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3492 <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	3493 <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	3494 <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	3495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3496 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3497 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	3498
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3503 <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	3504 <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	3505 <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	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 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	3509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3511 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3512 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	3513 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	3514 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	3515 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	3516 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	3517 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	3518 (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	3519 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	3520 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	3521 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	3522 associated with the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3523 <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	3524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3526 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3527 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	3528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3530 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3531 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	3532 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	3533 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	3534 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	3535
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3540 <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	3541 <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	3542 <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	3543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3544 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3545 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	3546 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	3547 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	3548 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	3549
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3552 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	3553 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	3554 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	3555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3557 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3558 <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	3559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3560 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3561 #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	3562 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3563 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3569 <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	3570 <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	3571 <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	3572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3574 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	3575 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	3576 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	3577 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	3578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3579 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3581 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3582 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	3583 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	3584 (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	3585 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3587 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3588 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	3589 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	3590 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	3591 '<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	3592 '<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	3593 '<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	3594 '<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	3595 '<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	3596 '<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	3597 '<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	3598 '<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	3599 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3601 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3606 <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	3607 <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	3608 <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	3609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3610 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3611 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	3612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3614
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3617 <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	3618 <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	3619 <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	3620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3621 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3622 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	3623
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3628 <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	3629 <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	3630 <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	3631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3633 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	3634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3636 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3637 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	3638 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	3639 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	3640 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	3641 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	3642 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	3643 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	3644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3646
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3649 <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	3650 <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	3651 <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	3652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3653 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3654 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	3655 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	3656 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	3657
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3662 <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	3663 <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	3664 <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	3665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3666 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3667 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	3668 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3669 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	3670 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	3671 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3672 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	3673 including embedded zeros.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3677 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	3678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3680
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3683 <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	3684 <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	3685 <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	3686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3687 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3688 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	3689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3692
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 <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	3695 <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	3696 <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	3697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3698 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3699 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3705 <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	3706 <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	3707 <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	3708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3710 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	3711 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3712 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	3713 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	3714 the function returns.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3717 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3718 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	3719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3721 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3722 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	3723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3725
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 <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	3729 <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	3730 <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	3731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3733 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	3734 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	3735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3737
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 <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	3741 <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	3742 <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	3743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3745 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	3746 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3752 <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	3753 <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	3754 <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	3755 const char *fmt,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3756 va_list argp);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3759 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	3760 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	3761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3763
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3766 <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	3767 <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	3768 <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	3769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3770 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3771 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	3772 <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	3773 (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	3774 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3775 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3781 <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	3782 <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	3783 <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	3784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3785 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3786 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	3787 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3791
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 <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	3794 <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	3795 <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	3796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3797 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3798 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	3799 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	3800 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3801 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	3802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3804 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3805 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3811 <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	3812 <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	3813 <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	3814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3815 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3816 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	3817 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	3818 <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	3819 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3820 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	3821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3823 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3824 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3830 <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	3831 <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	3832 <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	3833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3834 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3835 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	3836 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	3837 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	3838 with no metamethods;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3839 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	3840 for the userdata;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3841 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	3842
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 <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	3848 <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	3849 <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	3850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3851 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3852 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	3853 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3859 <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	3860 <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	3861 <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	3862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3863 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3864 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	3865 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	3866 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3870 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	3871 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3872 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	3873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3876
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 <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	3879 <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	3880 <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	3881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3882 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3883 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	3884 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	3885 <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	3886 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	3887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3890 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	3891 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3892 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	3893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3894
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 <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	3899 <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	3900 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3901 size_t *size);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3903 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3904 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	3905 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	3906 <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	3907 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	3908 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	3909 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	3910 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	3911 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	3912 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	3913 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	3914 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	3915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3916
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3920 <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	3921 <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	3922 <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	3923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3924 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3925 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	3926 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	3927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3928 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3929 #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	3930 (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	3931 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3934
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 <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	3937 <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	3938 <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	3939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3940 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3941 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	3942 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	3943 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	3944 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	3945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3950 <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	3951 <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	3952 <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	3953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3955 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	3956 without shifting any element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3957 (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	3958 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3964 <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	3965 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3966 <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	3967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3968 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3969 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	3970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3972 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3973 To start a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3974 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	3975 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	3976 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	3977 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	3978 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	3979 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	3980 <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	3981 <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	3982 <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	3983 without errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3984 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3988 In case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3989 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	3990 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	3991 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	3992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3995 To resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3996 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	3997 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	3998 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	3999 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	4000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4002 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4003 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	4004 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	4005 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4011 <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	4012 <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	4013 <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	4014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4016 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	4017 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	4018 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	4019 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	4020 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	4021 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	4022
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4027 <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	4028 <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	4029 <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	4030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4031 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4032 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	4033 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	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_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	4040 <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	4041 <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	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 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	4045 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	4046 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4050 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	4051 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	4052 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	4053
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4058 <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	4059 <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	4060 <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	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 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	4064 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	4065
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 <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	4071 <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	4072 <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	4073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4075 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	4076 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	4077 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	4078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4080 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4081 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	4082 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	4083 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4089 <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	4090 <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	4091 <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	4092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4093 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4094 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	4095 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4099
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 <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	4102 <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	4103 <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	4104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4106 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	4107 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	4108 <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	4109 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	4110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4112 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4113 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	4114 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	4115 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4121 <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	4122 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4123 <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	4124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4125 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4126 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	4127 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	4128 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	4129 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	4130 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4136 <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	4137 <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	4138 <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	4139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4141 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	4142 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	4143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4145
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4148 <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	4149 <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	4150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4152 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	4153 (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	4154 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	4155 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	4156 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	4157
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4159 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4160 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	4161 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	4162 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	4163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4166
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 <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	4169 <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	4170 <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	4171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4172 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4173 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	4174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4176 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4177 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	4178 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	4179 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	4180 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	4181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4184 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	4185 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	4186 (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	4187 (to resume a coroutine).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4189
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 <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	4194 <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	4195 <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	4196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4197 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4198 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	4199 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	4200 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	4201 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	4202 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	4203 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	4204 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	4205 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	4206 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	4207 (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	4208 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	4209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4214 <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	4215 <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	4216 <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	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 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	4220 value (0 or 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4221 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	4222 <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	4223 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	4224 otherwise it returns false.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4225 (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	4226 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	4227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4229
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4232 <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	4233 <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	4234 <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	4235
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4236 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4237 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	4238 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	4239 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	4240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4241
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4245 <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	4246 <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	4247 <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	4248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4249 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4250 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	4251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4256 <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	4257 <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	4258 <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	4259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4260 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4261 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	4262 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	4263 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	4264 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	4265 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	4266
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4269 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	4270 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	4271 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	4272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4274
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4277 <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	4278 <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	4279 <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	4280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4281 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4282 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	4283 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	4284 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	4285 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	4286 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	4287 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	4288 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	4289 <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	4290 (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	4291 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	4292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4295 <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	4296 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	4297 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	4298 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	4299 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	4300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4302 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4303 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	4304 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	4305 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	4306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4307
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 <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	4312 <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	4313 <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	4314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4315 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4316 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	4317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4318
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 <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	4323 <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	4324 <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	4325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4326 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4327 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	4328 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	4329 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	4330 (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	4331 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	4332
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4335 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	4336 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	4337 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	4338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4340
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4343 <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	4344 <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	4345 <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	4346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4347 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4348 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	4349 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	4350 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	4351 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	4352 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	4353 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	4354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4356 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4357 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	4358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4363 <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	4364 <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	4365 <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	4366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4367 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4368 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	4369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4371
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 <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	4375 <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	4376 <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	4377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4378 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4379 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	4380 (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	4381 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	4382 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	4383
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 <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	4389 <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	4390 <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	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 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	4394 returns its block address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4395 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	4396 returns its pointer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4397 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	4398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4401
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 <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	4404 <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	4405 <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	4406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4407 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4408 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	4409 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	4410 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	4411 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	4412 <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	4413 <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	4414 <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	4415 <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	4416 <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	4417 <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	4418 <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	4419 <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	4420 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4421 <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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4427 <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	4428 <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	4429 <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	4430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4431 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4432 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	4433 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	4434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4439 <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	4440 <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	4441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4442 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4443 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	4444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4445
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 <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	4450 <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	4451 <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	4452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4453 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4454 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	4455 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	4456
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4461 <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	4462 <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	4463 <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	4464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4465 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4466 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	4467 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	4468 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	4469 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	4470 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	4471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4476 <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	4477 <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	4478 const void* p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4479 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4480 void* ud);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4483 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	4484 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	4485 <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	4486 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	4487 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	4488 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	4489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4491 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4492 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	4493 0 means no errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4494 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	4495 calling the writer again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4498
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 <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	4502 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4503 <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	4504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4506 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	4507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4509 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4510 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	4511 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4517 <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	4518 <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	4519 <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	4520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4521 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4522 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	4523 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	4524 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	4525 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	4526 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	4527
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4532 <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	4533 <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	4534 <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	4535 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4536 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4537 lua_KFunction k);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4540 Yields a coroutine (thread).
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4543 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4544 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	4545 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	4546 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	4547 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	4548 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	4549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4551 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4552 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	4553 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	4554 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	4555 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	4556 from the previous function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4557 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	4558 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	4559 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4560 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	4561 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	4562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4564 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4565 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	4566 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	4567 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	4568 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	4569 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	4570 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	4571 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	4572 (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	4573 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	4574 Lua will yield and,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4575 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	4576 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	4577 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	4578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4580 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4581 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	4582 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	4583 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	4584 (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	4585
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4592 <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	4593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4594 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4595 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	4596 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	4597 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	4598 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	4599 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	4600 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	4601
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4604 <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	4605 <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	4606 int event;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4607 const char name; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4608 const char namewhat; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4609 const char what; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4610 const char source; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4611 int currentline; /* (l) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4612 int linedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4613 int lastlinedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4614 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	4615 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	4616 char isvararg; /* (u) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4617 char istailcall; /* (t) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4618 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	4619 /* private part */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4620 <em>other fields</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4621 } lua_Debug;</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4624 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	4625 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	4626 <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	4627 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	4628 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	4629 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	4630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4633 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	4634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4635 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4637 <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	4638 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	4639 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	4640 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	4641 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	4642 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	4643 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	4644 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4645 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	4646 <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	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>short_src</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4650 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	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>linedefined</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4654 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	4655 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4657 <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	4658 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	4659 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4661 <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	4662 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	4663 <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	4664 <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	4665 </li>
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 <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	4668 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	4669 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	4670 <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	4671 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4673 <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	4674 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	4675 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	4676 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	4677 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	4678 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	4679 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	4680 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	4681 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	4682 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	4683 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4685 <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	4686 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	4687 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	4688 <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	4689 <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	4690 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	4691 (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	4692 </li>
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 <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	4695 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	4696 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	4697 </li>
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 <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	4700 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	4701 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4703 <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	4704 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	4705 (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	4706 </li>
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 <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	4709 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	4710 (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	4711 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4713 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4718 <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	4719 <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	4720 <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	4721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4723 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	4724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4729 <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	4730 <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	4731 <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	4732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4733 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4734 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	4735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4736
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4740 <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	4741 <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	4742 <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	4743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4745 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	4746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4747
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4751 <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	4752 <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	4753 <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	4754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4755 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4756 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	4757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4759 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4760 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	4761 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	4762 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	4763 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	4764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4767 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	4768 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	4769 (In that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4770 <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	4771 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	4772 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	4773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4774 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4775 lua_Debug ar;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4776 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	4777 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	4778 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	4779 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4782 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	4783 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	4784 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	4785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4786 <ul>
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 <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	4789 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4791 <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	4792 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	4793 <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	4794 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4796 <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	4797 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4799 <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	4800 </li>
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 <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	4803 <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	4804 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4806 <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	4807 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	4808 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	4809 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4811 <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	4812 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	4813 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	4814 (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	4815 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	4816 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	4817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4819 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4820 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	4821 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	4822 </li>
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 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4826 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4827 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	4828 (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	4829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4830
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4834 <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	4835 <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	4836 <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	4837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4839 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	4840 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	4841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4843 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4844 In the first case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4845 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	4846 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	4847 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	4848 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	4849 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	4850 and names.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4853 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4854 <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	4855 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4858 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4859 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	4860 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	4861 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	4862 (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	4863 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4869 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	4870
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 <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	4876 <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	4877 <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	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 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	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 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	4885 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	4886 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	4887 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	4888 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	4889 (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	4890 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	4891 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	4892 it returns 0.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4898 <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	4899 <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	4900 <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	4901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4902 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4903 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	4904 (For Lua functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4905 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	4906 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	4907 <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	4908 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	4909 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4910 <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	4911 (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	4912 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	4913 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	4914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4916 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4917 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	4918 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	4919 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	4920 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4926 <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	4927 <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	4928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4929 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4930 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	4931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4933 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4934 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	4935 <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	4936 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	4937 <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	4938 <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	4939 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	4940 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	4941 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	4942 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	4943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4945 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4946 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	4947 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	4948 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	4949
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4952 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	4953 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	4954 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	4955
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4958 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	4959 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	4960 <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	4961
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4964 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	4965 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	4966 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	4967 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	4968 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	4969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4971
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 <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	4975 <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	4976 <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	4977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4979 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	4980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4982 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4983 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	4984 <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	4985 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	4986 <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	4987 <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	4988 <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	4989 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	4990 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	4991 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	4992 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	4993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4994 <ul>
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 <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	4997 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	4998 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	4999 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5001 <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	5002 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	5003 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	5004 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	5005 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5007 <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	5008 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	5009 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	5010 (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	5011 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5013 <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	5014 <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5015 (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	5016 </li>
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 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5021 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	5022
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5027 <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	5028 <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	5029 <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	5030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5031 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5032 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	5033 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	5034 (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	5035 <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	5036 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	5037 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5041 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	5042 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	5043 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	5044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5046
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5049 <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	5050 <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	5051 <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	5052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5053 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5054 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	5055 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	5056 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	5057 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	5058 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	5059 (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	5060
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5063 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	5064 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	5065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5067
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 <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	5071 <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	5072 <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	5073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5075 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	5076 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	5077 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	5078 (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	5079 (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	5080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5083 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	5084 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5085 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	5086 (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	5087 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	5088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5089
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5093 <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	5094 <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	5095 <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	5096 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	5097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5098 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5099 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	5100 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	5101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5102
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
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 <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	5109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5110 <p>
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 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	5113 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	5114 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	5115 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	5116 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	5117 common tasks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5120 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5121 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	5122 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	5123 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5127 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	5128 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	5129 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	5130 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	5131 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	5132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5133
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5134 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5135 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	5136 extra stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5137 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	5138 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	5139 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	5140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5143 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	5144 check C function arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5145 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	5146 (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	5147 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5151 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	5152 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	5153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5156 <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	5157
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5158 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5159 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	5160 in alphabetical order.
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 <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	5165 <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	5166 <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	5167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5168 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5169 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	5170 (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	5171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5174
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 <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	5177 <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	5178 <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	5179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5180 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5181 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	5182 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	5183 (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	5184 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	5185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5190 <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	5191 <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	5192 <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	5193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5194 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5195 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	5196 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	5197 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5203 <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	5204 <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	5205 <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	5206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5207 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5208 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	5209 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	5210 (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	5211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5214
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 <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	5217 <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	5218 <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	5219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5220 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5221 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	5222 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	5223 (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	5224 Pops the value.
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 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	5229 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	5230 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	5231
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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5236 <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	5237 <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	5238 <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	5239 int cond,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5240 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5241 const char *extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5244 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	5245 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	5246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5247
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5251 <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	5252 <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	5253 <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	5254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5255 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5256 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	5257 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	5258 using a standard message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5259 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	5260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5261 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5262 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	5263 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5264 This function never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5266
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
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 <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	5271 <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	5272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5273 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5274 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	5275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5278 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	5279 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	5280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5281 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5283 <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	5284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5285 <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	5286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5287 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5288 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	5289 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	5290 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5292 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5293 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	5294 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	5295 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5297 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5299 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5300 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	5301 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	5302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5303 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5305 <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	5306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5307 <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	5308 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	5309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5310 <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	5311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5312 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5313 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	5314 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	5315 copied into that space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5316 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5318 </ul>
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 During its normal operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5322 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	5323 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	5324 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	5325 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	5326 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	5327 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5328 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	5329 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	5330 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	5331 (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	5332 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	5333 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	5334 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5340 <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	5341 <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	5342 <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	5343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5344 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5345 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	5346 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	5347 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	5348 (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	5349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5351
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5354 <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	5355 <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	5356 <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	5357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5358 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5359 Equivalent to the sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5360 <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	5361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5364
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 <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	5367 <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	5368 <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	5369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5370 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5371 Calls a metamethod.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5374 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5375 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	5376 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	5377 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	5378 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	5379 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	5380 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	5381 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	5382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5383
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5387 <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	5388 <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	5389 <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	5390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5391 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5392 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	5393 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	5394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5399 <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	5400 <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	5401 <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	5402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5403 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5404 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	5405 (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	5406 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5412 <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	5413 <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	5414 <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	5415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5416 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5417 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	5418 and returns this string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5419 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	5420 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5424 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	5425 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	5426
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5431 <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	5432 <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	5433 <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	5434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5436 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	5437 and returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5440
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5443 <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	5444 <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	5445 <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	5446 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5447 const char *def,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5448 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	5449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5450 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5451 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	5452 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	5453 (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	5454 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	5455 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	5456 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	5457
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 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	5461 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	5462 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5466 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	5467 (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	5468 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	5469
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5474 <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	5475 <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	5476 <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	5477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5478 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5479 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	5480 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	5481 <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	5482 (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	5483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5488 <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	5489 <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	5490 <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	5491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5492 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5493 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	5494 and returns this string.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5497 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5498 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	5499 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	5500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5502
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5505 <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	5506 <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	5507 <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	5508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5509 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5510 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	5511 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5517 <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	5518 <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	5519 <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	5520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5521 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5522 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	5523 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	5524 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	5525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5526
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 <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	5531 <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	5532 <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	5533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5534 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5535 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	5536 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	5537 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	5538 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	5539 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	5540 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	5541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5543
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 <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	5547 <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	5548 <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	5549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5551 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	5552 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	5553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5554 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5555 (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	5556 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5557 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	5558 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	5559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5562
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 <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	5565 <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	5566 <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	5567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5568 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5569 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	5570 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	5571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5572 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5573 (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	5574 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5575 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	5576 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5582 <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	5583 <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	5584 <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	5585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5586 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5587 Raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5588 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	5589 plus any extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5590 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	5591 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	5592 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	5593 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5597 This function never returns,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5598 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	5599 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	5600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5605 <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	5606 <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	5607 <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	5608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5609 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5610 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	5611 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	5612 (<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	5613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5618 <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	5619 <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	5620 <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	5621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5622 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5623 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	5624 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	5625 (<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	5626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5631 <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	5632 <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	5633 <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	5634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5635 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5636 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	5637 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	5638 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	5639 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	5640 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5646 <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	5647 <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	5648 <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	5649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5650 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5651 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	5652 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	5653 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	5654 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5660 <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	5661 <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	5662 <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	5663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5664 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5665 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	5666 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	5667 is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5668 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	5669 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	5670 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	5671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5676 <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	5677 <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	5678 <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	5679 const char *s,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5680 const char *p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5681 const char *r);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5683 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5684 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	5685 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	5686 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	5687 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	5688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5690
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 <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	5694 <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	5695 <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	5696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5697 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5698 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	5699 as a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5700 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	5701 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	5702 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5708 <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	5709 <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	5710 <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	5711 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5712 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5713 const char *name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5716 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	5717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5718
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5722 <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	5723 <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	5724 <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	5725 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5726 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5727 const char *name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5728 const char *mode);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5731 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	5732 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	5733 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5737 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	5738 <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	5739 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	5740 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	5741
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5744
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5746 <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	5747 <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	5748 <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	5749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5750 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5751 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	5752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5755
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 <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	5758 <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	5759 <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	5760 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5763 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	5764 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	5765 named <code>filename</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5766 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	5767 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	5768 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	5769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5771 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5772 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	5773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5775 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5776 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	5777 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	5778 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5782 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	5783 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	5784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5785
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5789 <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	5790 <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	5791 <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	5792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5793 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5794 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	5795 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	5796 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	5797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5799 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5800 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5804 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	5805 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	5806
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5811 <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	5812 <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	5813 <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	5814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5815 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5816 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	5817 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	5818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5820 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5821 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	5822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5823 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5824 (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	5825 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5826 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	5827 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	5828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5829
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5833 <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	5834 <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	5835 <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	5836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5837 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5838 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	5839 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	5840 (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	5841 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	5842 (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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5846 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	5847 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	5848 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	5849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5850
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5854 <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	5855 <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	5856 <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	5857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5858 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5859 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	5860 returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5861 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5862 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	5863 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	5864 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	5865 and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5866 (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	5867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5869 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5870 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	5871 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	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_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	5878 <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	5879 <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	5880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5882 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	5883 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	5884 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	5885 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	5886 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	5887 errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5890 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5891 Returns the new state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5892 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	5893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5894
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 <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	5899 <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	5900 <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	5901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5902 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5903 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	5904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5909 <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	5910 <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	5911 <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	5912 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5913 lua_Integer d);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5916 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	5917 (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	5918 returns this integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5919 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	5920 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5921 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5927 <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	5928 <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	5929 <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	5930 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5931 const char *d,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5932 size_t *l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5934 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5935 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	5936 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5937 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	5938 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5939 Otherwise, raises an error.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5943 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	5944 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	5945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5946
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5950 <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	5951 <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	5952 <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	5953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5955 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	5956 returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5957 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	5958 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5959 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5962
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5965 <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	5966 <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	5967 <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	5968 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5969 const char *d);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5972 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	5973 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5974 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	5975 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5976 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5977
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 <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	5983 <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	5984 <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	5985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5987 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	5988 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	5989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5990
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5994 <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	5995 <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	5996 <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	5997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5998 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5999 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	6000 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	6001 (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	6002 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	6003 <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	6004 it to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6006
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 <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	6011 <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	6012 <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	6013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6014 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6015 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	6016 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	6017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6022 <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	6023 <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	6024 <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	6025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6026 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6027 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6033 <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	6034 <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	6035 <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	6036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6038 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	6039 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	6040 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	6041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6044 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	6045 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	6046 <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	6047 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	6048 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	6049 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6053 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	6054 <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	6055 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	6056 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	6057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6062 <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	6063 <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	6064 const char *name;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6065 lua_CFunction func;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6066 } luaL_Reg;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6068 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6069 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	6070 <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	6071 <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	6072 the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6073 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	6074 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	6075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6077
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6080 <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	6081 <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	6082 <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	6083 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	6084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6085 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6086 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	6087 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	6088 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	6089 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	6090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6093 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	6094 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	6095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6097 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6098 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	6099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6104 <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	6105 <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	6106 <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	6107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6108 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6109 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	6110 (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	6111 (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	6112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6114 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6115 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	6116 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	6117 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	6118 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	6119 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	6120
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 <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	6126 <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	6127 <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	6128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6129 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6130 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	6131 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	6132 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	6133
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 <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	6139 <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	6140 FILE *f;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6141 lua_CFunction closef;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6142 } luaL_Stream;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6144 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6145 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	6146 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	6147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6149 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6150 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	6151 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	6152 (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	6153 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	6154 (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	6155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6157 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6158 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	6159 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	6160 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	6161 (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	6162 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	6163 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	6164 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	6165 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	6166 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	6167 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	6168 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	6169 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	6170 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	6171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6172
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 <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	6177 <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	6178 <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	6179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6180 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6181 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	6182 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	6183 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	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_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	6190 <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	6191 <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	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 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	6195 in a reasonable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6196 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	6197 returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6198 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	6199 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	6200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6202 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6203 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	6204 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	6205 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	6206 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6212 <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	6213 <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	6214 <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	6215 int level);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6217 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6218 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	6219 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	6220 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	6221 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	6222 to start the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6223
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6228 <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	6229 <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	6230 <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	6231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6232 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6233 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	6234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6235
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6239 <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	6240 <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	6241 <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	6242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6244 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	6245 (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	6246 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	6247 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	6248 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	6249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6252 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	6253 <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	6254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6255
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
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 <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	6260 <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	6261 <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	6262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6263 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6264 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	6265 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	6266 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	6267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6268 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6269 <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	6270 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6271 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	6272 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	6273 etc.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6276 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6277 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	6278
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6285 <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	6286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6287 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6288 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	6289 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	6290 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	6291 (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	6292 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	6293 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	6294 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	6295 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	6296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6298 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6299 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	6300 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	6301 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	6302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6303 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6305 <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	6306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6307 <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	6308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6309 <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	6310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6311 <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	6312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6313 <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	6314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6315 <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	6316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6317 <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	6318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6319 <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	6320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6321 <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	6322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6323 <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	6324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6325 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6326 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	6327 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	6328 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	6329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6331 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6332 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	6333 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	6334 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	6335 Alternatively,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6336 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	6337 <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	6338 <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	6339 <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	6340 <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	6341 <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	6342 <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	6343 <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	6344 <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	6345 <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	6346 <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	6347 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	6348 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	6349
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6352 <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	6353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6354 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6355 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	6356 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	6357 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	6358 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	6359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6362 <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	6363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6365 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6366 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	6367 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	6368 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	6369 In case of error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6370 <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	6371 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	6372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6374
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6377 <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	6378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6380 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6381 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	6382 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	6383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6384 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6386 <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	6387 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	6388 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	6389 </li>
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 <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	6392 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	6393 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	6394 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	6395 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6397 <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	6398 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	6399 </li>
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 <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	6402 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	6403 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	6404 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	6405 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	6406 (except for overflows).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6407 </li>
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 <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	6410 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	6411 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	6412 With a zero value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6413 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	6414 For non-zero values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6415 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	6416 (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	6417 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	6418 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6420 <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	6421 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	6422 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	6423 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	6424 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6426 <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	6427 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	6428 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	6429 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	6430 </li>
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 <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	6433 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	6434 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6435 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6437 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6441 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6442 <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	6443 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	6444 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6445 <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	6446 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	6447 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	6448 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	6449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6450
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 <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	6455 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	6456 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	6457 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	6458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6460 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6461 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	6462 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	6463 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	6464 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	6465 <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	6466 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	6467 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	6468 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	6469 to the message.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6472
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6475 <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	6476 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	6477 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	6478 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	6479 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	6480 nor vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6481
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6485 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6486 <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	6487
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6490 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	6491 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6492 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	6493 returns the associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6494 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	6495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6499 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6500 <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	6501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6503 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6504 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	6505 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6507 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6508 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	6509 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6510 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	6511 (<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	6512 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	6513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6517 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6518 <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	6519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6521 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6522 Loads a chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6525 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6526 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	6527 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	6528 <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	6529 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	6530 with previous results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6531 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	6532
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6535 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	6536 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	6537 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	6538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6540 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6541 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	6542 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	6543 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	6544 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	6545 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	6546 (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	6547 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	6548 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	6549 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6550 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	6551 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	6552 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	6553 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	6554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6556 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6557 <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	6558 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	6559 When absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6560 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	6561 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	6562
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6565 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	6566 (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	6567 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	6568 "<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	6569 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	6570 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	6571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6574 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	6575 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	6576 the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6577
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6582 <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	6583
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6586 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	6587 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	6588 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	6589 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6594 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6595 <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	6596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6598 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6599 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	6600 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	6601 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	6602 <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	6603 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6604 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	6605 <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	6606 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6607 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	6608 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	6609 <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	6610 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	6611 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6612 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	6613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6615 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6616 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	6617 <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	6618 (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	6619 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	6620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6622 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6623 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	6624 during the traversal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6625 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	6626 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	6627 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	6628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6633 <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	6634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6636 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6637 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	6638 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	6639 results from the call.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6643 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6644 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	6645 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6647 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6648 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	6649 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6650 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	6651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6653 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6654 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	6655 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	6656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6657
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6661 <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	6662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6664 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6665 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	6666 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	6667 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	6668 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	6669 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	6670 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	6671 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	6672 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	6673 after this first result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6674 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	6675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6679 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6680 <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	6681 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	6682 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	6683 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	6684 <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	6685 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	6686 for instance for debugging.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6687 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	6688 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6693 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6694 <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	6695 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	6696 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6697 Returns a boolean.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6702 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6703 <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	6704 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	6705 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6706 <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	6707 <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	6708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6712 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6713 <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	6714 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	6715 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	6716 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6717 Returns an integer.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6723 <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	6724 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	6725 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6726 <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	6727 <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	6728 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	6729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6732 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	6733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6738 <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	6739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6741 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6742 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	6743 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	6744 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	6745 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	6746 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	6747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6748
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6752 <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	6753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6755 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6756 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	6757 (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	6758 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	6759 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	6760 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	6761 raises an error.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6765 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	6766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6767
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6771 <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	6772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6774 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6775 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	6776 <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	6777 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	6778 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	6779 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	6780 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	6781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6783 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6784 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	6785 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	6786 (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	6787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6789 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6790 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	6791 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	6792 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	6793 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	6794 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	6795 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	6796 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	6797 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	6798 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6804 <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	6805 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	6806 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	6807 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	6808 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	6809 (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	6810 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	6811
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 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	6815 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	6816 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	6817 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	6818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6820
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6823 <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	6824 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	6825 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	6826 "<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	6827 "<code>number</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6828 "<code>string</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6829 "<code>boolean</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6830 "<code>table</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6831 "<code>function</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6832 "<code>thread</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6833 and "<code>userdata</code>".
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6839 <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	6840 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	6841 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	6842 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	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-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	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 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	6853 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	6854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6861 <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	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 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	6865 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	6866 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	6867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6869 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6870 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6874 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	6875 <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	6876 Returns this new coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6877 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	6878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6880
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6883 <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	6884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6886 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6887 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	6888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6890 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6891 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	6892 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	6893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6897 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6898 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6902 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	6903 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	6904 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	6905 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	6906 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	6907 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	6908 <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	6909 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	6910 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	6911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6914 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	6915 <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	6916 (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	6917 (when the coroutine terminates).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6918 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	6919 <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	6920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6921
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 <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	6926
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6929 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	6930 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6935 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6936 <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	6937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6939 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6940 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	6941 <code>"running"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6942 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	6943 <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	6944 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	6945 <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	6946 (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	6947 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	6948 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	6949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6953 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6954 <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	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 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	6959 <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	6960 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	6961 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	6962 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	6963 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	6964 except the first boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6965 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	6966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6970 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6971 <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	6972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6975 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	6976 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	6977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6984 <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	6985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6987 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	6988 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	6989 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	6990 <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	6991 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	6992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6995 <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	6996
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6999 Loads the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7000 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	7001 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	7002 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	7003 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	7004 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	7005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7007 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7008 To find a loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7009 <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	7010 By changing this sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7011 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	7012 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	7013 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	7014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7016 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7017 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	7018 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	7019 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	7020 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	7021 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	7022 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	7023 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	7024 If that also fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7025 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	7026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7029 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	7030 <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	7031 <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	7032 (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	7033 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	7034 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	7035 <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	7036 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	7037 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	7038 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	7039 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	7040 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	7041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7044 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	7045 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	7046 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	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.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	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 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	7057 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	7058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7059 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7061 <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	7062 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	7063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7064 <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	7065 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	7066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7067 <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	7068 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	7069 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	7070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7071 <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	7072 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	7073 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	7074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7075 <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	7076 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	7077 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	7078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7079 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7083 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7084 <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	7085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7087 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7088 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	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 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	7093 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	7094 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	7095 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	7096 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	7097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7101 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7102 <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	7103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7106 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	7107 modules are already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7108 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	7109 <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	7110 <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	7111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7113 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7114 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	7115 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	7116 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	7117
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7121 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7122 <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	7123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7125 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7126 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	7127
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7130 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	7131 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	7132 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	7133 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	7134 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7135 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	7136 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	7137 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	7138 (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	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 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	7143 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	7144 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	7145 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	7146 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	7147 <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	7148 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	7149 <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	7150 (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	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 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	7155 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	7156 (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	7157 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	7158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7162 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7163 <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	7164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7166 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7167 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	7168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7170 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7171 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	7172 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	7173 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	7174 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	7175 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	7176 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	7177 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	7178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7182 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7183 <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	7184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7186 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7187 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	7188 (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	7189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7191 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7192 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	7193 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	7194 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	7195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7199 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7200 <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	7201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7203 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7204 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	7205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7207 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7208 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	7209 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	7210 <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	7211 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	7212 sole parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7213 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	7214 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	7215 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	7216 (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	7217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7219 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7220 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	7221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7223 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7224 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	7225 <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	7226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7228 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7229 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	7230 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	7231 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7235 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	7236 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	7237 Again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7238 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	7239 For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7240 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	7241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7242 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7243 "./?.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	7244 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7245 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	7246 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	7247 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	7248 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	7249 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	7250 application with the library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7251 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	7252 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	7253 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	7254 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	7255 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	7256 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	7257 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	7258 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	7259 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	7260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7262 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7263 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	7264 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	7265 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	7266 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	7267 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	7268 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	7269 the submodule;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7270 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	7271 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	7272 into one single library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7273 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7277 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	7278 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	7279 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	7280 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	7281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7285 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7286 <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	7287
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7289 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7290 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	7291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7294 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	7295 <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	7296 For each template,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7297 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	7298 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	7299 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	7300 (a dot, by default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7301 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	7302 (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	7303 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	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 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	7308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7309 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7310 "./?.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	7311 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7312 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	7313 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	7314 <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	7315 <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	7316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7318 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7319 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	7320 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	7321 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	7322 (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	7323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7327
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 <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	7331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7333 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	7334 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	7335 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	7336 (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	7337 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	7338 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	7339 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	7340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7342 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7343 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	7344 <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	7345 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	7346 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	7347 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	7348 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	7349 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	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 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	7354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7356 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7357 <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	7358 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	7359 <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	7360 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	7361 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	7362 These indices are corrected
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7363 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	7364
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7367 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	7368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7372 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7373 <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	7374 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	7375 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	7376 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	7377 to its corresponding argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7380 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7381 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	7382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7386 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7387 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7391 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	7392 (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	7393 of the given function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7394 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	7395 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	7396 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	7397 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	7398 about the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7399 (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	7400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7402 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7403 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	7404 When (re)loaded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7405 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	7406 (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	7407 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	7408 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	7409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7413 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7414 <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	7415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7417 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7418 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	7419 <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	7420 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	7421 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	7422 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	7423 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	7424 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	7425 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	7426 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	7427 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	7428 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	7429 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	7430 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7434 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	7435 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	7436 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	7437 after the two indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7442 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7443 <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	7444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7446 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7447 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	7448 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	7449 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	7450 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	7451 <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	7452 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	7453 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	7454 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	7455 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	7456 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	7457 For instance, the call
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 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	7461 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7462 may produce the string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7464 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7465 "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	7466 new line"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7467 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7469 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7470 Options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7471 <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	7472 <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	7473 <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	7474 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	7475 <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	7476 expect an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7477 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	7478 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	7479 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	7480 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	7481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7483
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7486 <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	7487 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	7488 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	7489 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	7490 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	7491 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	7492 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	7493
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7496 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	7497 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	7498 printing one per line:
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7501 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	7502 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	7503 print(w)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7504 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7505 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7506 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	7507 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	7508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7509 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7510 t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7511 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	7512 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	7513 t[k] = v
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7514 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7515 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7517 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7518 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	7519 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7524 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7525 <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	7526 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	7527 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	7528 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	7529 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	7530 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	7531 <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	7532 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	7533 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	7534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7536 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7537 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	7538 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	7539 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	7540 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	7541 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	7542 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	7543 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	7544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7547 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	7548 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	7549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7551 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7552 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	7553 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	7554 in order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7555
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7558 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7559 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	7560 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	7561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7563 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7564 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	7565 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	7566 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	7567 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	7568 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	7569 (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	7570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7572 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7573 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7575 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7576 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	7577 --> 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	7578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7579 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	7580 --> x="hello hello world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7582 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	7583 --> 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	7584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7585 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	7586 --> 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	7587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7588 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	7589 return load(s)()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7590 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7591 --> x="4+5 = 9"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7593 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	7594 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	7595 --> 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	7596 </pre>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7600 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7601 <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	7602 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	7603 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	7604 Embedded zeros are counted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7605 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	7606
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7611 <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	7612 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	7613 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	7614 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	7615 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	7616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7617
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7621 <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	7622 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	7623 <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	7624 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	7625 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	7626 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	7627 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	7628 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	7629 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	7630 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	7631 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	7632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7636 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7637 <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	7638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7640 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7641 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	7642 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	7643 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	7644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7649 <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	7650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7653 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	7654 with the given format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7655 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	7656 '<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	7657
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7661 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7662 <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	7663 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	7664 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	7665 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	7666 (that is, no separator).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7667 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7672 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7673 <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	7674 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	7675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7676
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7680 <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	7681 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	7682 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	7683 <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	7684 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	7685 (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	7686 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7687 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	7688 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	7689 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	7690 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	7691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7693 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7694 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	7695 <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	7696 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	7697 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	7698 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	7699 If, after these corrections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7700 <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	7701 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	7702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7706 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7707 <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	7708
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7711 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	7712 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	7713 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	7714 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	7715 After the read values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7716 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	7717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7718
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7721 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7722 <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	7723 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	7724 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	7725 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	7726 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	7727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7728
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7732 <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	7733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7734 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7735 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	7736 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	7737 <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	7738 <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	7739 <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	7740 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	7741 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	7742 (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	7743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7744
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7746 <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	7747 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	7748 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	7749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7750 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7752 <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	7753 (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	7754 <code>^$()%.[]*+-?</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7755 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	7756 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7758 <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	7759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7760 <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	7761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7762 <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	7763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7764 <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	7765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7766 <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	7767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7768 <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	7769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7770 <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	7771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7772 <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	7773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7774 <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	7775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7776 <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	7777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7778 <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	7779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7780 <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	7781 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	7782 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	7783 Any non-alphanumeric character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7784 (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	7785 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	7786 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	7787 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7789 <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	7790 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	7791 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	7792 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	7793 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	7794 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	7795 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	7796 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	7797 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	7798 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	7799 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	7800 <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	7801 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	7802 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	7803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7805 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7806 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	7807 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	7808 have no meaning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7809 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7811 <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	7812 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	7813 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	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 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7817 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	7818 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	7819 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	7820
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7823 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	7824 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	7825 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	7826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7831 <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	7832 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	7833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7834 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7836 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7837 a single character class,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7838 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	7839 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7840
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 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	7843 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	7844 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	7845 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7848 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	7849 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	7850 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	7851 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7853 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7854 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	7855 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	7856 Unlike '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7857 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	7858 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7861 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	7862 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	7863 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	7864 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7866 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7867 <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	7868 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	7869 (see below);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7870 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7872 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7873 <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	7874 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	7875 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	7876 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	7877 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	7878 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	7879 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	7880 balanced parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7881 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7884 <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	7885 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	7886 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	7887 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	7888 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	7889 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	7890 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	7891 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7893 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7898 <h4>Pattern:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7899 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	7900 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	7901 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	7902 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	7903 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	7904 At other positions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7905 '<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	7906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7911 <h4>Captures:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7912 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	7913 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	7914 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	7915 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	7916 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	7917 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	7918 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	7919 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	7920 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	7921 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	7922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7924 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7925 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	7926 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	7927 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	7928 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	7929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7936 <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	7937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7938 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7939 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	7940 <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	7941 is a format string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7942 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	7943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7945 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7946 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	7947 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	7948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7949 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7950 <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	7951 <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	7952 <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	7953 <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	7954 (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	7955 <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	7956 <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	7957 <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	7958 <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	7959 <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	7960 <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	7961 <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	7962 <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	7963 <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	7964 <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	7965 (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	7966 <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	7967 (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	7968 <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	7969 <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	7970 <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	7971 <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	7972 <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	7973 <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	7974 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	7975 (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	7976 <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	7977 <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	7978 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	7979 (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	7980 <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	7981 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7982 (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	7983 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	7984 (options "<code>xX <=>!</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7985 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	7986 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	7987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7989 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7990 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	7991 <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	7992 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	7993 <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	7994 <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	7995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7997 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7998 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	7999 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8000 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	8001 and native endianness.
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 Alignment works as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8006 For each option,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8007 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	8008 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	8009 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	8010 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	8011 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	8012 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	8013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8016 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	8017 (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	8018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8019
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8025 <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	8026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8027 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8028 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	8029 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	8030 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	8031 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	8032 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	8033 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	8034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8036 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8037 Unless stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8038 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	8039 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	8040 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	8041 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	8042 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	8043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8045 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8046 <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	8047 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	8048 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	8049 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8054 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8055 <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	8056 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	8057 (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	8058 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	8059 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	8060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8065 <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	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 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	8070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8071 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8072 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	8073 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8074 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	8075 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	8076 of each character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8077 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8083 <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	8084 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	8085 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	8086 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	8087 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8093 <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	8094 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	8095 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	8096 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	8097 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	8098 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	8099
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8103 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8104 <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	8105 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	8106 <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	8107 (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	8108 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	8109 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	8110 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	8111 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	8112 <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	8113 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	8114 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	8115 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	8116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8118 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8119 As a special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8120 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	8121 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	8122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8124 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8125 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8129
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8133 <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	8134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8135 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8136 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	8137 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	8138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8141 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	8142 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	8143 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	8144 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	8145 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	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 <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	8150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8152 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8153 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	8154 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	8155 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	8156 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	8157 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	8158 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	8159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8163 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8164 <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	8165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8168 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	8169 shifting up the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8170 <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	8171 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	8172 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	8173 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	8174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8175
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8179 <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	8180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8182 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8183 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	8184 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	8185 multiple assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8186 <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	8187 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	8188 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	8189 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	8190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8194 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8195 <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	8196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8198 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8199 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	8200 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	8201 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8206 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8207 <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	8208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8210 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8211 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	8212 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	8213 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	8214 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	8215 <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	8216 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	8217 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	8218 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	8219 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8223 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	8224 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	8225 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	8226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8230 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8231 <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	8232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8235 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	8236 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	8237 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	8238 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	8239 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	8240 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	8241 (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	8242 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	8243 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8247 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	8248 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	8249 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	8250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8252
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8255 <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	8256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8258 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8259 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	8260 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	8261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8262 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8263 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	8264 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8265 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	8266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8268
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
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 <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	8274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8275 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8276 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	8277 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	8278 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	8279 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	8280 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	8281 Rounding functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8282 (<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	8283 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	8284 or a float otherwise.
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.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	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 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	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.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	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 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	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.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	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 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	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.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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8323 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	8324 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	8325 quadrant of the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8326 (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	8327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8329 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8330 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	8331 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	8332 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	8333
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8338 <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	8339
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8342 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	8343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8344
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8348 <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	8349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8351 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8352 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	8353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8355
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8358 <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	8359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8362 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	8363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8367 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8368 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8372 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	8373 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8378 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8379 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8383 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	8384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8385
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8389 <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	8390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8392 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8393 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	8394 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	8395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8396
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8400 <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	8401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8403 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8404 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	8405 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8410 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8411 <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	8412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8414 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8415 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	8416 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	8417 (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	8418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8420
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8423 <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	8424
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8427 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	8428 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	8429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8430
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 <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	8435 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8440 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8441 <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	8442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8444 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8445 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	8446 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	8447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8451 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8452 <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	8453 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	8454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8458 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8459 <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	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 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	8464 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	8465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8469 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8470 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8474 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	8475
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8479 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8480 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8484 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	8485
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8489 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8490 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8494 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8495 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	8496 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	8497 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	8498 <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	8499 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	8500 (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	8501 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8505 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	8506 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	8507 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	8508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8512 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8513 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8517 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	8518 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	8519 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	8520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8524 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8525 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8529 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	8530
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8534 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8535 <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	8536
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8539 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	8540 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8545 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8546 <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	8547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8549 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8550 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	8551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8552
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 <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	8557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8560 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	8561 returns that integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8562 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	8563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8567 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8568 <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	8569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8572 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	8573 "<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	8574 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	8575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8579 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8580 <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	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 Returns a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8585 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	8586 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	8587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8589
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 <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	8595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8596 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8597 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	8598 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	8599 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	8600 default output file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8601 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	8602 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	8603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8605 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8606 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	8607 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	8608 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	8609 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	8610 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	8611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8613 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8614 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	8615 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	8616 <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	8617 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	8618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8620 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8621 Unless otherwise stated,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8622 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	8623 (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	8624 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	8625 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	8626 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8627 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	8628 in case of errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8629 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	8630 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	8631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8633 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8634 <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	8635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8637 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8638 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	8639 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	8640
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8644 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8645 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8649 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	8650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8651
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 <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	8656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8658 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8659 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	8660 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	8661 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	8662 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	8663 When called without parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8664 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	8665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8667 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8668 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	8669 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	8670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8674 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8675 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8679 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	8680 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	8681 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	8682 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	8683 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	8684
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8687 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	8688 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	8689 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	8690 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	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 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	8695 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8700 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8701 <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	8702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8704 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8705 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	8706 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	8707 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	8708 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	8709
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8712 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	8713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8714 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8715 <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	8716 <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	8717 <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	8718 <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	8719 <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	8720 <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	8721 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	8722 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8723 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	8724 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	8725
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8730 <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	8731
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8734 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	8735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8739 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8740 <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	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 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	8745 on all platforms.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8748 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8749 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	8750 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	8751 (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	8752 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	8753 (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	8754
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8758 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8759 <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	8760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8763 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	8764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8768 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8769 <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	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 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	8774 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	8775 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	8776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8777
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8781 <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	8782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8784 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8785 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	8786 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	8787 <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	8788 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	8789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8793 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8794 <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	8795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8797 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8798 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	8799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8800
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 <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	8805
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8808 Closes <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8809 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	8810 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	8811 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	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 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	8816 <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	8817 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	8818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8822 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8823 <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	8824
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8827 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	8828
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
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8833 <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	8834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8836 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8837 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	8838 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	8839 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	8840 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	8841 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	8842 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	8843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8844 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8845 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	8846 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8847 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	8848 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 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	8850 when the loop ends.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8853 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8854 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	8855 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	8856
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8860 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8861 <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	8862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8864 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8865 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	8866 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	8867 For each format,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8868 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	8869 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	8870 (In this latter case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8871 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	8872 When called without formats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8873 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	8874 (see below).
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 The available formats are
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 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8882 <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	8883 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	8884 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	8885 (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	8886 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	8887 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	8888 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	8889 (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	8890 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	8891 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8893 <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	8894 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	8895 </li>
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 <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	8898 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	8899 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	8900 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8902 <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	8903 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	8904 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	8905 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	8906 </li>
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 <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	8909 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	8910 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	8911 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8913 <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	8914 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	8915 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	8916 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	8917 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	8918 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	8919 </li>
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 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8922 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	8923
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8927 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8928 <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	8929
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8932 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	8933 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	8934 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	8935 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	8936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8937 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8938 <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	8939 <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	8940 <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	8941 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8942 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	8943 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	8944 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	8945 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	8946
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8949 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	8950 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	8951 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	8952 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	8953 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	8954 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	8955 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	8956 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8962 <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	8963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8965 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8966 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	8967 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	8968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8969 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8971 <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	8972 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	8973 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8975 <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	8976 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	8977 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	8978 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	8979 </li>
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 <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	8982 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	8983 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	8984 (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	8985 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8987 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8988 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	8989 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	8990 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	8991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8995 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8996 <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	8997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8999 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9000 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	9001 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	9002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9005 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	9006 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	9007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9009
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9014 <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	9015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9016 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9017 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	9018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9020 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9021 <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	9022
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9025 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	9026 used by the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9028
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9032 <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	9033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9035 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9036 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	9037 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	9038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9040 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9041 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	9042 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	9043 (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	9044 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	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 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	9049 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	9050 After this optional character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9051 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	9052 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	9053 <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	9054 <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	9055 <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	9056 <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	9057 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	9058 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	9059 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	9060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9063 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	9064 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	9065 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	9066
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9069 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9070 <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	9071 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	9072 (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	9073
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 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9077 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	9078 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9083 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9084 <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	9085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9087 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9088 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	9089 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	9090 (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	9091 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	9092 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	9093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9094
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 <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	9099
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9102 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	9103 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	9104 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	9105 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	9106 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	9107 After this first result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9108 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	9109 as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9111 <ul>
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 <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	9114 the command terminated normally;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9115 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	9116 </li>
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 <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	9119 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	9120 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	9121 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9123 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9126 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	9127 <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	9128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9129
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 <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	9134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9136 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9137 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	9138 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	9139 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	9140 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	9141 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	9142 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	9143 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	9144 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	9145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9147 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9148 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	9149 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	9150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9152
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9155 <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	9156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9157
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9158 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9159 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	9160 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	9161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9165 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9166 <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	9167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9169 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9170 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	9171 with the given name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9172 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	9173 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	9174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9176
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9179 <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	9180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9182 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9183 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	9184 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	9185 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	9186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9188
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9191 <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	9192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9194 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9195 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	9196 <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	9197 <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	9198 <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	9199 <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	9200 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	9201 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	9202 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	9203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9205 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9206 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	9207 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	9208 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	9209 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	9210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9213 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	9214 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	9215 for the given category.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9218 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9219 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	9220 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	9221
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9225 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9226 <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	9227
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9230 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	9231 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	9232 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	9233 and may have fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9234 <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	9235 <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	9236 <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	9237 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	9238 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	9239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9242 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	9243 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	9244 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	9245 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	9246 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	9247 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	9248 <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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9253 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9254 <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	9255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9257 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9258 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	9259 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	9260 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	9261 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	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 On POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9266 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	9267 to avoid security risks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9268 (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	9269 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	9270 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	9271 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	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 When possible,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9276 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	9277 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9282
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 <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	9286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9287 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9288 This library provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9289 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	9290 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	9291 Several of its functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9292 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	9293 (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	9294 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	9295 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	9296 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	9297 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	9298 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	9299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9302 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	9303 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	9304 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	9305 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	9306 thread to operate over.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9307 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	9308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9310 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9311 <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	9312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9314 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9315 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	9316 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	9317 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	9318 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	9319 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	9320 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	9321 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	9322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9324 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9325 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	9326 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	9327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9331 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9332 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9336 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	9337 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	9338 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	9339 (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	9340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9344 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9345 <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	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 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	9350 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	9351 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	9352 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	9353 of the given thread:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9354 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	9355 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	9356 (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	9357 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9358 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	9359 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	9360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9362 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9363 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	9364 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	9365 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	9366 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	9367 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9368 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	9369 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	9370 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9371 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	9372 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	9373 valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9376 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9377 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	9378 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	9379 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	9380 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	9381 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	9382 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9387 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9388 <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	9389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9391 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9392 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	9393 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	9394 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	9395 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	9396
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9399 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	9400 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	9401 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	9402 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	9403 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	9404 -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	9405 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	9406 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	9407 (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	9408
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9411 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	9412 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	9413 (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	9414 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	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 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	9419 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	9420
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9425 <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	9426
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9429 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	9430 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	9431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9436 <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	9437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9439 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9440 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	9441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9443
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9446 <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	9447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9449 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9450 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	9451 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	9452 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	9453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9456 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	9457 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	9458 (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	9459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9463 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9464 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9468 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	9469 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	9470 returns <b>nil</b>.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9475 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9476 <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	9477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9479 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9480 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	9481 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	9482 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	9483 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	9484 with the given meaning:
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 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9487 <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	9488 <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	9489 <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	9490 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9491 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9492 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	9493 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	9494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9496 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9497 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9498 <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	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 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	9503 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	9504 <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	9505 <code>"return"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9506 <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	9507 For line events,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9508 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	9509 Inside a hook,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9510 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	9511 the running function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9512 (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	9513 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	9514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9516
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9519 <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	9520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9522 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9523 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	9524 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	9525 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	9526 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	9527 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	9528 (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	9529 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	9530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9532 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9533 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	9534 variable indices and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9539 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9540 <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	9541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9543 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9544 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	9545 (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	9546 Returns <code>value</code>.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9551 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9552 <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	9553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9555 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9556 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	9557 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	9558 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	9559 with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9560 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	9561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9565 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9566 <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	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 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	9571 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	9572 <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	9573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9575 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9576 Returns <code>udata</code>.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9582 <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	9583
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 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	9587 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	9588 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9589 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	9590 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	9591 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	9592 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	9593 to start the traceback
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9594 (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	9595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9599 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9600 <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	9601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9603 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9604 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	9605 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	9606 from the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9609 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9610 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	9611 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9612 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	9613 (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	9614 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9619 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9620 <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	9621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9623 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9624 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	9625 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	9626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9633 <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	9634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9635 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9636 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	9637 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	9638 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	9639 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	9640 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	9641 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	9642 The standalone interpreter includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9643 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	9644 Its usage is:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9646 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9647 lua [options] [script [args]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9648 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9649 The options are:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9651 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9652 <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	9653 <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	9654 <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	9655 <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	9656 <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	9657 <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	9658 <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	9659 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9660 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	9661 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9662 <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	9663 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	9664 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	9665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9667 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9668 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	9669 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	9670 (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	9671 before running any argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9672 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	9673 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	9674 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	9675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9677 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9678 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	9679 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	9680 Lua also ignores
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9681 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	9682 setting the values of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9683 <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	9684 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	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 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	9689 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	9690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9691 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9692 $ 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	9693 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9694 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	9695 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	9696 (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	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 Before running any code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9701 <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	9702 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	9703 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	9704 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	9705 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9706 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	9707 (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	9708 go to negative indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9709 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	9710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9711 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9712 $ 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	9713 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9714 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	9715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9716 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9717 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	9718 [0] = "b.lua",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9719 [1] = "t1", [2] = "t2" }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9720 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9721 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	9722 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	9723 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	9724 For instance, the call
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 $ 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	9728 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9729 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	9730 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	9731 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	9732 <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	9733 (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	9734 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	9735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9738 In interactive mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9739 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	9740 After reading a line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9741 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	9742 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	9743 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	9744 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	9745 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	9746 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	9747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9749 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9750 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	9751 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	9752 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	9753 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	9754 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	9755 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	9756 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	9757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9759 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9760 When finishing normally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9761 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	9762 (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	9763 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	9764 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	9765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9767 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9768 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	9769 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	9770 the standalone interpreter skips
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9771 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	9772 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	9773 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	9774 as in
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9777 #!/usr/local/bin/lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9778 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9779 (Of course,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9780 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	9781 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	9782 then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9784 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9785 #!/usr/bin/env lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9786 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9787 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	9788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9791 <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	9792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9793 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9794 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	9795 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	9796 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	9797 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	9798 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9799 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	9800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9802 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9803 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	9804 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	9805 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	9806 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	9807 Therefore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9808 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	9809 different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9810 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	9811 using a new version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9814 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9815 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	9816 of precompiled chunks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9817 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	9818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9820 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9821 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	9822 change between versions.
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.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	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 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	9831 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	9832 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	9833 some computations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9834 (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	9835 can give different results.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9839 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	9840 (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	9841 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	9842 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	9843 (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	9844 for an occasional incompatibility;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9845 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	9846 For good programming,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9847 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	9848 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	9849 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9851 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9852 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	9853 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	9854 (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	9855 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	9856 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	9857 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	9858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9860 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9861 (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	9862 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	9863 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	9864 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9866 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9867 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	9868 (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	9869 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9871 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9874
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 <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	9877 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9880 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	9881 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	9882 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	9883 (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	9884 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	9885 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9887 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9888 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	9889 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	9890 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9892 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9893 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	9894 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	9895 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9897 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9898 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	9899 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	9900 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9902 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9903 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	9904 <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	9905 <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	9906 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	9907 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	9908 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	9909 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	9910 For the other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9911 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	9912 implement them in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9913 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9915 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9916 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	9917 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	9918 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	9919 (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	9920 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	9921 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	9922 (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	9923 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	9924 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9926 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9929
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 <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	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 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9937 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	9938 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	9939 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	9940 Adapt your code accordingly.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9941 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9943 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9944 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	9945 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	9946 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9948 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9949 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	9950 (<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	9951 <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	9952 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9953 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	9954 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9957 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	9958 (<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	9959 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9960 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	9961 (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	9962 </li>
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 </ul>
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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9969 <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	9970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9971 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9972 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	9973 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	9974 {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	9975 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	9976 (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	9977 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	9978 Name, Numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9979 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	9980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9981
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9984 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9986 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9988 block ::= {stat} [retstat]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9990 stat ::= ‘<b>;</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9991 varlist ‘<b>=</b>’ explist \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9992 functioncall \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9993 label \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9994 <b>break</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9995 <b>goto</b> Name \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9996 <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	9997 <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	9998 <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	9999 <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	10000 <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	10001 <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	10002 <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	10003 <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	10004 <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	10005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10006 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	10007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10008 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	10009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10010 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	10011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10012 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	10013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10014 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	10015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10016 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	10017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10018 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	10019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10020 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	10021 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	10022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10023 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	10024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10025 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	10026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10027 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	10028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10029 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	10030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10031 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	10032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10033 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	10034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10035 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	10036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10037 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	10038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10039 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	10040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10041 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	10042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10043 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	10044 ‘<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	10045 ‘<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	10046 <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	10047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10048 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	10049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10050 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10052 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10061 <HR>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10062 <SMALL CLASS="footer">
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10063 Last update:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10064 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	10065 </SMALL>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10066 <!--
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10067 Last change: minor edit
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10068 -->
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10069
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10070 </div>
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	10071
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	10072 <% 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	10073 </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	10074 </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	10075 <%
386 db23f654f87d make all of website use luan Franklin Schmidt <fschmidt@gmail.com> parents: 382 diff changeset	10076 end

Mercurial Hosting > luan

annotate website/src/manual.html.luan @ 395:a7cb58532846