1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<title>Lua 5.1 Reference Manual</title> 6<link rel="stylesheet" type="text/css" href="lua.css"> 7<link rel="stylesheet" type="text/css" href="manual.css"> 8<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 9</head> 10 11<body> 12 13<hr> 14<h1> 15<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a> 16Lua 5.1 Reference Manual 17</h1> 18 19by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 20<p> 21<small> 22Copyright © 2006-2008 Lua.org, PUC-Rio. 23Freely available under the terms of the 24<a href="http://www.lua.org/license.html#5">Lua license</a>. 25</small> 26<hr> 27<p> 28 29<a href="contents.html#contents">contents</A> 30· 31<a href="contents.html#index">index</A> 32 33<!-- ====================================================================== --> 34<p> 35 36<!-- $Id: manual.html,v 1.1.1.1 2010/10/31 11:16:53 mbalmer Exp $ --> 37 38 39 40 41<h1>1 - <a name="1">Introduction</a></h1> 42 43<p> 44Lua is an extension programming language designed to support 45general procedural programming with data description 46facilities. 47It also offers good support for object-oriented programming, 48functional programming, and data-driven programming. 49Lua is intended to be used as a powerful, light-weight 50scripting language for any program that needs one. 51Lua is implemented as a library, written in <em>clean</em> C 52(that is, in the common subset of ANSI C and C++). 53 54 55<p> 56Being an extension language, Lua has no notion of a "main" program: 57it only works <em>embedded</em> in a host client, 58called the <em>embedding program</em> or simply the <em>host</em>. 59This host program can invoke functions to execute a piece of Lua code, 60can write and read Lua variables, 61and can register C functions to be called by Lua code. 62Through the use of C functions, Lua can be augmented to cope with 63a wide range of different domains, 64thus creating customized programming languages sharing a syntactical framework. 65The Lua distribution includes a sample host program called <code>lua</code>, 66which uses the Lua library to offer a complete, stand-alone Lua interpreter. 67 68 69<p> 70Lua is free software, 71and is provided as usual with no guarantees, 72as stated in its license. 73The implementation described in this manual is available 74at Lua's official web site, <code>www.lua.org</code>. 75 76 77<p> 78Like any other reference manual, 79this document is dry in places. 80For a discussion of the decisions behind the design of Lua, 81see the technical papers available at Lua's web site. 82For a detailed introduction to programming in Lua, 83see Roberto's book, <em>Programming in Lua (Second Edition)</em>. 84 85 86 87<h1>2 - <a name="2">The Language</a></h1> 88 89<p> 90This section describes the lexis, the syntax, and the semantics of Lua. 91In other words, 92this section describes 93which tokens are valid, 94how they can be combined, 95and what their combinations mean. 96 97 98<p> 99The language constructs will be explained using the usual extended BNF notation, 100in which 101{<em>a</em>} means 0 or more <em>a</em>'s, and 102[<em>a</em>] means an optional <em>a</em>. 103Non-terminals are shown like non-terminal, 104keywords are shown like <b>kword</b>, 105and other terminal symbols are shown like `<b>=</b>´. 106The complete syntax of Lua can be found in <a href="#8">§8</a> 107at the end of this manual. 108 109 110 111<h2>2.1 - <a name="2.1">Lexical Conventions</a></h2> 112 113<p> 114<em>Names</em> 115(also called <em>identifiers</em>) 116in Lua can be any string of letters, 117digits, and underscores, 118not beginning with a digit. 119This coincides with the definition of names in most languages. 120(The definition of letter depends on the current locale: 121any character considered alphabetic by the current locale 122can be used in an identifier.) 123Identifiers are used to name variables and table fields. 124 125 126<p> 127The following <em>keywords</em> are reserved 128and cannot be used as names: 129 130 131<pre> 132 and break do else elseif 133 end false for function if 134 in local nil not or 135 repeat return then true until while 136</pre> 137 138<p> 139Lua is a case-sensitive language: 140<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 141are two different, valid names. 142As a convention, names starting with an underscore followed by 143uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) 144are reserved for internal global variables used by Lua. 145 146 147<p> 148The following strings denote other tokens: 149 150<pre> 151 + - * / % ^ # 152 == ~= <= >= < > = 153 ( ) { } [ ] 154 ; : , . .. ... 155</pre> 156 157<p> 158<em>Literal strings</em> 159can be delimited by matching single or double quotes, 160and can contain the following C-like escape sequences: 161'<code>\a</code>' (bell), 162'<code>\b</code>' (backspace), 163'<code>\f</code>' (form feed), 164'<code>\n</code>' (newline), 165'<code>\r</code>' (carriage return), 166'<code>\t</code>' (horizontal tab), 167'<code>\v</code>' (vertical tab), 168'<code>\\</code>' (backslash), 169'<code>\"</code>' (quotation mark [double quote]), 170and '<code>\'</code>' (apostrophe [single quote]). 171Moreover, a backslash followed by a real newline 172results in a newline in the string. 173A character in a string can also be specified by its numerical value 174using the escape sequence <code>\<em>ddd</em></code>, 175where <em>ddd</em> is a sequence of up to three decimal digits. 176(Note that if a numerical escape is to be followed by a digit, 177it must be expressed using exactly three digits.) 178Strings in Lua can contain any 8-bit value, including embedded zeros, 179which can be specified as '<code>\0</code>'. 180 181 182<p> 183Literal strings can also be defined using a long format 184enclosed by <em>long brackets</em>. 185We define an <em>opening long bracket of level <em>n</em></em> as an opening 186square bracket followed by <em>n</em> equal signs followed by another 187opening square bracket. 188So, an opening long bracket of level 0 is written as <code>[[</code>, 189an opening long bracket of level 1 is written as <code>[=[</code>, 190and so on. 191A <em>closing long bracket</em> is defined similarly; 192for instance, a closing long bracket of level 4 is written as <code>]====]</code>. 193A long string starts with an opening long bracket of any level and 194ends at the first closing long bracket of the same level. 195Literals in this bracketed form can run for several lines, 196do not interpret any escape sequences, 197and ignore long brackets of any other level. 198They can contain anything except a closing bracket of the proper level. 199 200 201<p> 202For convenience, 203when the opening long bracket is immediately followed by a newline, 204the newline is not included in the string. 205As an example, in a system using ASCII 206(in which '<code>a</code>' is coded as 97, 207newline is coded as 10, and '<code>1</code>' is coded as 49), 208the five literal strings below denote the same string: 209 210<pre> 211 a = 'alo\n123"' 212 a = "alo\n123\"" 213 a = '\97lo\10\04923"' 214 a = [[alo 215 123"]] 216 a = [==[ 217 alo 218 123"]==] 219</pre> 220 221<p> 222A <em>numerical constant</em> can be written with an optional decimal part 223and an optional decimal exponent. 224Lua also accepts integer hexadecimal constants, 225by prefixing them with <code>0x</code>. 226Examples of valid numerical constants are 227 228<pre> 229 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 230</pre> 231 232<p> 233A <em>comment</em> starts with a double hyphen (<code>--</code>) 234anywhere outside a string. 235If the text immediately after <code>--</code> is not an opening long bracket, 236the comment is a <em>short comment</em>, 237which runs until the end of the line. 238Otherwise, it is a <em>long comment</em>, 239which runs until the corresponding closing long bracket. 240Long comments are frequently used to disable code temporarily. 241 242 243 244 245 246<h2>2.2 - <a name="2.2">Values and Types</a></h2> 247 248<p> 249Lua is a <em>dynamically typed language</em>. 250This means that 251variables do not have types; only values do. 252There are no type definitions in the language. 253All values carry their own type. 254 255 256<p> 257All values in Lua are <em>first-class values</em>. 258This means that all values can be stored in variables, 259passed as arguments to other functions, and returned as results. 260 261 262<p> 263There are eight basic types in Lua: 264<em>nil</em>, <em>boolean</em>, <em>number</em>, 265<em>string</em>, <em>function</em>, <em>userdata</em>, 266<em>thread</em>, and <em>table</em>. 267<em>Nil</em> is the type of the value <b>nil</b>, 268whose main property is to be different from any other value; 269it usually represents the absence of a useful value. 270<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. 271Both <b>nil</b> and <b>false</b> make a condition false; 272any other value makes it true. 273<em>Number</em> represents real (double-precision floating-point) numbers. 274(It is easy to build Lua interpreters that use other 275internal representations for numbers, 276such as single-precision float or long integers; 277see file <code>luaconf.h</code>.) 278<em>String</em> represents arrays of characters. 279 280Lua is 8-bit clean: 281strings can contain any 8-bit character, 282including embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>). 283 284 285<p> 286Lua can call (and manipulate) functions written in Lua and 287functions written in C 288(see <a href="#2.5.8">§2.5.8</a>). 289 290 291<p> 292The type <em>userdata</em> is provided to allow arbitrary C data to 293be stored in Lua variables. 294This type corresponds to a block of raw memory 295and has no pre-defined operations in Lua, 296except assignment and identity test. 297However, by using <em>metatables</em>, 298the programmer can define operations for userdata values 299(see <a href="#2.8">§2.8</a>). 300Userdata values cannot be created or modified in Lua, 301only through the C API. 302This guarantees the integrity of data owned by the host program. 303 304 305<p> 306The type <em>thread</em> represents independent threads of execution 307and it is used to implement coroutines (see <a href="#2.11">§2.11</a>). 308Do not confuse Lua threads with operating-system threads. 309Lua supports coroutines on all systems, 310even those that do not support threads. 311 312 313<p> 314The type <em>table</em> implements associative arrays, 315that is, arrays that can be indexed not only with numbers, 316but with any value (except <b>nil</b>). 317Tables can be <em>heterogeneous</em>; 318that is, they can contain values of all types (except <b>nil</b>). 319Tables are the sole data structuring mechanism in Lua; 320they can be used to represent ordinary arrays, 321symbol tables, sets, records, graphs, trees, etc. 322To represent records, Lua uses the field name as an index. 323The language supports this representation by 324providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 325There are several convenient ways to create tables in Lua 326(see <a href="#2.5.7">§2.5.7</a>). 327 328 329<p> 330Like indices, 331the value of a table field can be of any type (except <b>nil</b>). 332In particular, 333because functions are first-class values, 334table fields can contain functions. 335Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>). 336 337 338<p> 339Tables, functions, threads, and (full) userdata values are <em>objects</em>: 340variables do not actually <em>contain</em> these values, 341only <em>references</em> to them. 342Assignment, parameter passing, and function returns 343always manipulate references to such values; 344these operations do not imply any kind of copy. 345 346 347<p> 348The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 349of a given value. 350 351 352 353<h3>2.2.1 - <a name="2.2.1">Coercion</a></h3> 354 355<p> 356Lua provides automatic conversion between 357string and number values at run time. 358Any arithmetic operation applied to a string tries to convert 359this string to a number, following the usual conversion rules. 360Conversely, whenever a number is used where a string is expected, 361the number is converted to a string, in a reasonable format. 362For complete control over how numbers are converted to strings, 363use the <code>format</code> function from the string library 364(see <a href="#pdf-string.format"><code>string.format</code></a>). 365 366 367 368 369 370 371 372<h2>2.3 - <a name="2.3">Variables</a></h2> 373 374<p> 375Variables are places that store values. 376 377There are three kinds of variables in Lua: 378global variables, local variables, and table fields. 379 380 381<p> 382A single name can denote a global variable or a local variable 383(or a function's formal parameter, 384which is a particular kind of local variable): 385 386<pre> 387 var ::= Name 388</pre><p> 389Name denotes identifiers, as defined in <a href="#2.1">§2.1</a>. 390 391 392<p> 393Any variable is assumed to be global unless explicitly declared 394as a local (see <a href="#2.4.7">§2.4.7</a>). 395Local variables are <em>lexically scoped</em>: 396local variables can be freely accessed by functions 397defined inside their scope (see <a href="#2.6">§2.6</a>). 398 399 400<p> 401Before the first assignment to a variable, its value is <b>nil</b>. 402 403 404<p> 405Square brackets are used to index a table: 406 407<pre> 408 var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´ 409</pre><p> 410The meaning of accesses to global variables 411and table fields can be changed via metatables. 412An access to an indexed variable <code>t[i]</code> is equivalent to 413a call <code>gettable_event(t,i)</code>. 414(See <a href="#2.8">§2.8</a> for a complete description of the 415<code>gettable_event</code> function. 416This function is not defined or callable in Lua. 417We use it here only for explanatory purposes.) 418 419 420<p> 421The syntax <code>var.Name</code> is just syntactic sugar for 422<code>var["Name"]</code>: 423 424<pre> 425 var ::= prefixexp `<b>.</b>´ Name 426</pre> 427 428<p> 429All global variables live as fields in ordinary Lua tables, 430called <em>environment tables</em> or simply 431<em>environments</em> (see <a href="#2.9">§2.9</a>). 432Each function has its own reference to an environment, 433so that all global variables in this function 434will refer to this environment table. 435When a function is created, 436it inherits the environment from the function that created it. 437To get the environment table of a Lua function, 438you call <a href="#pdf-getfenv"><code>getfenv</code></a>. 439To replace it, 440you call <a href="#pdf-setfenv"><code>setfenv</code></a>. 441(You can only manipulate the environment of C functions 442through the debug library; (see <a href="#5.9">§5.9</a>).) 443 444 445<p> 446An access to a global variable <code>x</code> 447is equivalent to <code>_env.x</code>, 448which in turn is equivalent to 449 450<pre> 451 gettable_event(_env, "x") 452</pre><p> 453where <code>_env</code> is the environment of the running function. 454(See <a href="#2.8">§2.8</a> for a complete description of the 455<code>gettable_event</code> function. 456This function is not defined or callable in Lua. 457Similarly, the <code>_env</code> variable is not defined in Lua. 458We use them here only for explanatory purposes.) 459 460 461 462 463 464<h2>2.4 - <a name="2.4">Statements</a></h2> 465 466<p> 467Lua supports an almost conventional set of statements, 468similar to those in Pascal or C. 469This set includes 470assignments, control structures, function calls, 471and variable declarations. 472 473 474 475<h3>2.4.1 - <a name="2.4.1">Chunks</a></h3> 476 477<p> 478The unit of execution of Lua is called a <em>chunk</em>. 479A chunk is simply a sequence of statements, 480which are executed sequentially. 481Each statement can be optionally followed by a semicolon: 482 483<pre> 484 chunk ::= {stat [`<b>;</b>´]} 485</pre><p> 486There are no empty statements and thus '<code>;;</code>' is not legal. 487 488 489<p> 490Lua handles a chunk as the body of an anonymous function 491with a variable number of arguments 492(see <a href="#2.5.9">§2.5.9</a>). 493As such, chunks can define local variables, 494receive arguments, and return values. 495 496 497<p> 498A chunk can be stored in a file or in a string inside the host program. 499To execute a chunk, 500Lua first pre-compiles the chunk into instructions for a virtual machine, 501and then it executes the compiled code 502with an interpreter for the virtual machine. 503 504 505<p> 506Chunks can also be pre-compiled into binary form; 507see program <code>luac</code> for details. 508Programs in source and compiled forms are interchangeable; 509Lua automatically detects the file type and acts accordingly. 510 511 512 513 514 515 516<h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p> 517A block is a list of statements; 518syntactically, a block is the same as a chunk: 519 520<pre> 521 block ::= chunk 522</pre> 523 524<p> 525A block can be explicitly delimited to produce a single statement: 526 527<pre> 528 stat ::= <b>do</b> block <b>end</b> 529</pre><p> 530Explicit blocks are useful 531to control the scope of variable declarations. 532Explicit blocks are also sometimes used to 533add a <b>return</b> or <b>break</b> statement in the middle 534of another block (see <a href="#2.4.4">§2.4.4</a>). 535 536 537 538 539 540<h3>2.4.3 - <a name="2.4.3">Assignment</a></h3> 541 542<p> 543Lua allows multiple assignments. 544Therefore, the syntax for assignment 545defines a list of variables on the left side 546and a list of expressions on the right side. 547The elements in both lists are separated by commas: 548 549<pre> 550 stat ::= varlist `<b>=</b>´ explist 551 varlist ::= var {`<b>,</b>´ var} 552 explist ::= exp {`<b>,</b>´ exp} 553</pre><p> 554Expressions are discussed in <a href="#2.5">§2.5</a>. 555 556 557<p> 558Before the assignment, 559the list of values is <em>adjusted</em> to the length of 560the list of variables. 561If there are more values than needed, 562the excess values are thrown away. 563If there are fewer values than needed, 564the list is extended with as many <b>nil</b>'s as needed. 565If the list of expressions ends with a function call, 566then all values returned by that call enter the list of values, 567before the adjustment 568(except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>). 569 570 571<p> 572The assignment statement first evaluates all its expressions 573and only then are the assignments performed. 574Thus the code 575 576<pre> 577 i = 3 578 i, a[i] = i+1, 20 579</pre><p> 580sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 581because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 582before it is assigned 4. 583Similarly, the line 584 585<pre> 586 x, y = y, x 587</pre><p> 588exchanges the values of <code>x</code> and <code>y</code>, 589and 590 591<pre> 592 x, y, z = y, z, x 593</pre><p> 594cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 595 596 597<p> 598The meaning of assignments to global variables 599and table fields can be changed via metatables. 600An assignment to an indexed variable <code>t[i] = val</code> is equivalent to 601<code>settable_event(t,i,val)</code>. 602(See <a href="#2.8">§2.8</a> for a complete description of the 603<code>settable_event</code> function. 604This function is not defined or callable in Lua. 605We use it here only for explanatory purposes.) 606 607 608<p> 609An assignment to a global variable <code>x = val</code> 610is equivalent to the assignment 611<code>_env.x = val</code>, 612which in turn is equivalent to 613 614<pre> 615 settable_event(_env, "x", val) 616</pre><p> 617where <code>_env</code> is the environment of the running function. 618(The <code>_env</code> variable is not defined in Lua. 619We use it here only for explanatory purposes.) 620 621 622 623 624 625<h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p> 626The control structures 627<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 628familiar syntax: 629 630 631 632 633<pre> 634 stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 635 stat ::= <b>repeat</b> block <b>until</b> exp 636 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 637</pre><p> 638Lua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>). 639 640 641<p> 642The condition expression of a 643control structure can return any value. 644Both <b>false</b> and <b>nil</b> are considered false. 645All values different from <b>nil</b> and <b>false</b> are considered true 646(in particular, the number 0 and the empty string are also true). 647 648 649<p> 650In the <b>repeat</b>–<b>until</b> loop, 651the inner block does not end at the <b>until</b> keyword, 652but only after the condition. 653So, the condition can refer to local variables 654declared inside the loop block. 655 656 657<p> 658The <b>return</b> statement is used to return values 659from a function or a chunk (which is just a function). 660 661Functions and chunks can return more than one value, 662and so the syntax for the <b>return</b> statement is 663 664<pre> 665 stat ::= <b>return</b> [explist] 666</pre> 667 668<p> 669The <b>break</b> statement is used to terminate the execution of a 670<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 671skipping to the next statement after the loop: 672 673 674<pre> 675 stat ::= <b>break</b> 676</pre><p> 677A <b>break</b> ends the innermost enclosing loop. 678 679 680<p> 681The <b>return</b> and <b>break</b> 682statements can only be written as the <em>last</em> statement of a block. 683If it is really necessary to <b>return</b> or <b>break</b> in the 684middle of a block, 685then an explicit inner block can be used, 686as in the idioms 687<code>do return end</code> and <code>do break end</code>, 688because now <b>return</b> and <b>break</b> are the last statements in 689their (inner) blocks. 690 691 692 693 694 695<h3>2.4.5 - <a name="2.4.5">For Statement</a></h3> 696 697<p> 698 699The <b>for</b> statement has two forms: 700one numeric and one generic. 701 702 703<p> 704The numeric <b>for</b> loop repeats a block of code while a 705control variable runs through an arithmetic progression. 706It has the following syntax: 707 708<pre> 709 stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> 710</pre><p> 711The <em>block</em> is repeated for <em>name</em> starting at the value of 712the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 713third <em>exp</em>. 714More precisely, a <b>for</b> statement like 715 716<pre> 717 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 718</pre><p> 719is equivalent to the code: 720 721<pre> 722 do 723 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 724 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 725 while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do 726 local v = <em>var</em> 727 <em>block</em> 728 <em>var</em> = <em>var</em> + <em>step</em> 729 end 730 end 731</pre><p> 732Note the following: 733 734<ul> 735 736<li> 737All three control expressions are evaluated only once, 738before the loop starts. 739They must all result in numbers. 740</li> 741 742<li> 743<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 744The names shown here are for explanatory purposes only. 745</li> 746 747<li> 748If the third expression (the step) is absent, 749then a step of 1 is used. 750</li> 751 752<li> 753You can use <b>break</b> to exit a <b>for</b> loop. 754</li> 755 756<li> 757The loop variable <code>v</code> is local to the loop; 758you cannot use its value after the <b>for</b> ends or is broken. 759If you need this value, 760assign it to another variable before breaking or exiting the loop. 761</li> 762 763</ul> 764 765<p> 766The generic <b>for</b> statement works over functions, 767called <em>iterators</em>. 768On each iteration, the iterator function is called to produce a new value, 769stopping when this new value is <b>nil</b>. 770The generic <b>for</b> loop has the following syntax: 771 772<pre> 773 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 774 namelist ::= Name {`<b>,</b>´ Name} 775</pre><p> 776A <b>for</b> statement like 777 778<pre> 779 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 780</pre><p> 781is equivalent to the code: 782 783<pre> 784 do 785 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 786 while true do 787 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 788 <em>var</em> = <em>var_1</em> 789 if <em>var</em> == nil then break end 790 <em>block</em> 791 end 792 end 793</pre><p> 794Note the following: 795 796<ul> 797 798<li> 799<code><em>explist</em></code> is evaluated only once. 800Its results are an <em>iterator</em> function, 801a <em>state</em>, 802and an initial value for the first <em>iterator variable</em>. 803</li> 804 805<li> 806<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 807The names are here for explanatory purposes only. 808</li> 809 810<li> 811You can use <b>break</b> to exit a <b>for</b> loop. 812</li> 813 814<li> 815The loop variables <code><em>var_i</em></code> are local to the loop; 816you cannot use their values after the <b>for</b> ends. 817If you need these values, 818then assign them to other variables before breaking or exiting the loop. 819</li> 820 821</ul> 822 823 824 825 826<h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p> 827To allow possible side-effects, 828function calls can be executed as statements: 829 830<pre> 831 stat ::= functioncall 832</pre><p> 833In this case, all returned values are thrown away. 834Function calls are explained in <a href="#2.5.8">§2.5.8</a>. 835 836 837 838 839 840<h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p> 841Local variables can be declared anywhere inside a block. 842The declaration can include an initial assignment: 843 844<pre> 845 stat ::= <b>local</b> namelist [`<b>=</b>´ explist] 846</pre><p> 847If present, an initial assignment has the same semantics 848of a multiple assignment (see <a href="#2.4.3">§2.4.3</a>). 849Otherwise, all variables are initialized with <b>nil</b>. 850 851 852<p> 853A chunk is also a block (see <a href="#2.4.1">§2.4.1</a>), 854and so local variables can be declared in a chunk outside any explicit block. 855The scope of such local variables extends until the end of the chunk. 856 857 858<p> 859The visibility rules for local variables are explained in <a href="#2.6">§2.6</a>. 860 861 862 863 864 865 866 867<h2>2.5 - <a name="2.5">Expressions</a></h2> 868 869<p> 870The basic expressions in Lua are the following: 871 872<pre> 873 exp ::= prefixexp 874 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 875 exp ::= Number 876 exp ::= String 877 exp ::= function 878 exp ::= tableconstructor 879 exp ::= `<b>...</b>´ 880 exp ::= exp binop exp 881 exp ::= unop exp 882 prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ 883</pre> 884 885<p> 886Numbers and literal strings are explained in <a href="#2.1">§2.1</a>; 887variables are explained in <a href="#2.3">§2.3</a>; 888function definitions are explained in <a href="#2.5.9">§2.5.9</a>; 889function calls are explained in <a href="#2.5.8">§2.5.8</a>; 890table constructors are explained in <a href="#2.5.7">§2.5.7</a>. 891Vararg expressions, 892denoted by three dots ('<code>...</code>'), can only be used when 893directly inside a vararg function; 894they are explained in <a href="#2.5.9">§2.5.9</a>. 895 896 897<p> 898Binary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>), 899relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>), 900and the concatenation operator (see <a href="#2.5.4">§2.5.4</a>). 901Unary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>), 902the unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>), 903and the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>). 904 905 906<p> 907Both function calls and vararg expressions can result in multiple values. 908If an expression is used as a statement 909(only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)), 910then its return list is adjusted to zero elements, 911thus discarding all returned values. 912If an expression is used as the last (or the only) element 913of a list of expressions, 914then no adjustment is made 915(unless the call is enclosed in parentheses). 916In all other contexts, 917Lua adjusts the result list to one element, 918discarding all values except the first one. 919 920 921<p> 922Here are some examples: 923 924<pre> 925 f() -- adjusted to 0 results 926 g(f(), x) -- f() is adjusted to 1 result 927 g(x, f()) -- g gets x plus all results from f() 928 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 929 a,b = ... -- a gets the first vararg parameter, b gets 930 -- the second (both a and b can get nil if there 931 -- is no corresponding vararg parameter) 932 933 a,b,c = x, f() -- f() is adjusted to 2 results 934 a,b,c = f() -- f() is adjusted to 3 results 935 return f() -- returns all results from f() 936 return ... -- returns all received vararg parameters 937 return x,y,f() -- returns x, y, and all results from f() 938 {f()} -- creates a list with all results from f() 939 {...} -- creates a list with all vararg parameters 940 {f(), nil} -- f() is adjusted to 1 result 941</pre> 942 943<p> 944Any expression enclosed in parentheses always results in only one value. 945Thus, 946<code>(f(x,y,z))</code> is always a single value, 947even if <code>f</code> returns several values. 948(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 949or <b>nil</b> if <code>f</code> does not return any values.) 950 951 952 953<h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p> 954Lua supports the usual arithmetic operators: 955the binary <code>+</code> (addition), 956<code>-</code> (subtraction), <code>*</code> (multiplication), 957<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation); 958and unary <code>-</code> (negation). 959If the operands are numbers, or strings that can be converted to 960numbers (see <a href="#2.2.1">§2.2.1</a>), 961then all operations have the usual meaning. 962Exponentiation works for any exponent. 963For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>. 964Modulo is defined as 965 966<pre> 967 a % b == a - math.floor(a/b)*b 968</pre><p> 969That is, it is the remainder of a division that rounds 970the quotient towards minus infinity. 971 972 973 974 975 976<h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p> 977The relational operators in Lua are 978 979<pre> 980 == ~= < > <= >= 981</pre><p> 982These operators always result in <b>false</b> or <b>true</b>. 983 984 985<p> 986Equality (<code>==</code>) first compares the type of its operands. 987If the types are different, then the result is <b>false</b>. 988Otherwise, the values of the operands are compared. 989Numbers and strings are compared in the usual way. 990Objects (tables, userdata, threads, and functions) 991are compared by <em>reference</em>: 992two objects are considered equal only if they are the <em>same</em> object. 993Every time you create a new object 994(a table, userdata, thread, or function), 995this new object is different from any previously existing object. 996 997 998<p> 999You can change the way that Lua compares tables and userdata 1000by using the "eq" metamethod (see <a href="#2.8">§2.8</a>). 1001 1002 1003<p> 1004The conversion rules of <a href="#2.2.1">§2.2.1</a> 1005<em>do not</em> apply to equality comparisons. 1006Thus, <code>"0"==0</code> evaluates to <b>false</b>, 1007and <code>t[0]</code> and <code>t["0"]</code> denote different 1008entries in a table. 1009 1010 1011<p> 1012The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 1013 1014 1015<p> 1016The order operators work as follows. 1017If both arguments are numbers, then they are compared as such. 1018Otherwise, if both arguments are strings, 1019then their values are compared according to the current locale. 1020Otherwise, Lua tries to call the "lt" or the "le" 1021metamethod (see <a href="#2.8">§2.8</a>). 1022A comparison <code>a > b</code> is translated to <code>b < a</code> 1023and <code>a >= b</code> is translated to <code>b <= a</code>. 1024 1025 1026 1027 1028 1029<h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p> 1030The logical operators in Lua are 1031<b>and</b>, <b>or</b>, and <b>not</b>. 1032Like the control structures (see <a href="#2.4.4">§2.4.4</a>), 1033all logical operators consider both <b>false</b> and <b>nil</b> as false 1034and anything else as true. 1035 1036 1037<p> 1038The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 1039The conjunction operator <b>and</b> returns its first argument 1040if this value is <b>false</b> or <b>nil</b>; 1041otherwise, <b>and</b> returns its second argument. 1042The disjunction operator <b>or</b> returns its first argument 1043if this value is different from <b>nil</b> and <b>false</b>; 1044otherwise, <b>or</b> returns its second argument. 1045Both <b>and</b> and <b>or</b> use short-cut evaluation; 1046that is, 1047the second operand is evaluated only if necessary. 1048Here are some examples: 1049 1050<pre> 1051 10 or 20 --> 10 1052 10 or error() --> 10 1053 nil or "a" --> "a" 1054 nil and 10 --> nil 1055 false and error() --> false 1056 false and nil --> false 1057 false or nil --> nil 1058 10 and 20 --> 20 1059</pre><p> 1060(In this manual, 1061<code>--></code> indicates the result of the preceding expression.) 1062 1063 1064 1065 1066 1067<h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p> 1068The string concatenation operator in Lua is 1069denoted by two dots ('<code>..</code>'). 1070If both operands are strings or numbers, then they are converted to 1071strings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>. 1072Otherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>). 1073 1074 1075 1076 1077 1078<h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3> 1079 1080<p> 1081The length operator is denoted by the unary operator <code>#</code>. 1082The length of a string is its number of bytes 1083(that is, the usual meaning of string length when each 1084character is one byte). 1085 1086 1087<p> 1088The length of a table <code>t</code> is defined to be any 1089integer index <code>n</code> 1090such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; 1091moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero. 1092For a regular array, with non-nil values from 1 to a given <code>n</code>, 1093its length is exactly that <code>n</code>, 1094the index of its last value. 1095If the array has "holes" 1096(that is, <b>nil</b> values between other non-nil values), 1097then <code>#t</code> can be any of the indices that 1098directly precedes a <b>nil</b> value 1099(that is, it may consider any such <b>nil</b> value as the end of 1100the array). 1101 1102 1103 1104 1105 1106<h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p> 1107Operator precedence in Lua follows the table below, 1108from lower to higher priority: 1109 1110<pre> 1111 or 1112 and 1113 < > <= >= ~= == 1114 .. 1115 + - 1116 * / % 1117 not # - (unary) 1118 ^ 1119</pre><p> 1120As usual, 1121you can use parentheses to change the precedences of an expression. 1122The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 1123operators are right associative. 1124All other binary operators are left associative. 1125 1126 1127 1128 1129 1130<h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p> 1131Table constructors are expressions that create tables. 1132Every time a constructor is evaluated, a new table is created. 1133A constructor can be used to create an empty table 1134or to create a table and initialize some of its fields. 1135The general syntax for constructors is 1136 1137<pre> 1138 tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ 1139 fieldlist ::= field {fieldsep field} [fieldsep] 1140 field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp 1141 fieldsep ::= `<b>,</b>´ | `<b>;</b>´ 1142</pre> 1143 1144<p> 1145Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 1146with key <code>exp1</code> and value <code>exp2</code>. 1147A field of the form <code>name = exp</code> is equivalent to 1148<code>["name"] = exp</code>. 1149Finally, fields of the form <code>exp</code> are equivalent to 1150<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers, 1151starting with 1. 1152Fields in the other formats do not affect this counting. 1153For example, 1154 1155<pre> 1156 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 1157</pre><p> 1158is equivalent to 1159 1160<pre> 1161 do 1162 local t = {} 1163 t[f(1)] = g 1164 t[1] = "x" -- 1st exp 1165 t[2] = "y" -- 2nd exp 1166 t.x = 1 -- t["x"] = 1 1167 t[3] = f(x) -- 3rd exp 1168 t[30] = 23 1169 t[4] = 45 -- 4th exp 1170 a = t 1171 end 1172</pre> 1173 1174<p> 1175If the last field in the list has the form <code>exp</code> 1176and the expression is a function call or a vararg expression, 1177then all values returned by this expression enter the list consecutively 1178(see <a href="#2.5.8">§2.5.8</a>). 1179To avoid this, 1180enclose the function call or the vararg expression 1181in parentheses (see <a href="#2.5">§2.5</a>). 1182 1183 1184<p> 1185The field list can have an optional trailing separator, 1186as a convenience for machine-generated code. 1187 1188 1189 1190 1191 1192<h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p> 1193A function call in Lua has the following syntax: 1194 1195<pre> 1196 functioncall ::= prefixexp args 1197</pre><p> 1198In a function call, 1199first prefixexp and args are evaluated. 1200If the value of prefixexp has type <em>function</em>, 1201then this function is called 1202with the given arguments. 1203Otherwise, the prefixexp "call" metamethod is called, 1204having as first parameter the value of prefixexp, 1205followed by the original call arguments 1206(see <a href="#2.8">§2.8</a>). 1207 1208 1209<p> 1210The form 1211 1212<pre> 1213 functioncall ::= prefixexp `<b>:</b>´ Name args 1214</pre><p> 1215can be used to call "methods". 1216A call <code>v:name(<em>args</em>)</code> 1217is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 1218except that <code>v</code> is evaluated only once. 1219 1220 1221<p> 1222Arguments have the following syntax: 1223 1224<pre> 1225 args ::= `<b>(</b>´ [explist] `<b>)</b>´ 1226 args ::= tableconstructor 1227 args ::= String 1228</pre><p> 1229All argument expressions are evaluated before the call. 1230A call of the form <code>f{<em>fields</em>}</code> is 1231syntactic sugar for <code>f({<em>fields</em>})</code>; 1232that is, the argument list is a single new table. 1233A call of the form <code>f'<em>string</em>'</code> 1234(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 1235is syntactic sugar for <code>f('<em>string</em>')</code>; 1236that is, the argument list is a single literal string. 1237 1238 1239<p> 1240As an exception to the free-format syntax of Lua, 1241you cannot put a line break before the '<code>(</code>' in a function call. 1242This restriction avoids some ambiguities in the language. 1243If you write 1244 1245<pre> 1246 a = f 1247 (g).x(a) 1248</pre><p> 1249Lua would see that as a single statement, <code>a = f(g).x(a)</code>. 1250So, if you want two statements, you must add a semi-colon between them. 1251If you actually want to call <code>f</code>, 1252you must remove the line break before <code>(g)</code>. 1253 1254 1255<p> 1256A call of the form <code>return</code> <em>functioncall</em> is called 1257a <em>tail call</em>. 1258Lua implements <em>proper tail calls</em> 1259(or <em>proper tail recursion</em>): 1260in a tail call, 1261the called function reuses the stack entry of the calling function. 1262Therefore, there is no limit on the number of nested tail calls that 1263a program can execute. 1264However, a tail call erases any debug information about the 1265calling function. 1266Note that a tail call only happens with a particular syntax, 1267where the <b>return</b> has one single function call as argument; 1268this syntax makes the calling function return exactly 1269the returns of the called function. 1270So, none of the following examples are tail calls: 1271 1272<pre> 1273 return (f(x)) -- results adjusted to 1 1274 return 2 * f(x) 1275 return x, f(x) -- additional results 1276 f(x); return -- results discarded 1277 return x or f(x) -- results adjusted to 1 1278</pre> 1279 1280 1281 1282 1283<h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3> 1284 1285<p> 1286The syntax for function definition is 1287 1288<pre> 1289 function ::= <b>function</b> funcbody 1290 funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> 1291</pre> 1292 1293<p> 1294The following syntactic sugar simplifies function definitions: 1295 1296<pre> 1297 stat ::= <b>function</b> funcname funcbody 1298 stat ::= <b>local</b> <b>function</b> Name funcbody 1299 funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] 1300</pre><p> 1301The statement 1302 1303<pre> 1304 function f () <em>body</em> end 1305</pre><p> 1306translates to 1307 1308<pre> 1309 f = function () <em>body</em> end 1310</pre><p> 1311The statement 1312 1313<pre> 1314 function t.a.b.c.f () <em>body</em> end 1315</pre><p> 1316translates to 1317 1318<pre> 1319 t.a.b.c.f = function () <em>body</em> end 1320</pre><p> 1321The statement 1322 1323<pre> 1324 local function f () <em>body</em> end 1325</pre><p> 1326translates to 1327 1328<pre> 1329 local f; f = function () <em>body</em> end 1330</pre><p> 1331<em>not</em> to 1332 1333<pre> 1334 local f = function () <em>body</em> end 1335</pre><p> 1336(This only makes a difference when the body of the function 1337contains references to <code>f</code>.) 1338 1339 1340<p> 1341A function definition is an executable expression, 1342whose value has type <em>function</em>. 1343When Lua pre-compiles a chunk, 1344all its function bodies are pre-compiled too. 1345Then, whenever Lua executes the function definition, 1346the function is <em>instantiated</em> (or <em>closed</em>). 1347This function instance (or <em>closure</em>) 1348is the final value of the expression. 1349Different instances of the same function 1350can refer to different external local variables 1351and can have different environment tables. 1352 1353 1354<p> 1355Parameters act as local variables that are 1356initialized with the argument values: 1357 1358<pre> 1359 parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ 1360</pre><p> 1361When a function is called, 1362the list of arguments is adjusted to 1363the length of the list of parameters, 1364unless the function is a variadic or <em>vararg function</em>, 1365which is 1366indicated by three dots ('<code>...</code>') at the end of its parameter list. 1367A vararg function does not adjust its argument list; 1368instead, it collects all extra arguments and supplies them 1369to the function through a <em>vararg expression</em>, 1370which is also written as three dots. 1371The value of this expression is a list of all actual extra arguments, 1372similar to a function with multiple results. 1373If a vararg expression is used inside another expression 1374or in the middle of a list of expressions, 1375then its return list is adjusted to one element. 1376If the expression is used as the last element of a list of expressions, 1377then no adjustment is made 1378(unless that last expression is enclosed in parentheses). 1379 1380 1381<p> 1382As an example, consider the following definitions: 1383 1384<pre> 1385 function f(a, b) end 1386 function g(a, b, ...) end 1387 function r() return 1,2,3 end 1388</pre><p> 1389Then, we have the following mapping from arguments to parameters and 1390to the vararg expression: 1391 1392<pre> 1393 CALL PARAMETERS 1394 1395 f(3) a=3, b=nil 1396 f(3, 4) a=3, b=4 1397 f(3, 4, 5) a=3, b=4 1398 f(r(), 10) a=1, b=10 1399 f(r()) a=1, b=2 1400 1401 g(3) a=3, b=nil, ... --> (nothing) 1402 g(3, 4) a=3, b=4, ... --> (nothing) 1403 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 1404 g(5, r()) a=5, b=1, ... --> 2 3 1405</pre> 1406 1407<p> 1408Results are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>). 1409If control reaches the end of a function 1410without encountering a <b>return</b> statement, 1411then the function returns with no results. 1412 1413 1414<p> 1415The <em>colon</em> syntax 1416is used for defining <em>methods</em>, 1417that is, functions that have an implicit extra parameter <code>self</code>. 1418Thus, the statement 1419 1420<pre> 1421 function t.a.b.c:f (<em>params</em>) <em>body</em> end 1422</pre><p> 1423is syntactic sugar for 1424 1425<pre> 1426 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 1427</pre> 1428 1429 1430 1431 1432 1433 1434<h2>2.6 - <a name="2.6">Visibility Rules</a></h2> 1435 1436<p> 1437 1438Lua is a lexically scoped language. 1439The scope of variables begins at the first statement <em>after</em> 1440their declaration and lasts until the end of the innermost block that 1441includes the declaration. 1442Consider the following example: 1443 1444<pre> 1445 x = 10 -- global variable 1446 do -- new block 1447 local x = x -- new 'x', with value 10 1448 print(x) --> 10 1449 x = x+1 1450 do -- another block 1451 local x = x+1 -- another 'x' 1452 print(x) --> 12 1453 end 1454 print(x) --> 11 1455 end 1456 print(x) --> 10 (the global one) 1457</pre> 1458 1459<p> 1460Notice that, in a declaration like <code>local x = x</code>, 1461the new <code>x</code> being declared is not in scope yet, 1462and so the second <code>x</code> refers to the outside variable. 1463 1464 1465<p> 1466Because of the lexical scoping rules, 1467local variables can be freely accessed by functions 1468defined inside their scope. 1469A local variable used by an inner function is called 1470an <em>upvalue</em>, or <em>external local variable</em>, 1471inside the inner function. 1472 1473 1474<p> 1475Notice that each execution of a <b>local</b> statement 1476defines new local variables. 1477Consider the following example: 1478 1479<pre> 1480 a = {} 1481 local x = 20 1482 for i=1,10 do 1483 local y = 0 1484 a[i] = function () y=y+1; return x+y end 1485 end 1486</pre><p> 1487The loop creates ten closures 1488(that is, ten instances of the anonymous function). 1489Each of these closures uses a different <code>y</code> variable, 1490while all of them share the same <code>x</code>. 1491 1492 1493 1494 1495 1496<h2>2.7 - <a name="2.7">Error Handling</a></h2> 1497 1498<p> 1499Because Lua is an embedded extension language, 1500all Lua actions start from C code in the host program 1501calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 1502Whenever an error occurs during Lua compilation or execution, 1503control returns to C, 1504which can take appropriate measures 1505(such as printing an error message). 1506 1507 1508<p> 1509Lua code can explicitly generate an error by calling the 1510<a href="#pdf-error"><code>error</code></a> function. 1511If you need to catch errors in Lua, 1512you can use the <a href="#pdf-pcall"><code>pcall</code></a> function. 1513 1514 1515 1516 1517 1518<h2>2.8 - <a name="2.8">Metatables</a></h2> 1519 1520<p> 1521Every value in Lua can have a <em>metatable</em>. 1522This <em>metatable</em> is an ordinary Lua table 1523that defines the behavior of the original value 1524under certain special operations. 1525You can change several aspects of the behavior 1526of operations over a value by setting specific fields in its metatable. 1527For instance, when a non-numeric value is the operand of an addition, 1528Lua checks for a function in the field <code>"__add"</code> in its metatable. 1529If it finds one, 1530Lua calls this function to perform the addition. 1531 1532 1533<p> 1534We call the keys in a metatable <em>events</em> 1535and the values <em>metamethods</em>. 1536In the previous example, the event is <code>"add"</code> 1537and the metamethod is the function that performs the addition. 1538 1539 1540<p> 1541You can query the metatable of any value 1542through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 1543 1544 1545<p> 1546You can replace the metatable of tables 1547through the <a href="#pdf-setmetatable"><code>setmetatable</code></a> 1548function. 1549You cannot change the metatable of other types from Lua 1550(except by using the debug library); 1551you must use the C API for that. 1552 1553 1554<p> 1555Tables and full userdata have individual metatables 1556(although multiple tables and userdata can share their metatables). 1557Values of all other types share one single metatable per type; 1558that is, there is one single metatable for all numbers, 1559one for all strings, etc. 1560 1561 1562<p> 1563A metatable controls how an object behaves in arithmetic operations, 1564order comparisons, concatenation, length operation, and indexing. 1565A metatable also can define a function to be called when a userdata 1566is garbage collected. 1567For each of these operations Lua associates a specific key 1568called an <em>event</em>. 1569When Lua performs one of these operations over a value, 1570it checks whether this value has a metatable with the corresponding event. 1571If so, the value associated with that key (the metamethod) 1572controls how Lua will perform the operation. 1573 1574 1575<p> 1576Metatables control the operations listed next. 1577Each operation is identified by its corresponding name. 1578The key for each operation is a string with its name prefixed by 1579two underscores, '<code>__</code>'; 1580for instance, the key for operation "add" is the 1581string <code>"__add"</code>. 1582The semantics of these operations is better explained by a Lua function 1583describing how the interpreter executes the operation. 1584 1585 1586<p> 1587The code shown here in Lua is only illustrative; 1588the real behavior is hard coded in the interpreter 1589and it is much more efficient than this simulation. 1590All functions used in these descriptions 1591(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.) 1592are described in <a href="#5.1">§5.1</a>. 1593In particular, to retrieve the metamethod of a given object, 1594we use the expression 1595 1596<pre> 1597 metatable(obj)[event] 1598</pre><p> 1599This should be read as 1600 1601<pre> 1602 rawget(getmetatable(obj) or {}, event) 1603</pre><p> 1604 1605That is, the access to a metamethod does not invoke other metamethods, 1606and the access to objects with no metatables does not fail 1607(it simply results in <b>nil</b>). 1608 1609 1610 1611<ul> 1612 1613<li><b>"add":</b> 1614the <code>+</code> operation. 1615 1616 1617 1618<p> 1619The function <code>getbinhandler</code> below defines how Lua chooses a handler 1620for a binary operation. 1621First, Lua tries the first operand. 1622If its type does not define a handler for the operation, 1623then Lua tries the second operand. 1624 1625<pre> 1626 function getbinhandler (op1, op2, event) 1627 return metatable(op1)[event] or metatable(op2)[event] 1628 end 1629</pre><p> 1630By using this function, 1631the behavior of the <code>op1 + op2</code> is 1632 1633<pre> 1634 function add_event (op1, op2) 1635 local o1, o2 = tonumber(op1), tonumber(op2) 1636 if o1 and o2 then -- both operands are numeric? 1637 return o1 + o2 -- '+' here is the primitive 'add' 1638 else -- at least one of the operands is not numeric 1639 local h = getbinhandler(op1, op2, "__add") 1640 if h then 1641 -- call the handler with both operands 1642 return (h(op1, op2)) 1643 else -- no handler available: default behavior 1644 error(···) 1645 end 1646 end 1647 end 1648</pre><p> 1649</li> 1650 1651<li><b>"sub":</b> 1652the <code>-</code> operation. 1653 1654Behavior similar to the "add" operation. 1655</li> 1656 1657<li><b>"mul":</b> 1658the <code>*</code> operation. 1659 1660Behavior similar to the "add" operation. 1661</li> 1662 1663<li><b>"div":</b> 1664the <code>/</code> operation. 1665 1666Behavior similar to the "add" operation. 1667</li> 1668 1669<li><b>"mod":</b> 1670the <code>%</code> operation. 1671 1672Behavior similar to the "add" operation, 1673with the operation 1674<code>o1 - floor(o1/o2)*o2</code> as the primitive operation. 1675</li> 1676 1677<li><b>"pow":</b> 1678the <code>^</code> (exponentiation) operation. 1679 1680Behavior similar to the "add" operation, 1681with the function <code>pow</code> (from the C math library) 1682as the primitive operation. 1683</li> 1684 1685<li><b>"unm":</b> 1686the unary <code>-</code> operation. 1687 1688 1689<pre> 1690 function unm_event (op) 1691 local o = tonumber(op) 1692 if o then -- operand is numeric? 1693 return -o -- '-' here is the primitive 'unm' 1694 else -- the operand is not numeric. 1695 -- Try to get a handler from the operand 1696 local h = metatable(op).__unm 1697 if h then 1698 -- call the handler with the operand 1699 return (h(op)) 1700 else -- no handler available: default behavior 1701 error(···) 1702 end 1703 end 1704 end 1705</pre><p> 1706</li> 1707 1708<li><b>"concat":</b> 1709the <code>..</code> (concatenation) operation. 1710 1711 1712<pre> 1713 function concat_event (op1, op2) 1714 if (type(op1) == "string" or type(op1) == "number") and 1715 (type(op2) == "string" or type(op2) == "number") then 1716 return op1 .. op2 -- primitive string concatenation 1717 else 1718 local h = getbinhandler(op1, op2, "__concat") 1719 if h then 1720 return (h(op1, op2)) 1721 else 1722 error(···) 1723 end 1724 end 1725 end 1726</pre><p> 1727</li> 1728 1729<li><b>"len":</b> 1730the <code>#</code> operation. 1731 1732 1733<pre> 1734 function len_event (op) 1735 if type(op) == "string" then 1736 return strlen(op) -- primitive string length 1737 elseif type(op) == "table" then 1738 return #op -- primitive table length 1739 else 1740 local h = metatable(op).__len 1741 if h then 1742 -- call the handler with the operand 1743 return (h(op)) 1744 else -- no handler available: default behavior 1745 error(···) 1746 end 1747 end 1748 end 1749</pre><p> 1750See <a href="#2.5.5">§2.5.5</a> for a description of the length of a table. 1751</li> 1752 1753<li><b>"eq":</b> 1754the <code>==</code> operation. 1755 1756The function <code>getcomphandler</code> defines how Lua chooses a metamethod 1757for comparison operators. 1758A metamethod only is selected when both objects 1759being compared have the same type 1760and the same metamethod for the selected operation. 1761 1762<pre> 1763 function getcomphandler (op1, op2, event) 1764 if type(op1) ~= type(op2) then return nil end 1765 local mm1 = metatable(op1)[event] 1766 local mm2 = metatable(op2)[event] 1767 if mm1 == mm2 then return mm1 else return nil end 1768 end 1769</pre><p> 1770The "eq" event is defined as follows: 1771 1772<pre> 1773 function eq_event (op1, op2) 1774 if type(op1) ~= type(op2) then -- different types? 1775 return false -- different objects 1776 end 1777 if op1 == op2 then -- primitive equal? 1778 return true -- objects are equal 1779 end 1780 -- try metamethod 1781 local h = getcomphandler(op1, op2, "__eq") 1782 if h then 1783 return (h(op1, op2)) 1784 else 1785 return false 1786 end 1787 end 1788</pre><p> 1789<code>a ~= b</code> is equivalent to <code>not (a == b)</code>. 1790</li> 1791 1792<li><b>"lt":</b> 1793the <code><</code> operation. 1794 1795 1796<pre> 1797 function lt_event (op1, op2) 1798 if type(op1) == "number" and type(op2) == "number" then 1799 return op1 < op2 -- numeric comparison 1800 elseif type(op1) == "string" and type(op2) == "string" then 1801 return op1 < op2 -- lexicographic comparison 1802 else 1803 local h = getcomphandler(op1, op2, "__lt") 1804 if h then 1805 return (h(op1, op2)) 1806 else 1807 error(···) 1808 end 1809 end 1810 end 1811</pre><p> 1812<code>a > b</code> is equivalent to <code>b < a</code>. 1813</li> 1814 1815<li><b>"le":</b> 1816the <code><=</code> operation. 1817 1818 1819<pre> 1820 function le_event (op1, op2) 1821 if type(op1) == "number" and type(op2) == "number" then 1822 return op1 <= op2 -- numeric comparison 1823 elseif type(op1) == "string" and type(op2) == "string" then 1824 return op1 <= op2 -- lexicographic comparison 1825 else 1826 local h = getcomphandler(op1, op2, "__le") 1827 if h then 1828 return (h(op1, op2)) 1829 else 1830 h = getcomphandler(op1, op2, "__lt") 1831 if h then 1832 return not h(op2, op1) 1833 else 1834 error(···) 1835 end 1836 end 1837 end 1838 end 1839</pre><p> 1840<code>a >= b</code> is equivalent to <code>b <= a</code>. 1841Note that, in the absence of a "le" metamethod, 1842Lua tries the "lt", assuming that <code>a <= b</code> is 1843equivalent to <code>not (b < a)</code>. 1844</li> 1845 1846<li><b>"index":</b> 1847The indexing access <code>table[key]</code>. 1848 1849 1850<pre> 1851 function gettable_event (table, key) 1852 local h 1853 if type(table) == "table" then 1854 local v = rawget(table, key) 1855 if v ~= nil then return v end 1856 h = metatable(table).__index 1857 if h == nil then return nil end 1858 else 1859 h = metatable(table).__index 1860 if h == nil then 1861 error(···) 1862 end 1863 end 1864 if type(h) == "function" then 1865 return (h(table, key)) -- call the handler 1866 else return h[key] -- or repeat operation on it 1867 end 1868 end 1869</pre><p> 1870</li> 1871 1872<li><b>"newindex":</b> 1873The indexing assignment <code>table[key] = value</code>. 1874 1875 1876<pre> 1877 function settable_event (table, key, value) 1878 local h 1879 if type(table) == "table" then 1880 local v = rawget(table, key) 1881 if v ~= nil then rawset(table, key, value); return end 1882 h = metatable(table).__newindex 1883 if h == nil then rawset(table, key, value); return end 1884 else 1885 h = metatable(table).__newindex 1886 if h == nil then 1887 error(···) 1888 end 1889 end 1890 if type(h) == "function" then 1891 h(table, key,value) -- call the handler 1892 else h[key] = value -- or repeat operation on it 1893 end 1894 end 1895</pre><p> 1896</li> 1897 1898<li><b>"call":</b> 1899called when Lua calls a value. 1900 1901 1902<pre> 1903 function function_event (func, ...) 1904 if type(func) == "function" then 1905 return func(...) -- primitive call 1906 else 1907 local h = metatable(func).__call 1908 if h then 1909 return h(func, ...) 1910 else 1911 error(···) 1912 end 1913 end 1914 end 1915</pre><p> 1916</li> 1917 1918</ul> 1919 1920 1921 1922 1923<h2>2.9 - <a name="2.9">Environments</a></h2> 1924 1925<p> 1926Besides metatables, 1927objects of types thread, function, and userdata 1928have another table associated with them, 1929called their <em>environment</em>. 1930Like metatables, environments are regular tables and 1931multiple objects can share the same environment. 1932 1933 1934<p> 1935Threads are created sharing the environment of the creating thread. 1936Userdata and C functions are created sharing the environment 1937of the creating C function. 1938Non-nested Lua functions 1939(created by <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</code></a> or <a href="#pdf-load"><code>load</code></a>) 1940are created sharing the environment of the creating thread. 1941Nested Lua functions are created sharing the environment of 1942the creating Lua function. 1943 1944 1945<p> 1946Environments associated with userdata have no meaning for Lua. 1947It is only a convenience feature for programmers to associate a table to 1948a userdata. 1949 1950 1951<p> 1952Environments associated with threads are called 1953<em>global environments</em>. 1954They are used as the default environment for threads and 1955non-nested Lua functions created by the thread 1956and can be directly accessed by C code (see <a href="#3.3">§3.3</a>). 1957 1958 1959<p> 1960The environment associated with a C function can be directly 1961accessed by C code (see <a href="#3.3">§3.3</a>). 1962It is used as the default environment for other C functions 1963and userdata created by the function. 1964 1965 1966<p> 1967Environments associated with Lua functions are used to resolve 1968all accesses to global variables within the function (see <a href="#2.3">§2.3</a>). 1969They are used as the default environment for nested Lua functions 1970created by the function. 1971 1972 1973<p> 1974You can change the environment of a Lua function or the 1975running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>. 1976You can get the environment of a Lua function or the running thread 1977by calling <a href="#pdf-getfenv"><code>getfenv</code></a>. 1978To manipulate the environment of other objects 1979(userdata, C functions, other threads) you must 1980use the C API. 1981 1982 1983 1984 1985 1986<h2>2.10 - <a name="2.10">Garbage Collection</a></h2> 1987 1988<p> 1989Lua performs automatic memory management. 1990This means that 1991you have to worry neither about allocating memory for new objects 1992nor about freeing it when the objects are no longer needed. 1993Lua manages memory automatically by running 1994a <em>garbage collector</em> from time to time 1995to collect all <em>dead objects</em> 1996(that is, objects that are no longer accessible from Lua). 1997All memory used by Lua is subject to automatic management: 1998tables, userdata, functions, threads, strings, etc. 1999 2000 2001<p> 2002Lua implements an incremental mark-and-sweep collector. 2003It uses two numbers to control its garbage-collection cycles: 2004the <em>garbage-collector pause</em> and 2005the <em>garbage-collector step multiplier</em>. 2006Both use percentage points as units 2007(so that a value of 100 means an internal value of 1). 2008 2009 2010<p> 2011The garbage-collector pause 2012controls how long the collector waits before starting a new cycle. 2013Larger values make the collector less aggressive. 2014Values smaller than 100 mean the collector will not wait to 2015start a new cycle. 2016A value of 200 means that the collector waits for the total memory in use 2017to double before starting a new cycle. 2018 2019 2020<p> 2021The step multiplier 2022controls the relative speed of the collector relative to 2023memory allocation. 2024Larger values make the collector more aggressive but also increase 2025the size of each incremental step. 2026Values smaller than 100 make the collector too slow and 2027can result in the collector never finishing a cycle. 2028The default, 200, means that the collector runs at "twice" 2029the speed of memory allocation. 2030 2031 2032<p> 2033You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 2034or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 2035With these functions you can also control 2036the collector directly (e.g., stop and restart it). 2037 2038 2039 2040<h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3> 2041 2042<p> 2043Using the C API, 2044you can set garbage-collector metamethods for userdata (see <a href="#2.8">§2.8</a>). 2045These metamethods are also called <em>finalizers</em>. 2046Finalizers allow you to coordinate Lua's garbage collection 2047with external resource management 2048(such as closing files, network or database connections, 2049or freeing your own memory). 2050 2051 2052<p> 2053Garbage userdata with a field <code>__gc</code> in their metatables are not 2054collected immediately by the garbage collector. 2055Instead, Lua puts them in a list. 2056After the collection, 2057Lua does the equivalent of the following function 2058for each userdata in that list: 2059 2060<pre> 2061 function gc_event (udata) 2062 local h = metatable(udata).__gc 2063 if h then 2064 h(udata) 2065 end 2066 end 2067</pre> 2068 2069<p> 2070At the end of each garbage-collection cycle, 2071the finalizers for userdata are called in <em>reverse</em> 2072order of their creation, 2073among those collected in that cycle. 2074That is, the first finalizer to be called is the one associated 2075with the userdata created last in the program. 2076The userdata itself is freed only in the next garbage-collection cycle. 2077 2078 2079 2080 2081 2082<h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3> 2083 2084<p> 2085A <em>weak table</em> is a table whose elements are 2086<em>weak references</em>. 2087A weak reference is ignored by the garbage collector. 2088In other words, 2089if the only references to an object are weak references, 2090then the garbage collector will collect this object. 2091 2092 2093<p> 2094A weak table can have weak keys, weak values, or both. 2095A table with weak keys allows the collection of its keys, 2096but prevents the collection of its values. 2097A table with both weak keys and weak values allows the collection of 2098both keys and values. 2099In any case, if either the key or the value is collected, 2100the whole pair is removed from the table. 2101The weakness of a table is controlled by the 2102<code>__mode</code> field of its metatable. 2103If the <code>__mode</code> field is a string containing the character '<code>k</code>', 2104the keys in the table are weak. 2105If <code>__mode</code> contains '<code>v</code>', 2106the values in the table are weak. 2107 2108 2109<p> 2110After you use a table as a metatable, 2111you should not change the value of its <code>__mode</code> field. 2112Otherwise, the weak behavior of the tables controlled by this 2113metatable is undefined. 2114 2115 2116 2117 2118 2119 2120 2121<h2>2.11 - <a name="2.11">Coroutines</a></h2> 2122 2123<p> 2124Lua supports coroutines, 2125also called <em>collaborative multithreading</em>. 2126A coroutine in Lua represents an independent thread of execution. 2127Unlike threads in multithread systems, however, 2128a coroutine only suspends its execution by explicitly calling 2129a yield function. 2130 2131 2132<p> 2133You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 2134Its sole argument is a function 2135that is the main function of the coroutine. 2136The <code>create</code> function only creates a new coroutine and 2137returns a handle to it (an object of type <em>thread</em>); 2138it does not start the coroutine execution. 2139 2140 2141<p> 2142When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 2143passing as its first argument 2144a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 2145the coroutine starts its execution, 2146at the first line of its main function. 2147Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on 2148to the coroutine main function. 2149After the coroutine starts running, 2150it runs until it terminates or <em>yields</em>. 2151 2152 2153<p> 2154A coroutine can terminate its execution in two ways: 2155normally, when its main function returns 2156(explicitly or implicitly, after the last instruction); 2157and abnormally, if there is an unprotected error. 2158In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 2159plus any values returned by the coroutine main function. 2160In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 2161plus an error message. 2162 2163 2164<p> 2165A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 2166When a coroutine yields, 2167the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 2168even if the yield happens inside nested function calls 2169(that is, not in the main function, 2170but in a function directly or indirectly called by the main function). 2171In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 2172plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 2173The next time you resume the same coroutine, 2174it continues its execution from the point where it yielded, 2175with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 2176arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 2177 2178 2179<p> 2180Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 2181the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 2182but instead of returning the coroutine itself, 2183it returns a function that, when called, resumes the coroutine. 2184Any arguments passed to this function 2185go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 2186<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 2187except the first one (the boolean error code). 2188Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 2189<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 2190any error is propagated to the caller. 2191 2192 2193<p> 2194As an example, 2195consider the following code: 2196 2197<pre> 2198 function foo (a) 2199 print("foo", a) 2200 return coroutine.yield(2*a) 2201 end 2202 2203 co = coroutine.create(function (a,b) 2204 print("co-body", a, b) 2205 local r = foo(a+1) 2206 print("co-body", r) 2207 local r, s = coroutine.yield(a+b, a-b) 2208 print("co-body", r, s) 2209 return b, "end" 2210 end) 2211 2212 print("main", coroutine.resume(co, 1, 10)) 2213 print("main", coroutine.resume(co, "r")) 2214 print("main", coroutine.resume(co, "x", "y")) 2215 print("main", coroutine.resume(co, "x", "y")) 2216</pre><p> 2217When you run it, it produces the following output: 2218 2219<pre> 2220 co-body 1 10 2221 foo 2 2222 2223 main true 4 2224 co-body r 2225 main true 11 -9 2226 co-body x y 2227 main true 10 end 2228 main false cannot resume dead coroutine 2229</pre> 2230 2231 2232 2233 2234<h1>3 - <a name="3">The Application Program Interface</a></h1> 2235 2236<p> 2237 2238This section describes the C API for Lua, that is, 2239the set of C functions available to the host program to communicate 2240with Lua. 2241All API functions and related types and constants 2242are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2243 2244 2245<p> 2246Even when we use the term "function", 2247any facility in the API may be provided as a macro instead. 2248All such macros use each of their arguments exactly once 2249(except for the first argument, which is always a Lua state), 2250and so do not generate any hidden side-effects. 2251 2252 2253<p> 2254As in most C libraries, 2255the Lua API functions do not check their arguments for validity or consistency. 2256However, you can change this behavior by compiling Lua 2257with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>, 2258in file <code>luaconf.h</code>. 2259 2260 2261 2262<h2>3.1 - <a name="3.1">The Stack</a></h2> 2263 2264<p> 2265Lua uses a <em>virtual stack</em> to pass values to and from C. 2266Each element in this stack represents a Lua value 2267(<b>nil</b>, number, string, etc.). 2268 2269 2270<p> 2271Whenever Lua calls C, the called function gets a new stack, 2272which is independent of previous stacks and of stacks of 2273C functions that are still active. 2274This stack initially contains any arguments to the C function 2275and it is where the C function pushes its results 2276to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2277 2278 2279<p> 2280For convenience, 2281most query operations in the API do not follow a strict stack discipline. 2282Instead, they can refer to any element in the stack 2283by using an <em>index</em>: 2284A positive index represents an <em>absolute</em> stack position 2285(starting at 1); 2286a negative index represents an <em>offset</em> relative to the top of the stack. 2287More specifically, if the stack has <em>n</em> elements, 2288then index 1 represents the first element 2289(that is, the element that was pushed onto the stack first) 2290and 2291index <em>n</em> represents the last element; 2292index -1 also represents the last element 2293(that is, the element at the top) 2294and index <em>-n</em> represents the first element. 2295We say that an index is <em>valid</em> 2296if it lies between 1 and the stack top 2297(that is, if <code>1 ≤ abs(index) ≤ top</code>). 2298 2299 2300 2301 2302 2303 2304<h2>3.2 - <a name="3.2">Stack Size</a></h2> 2305 2306<p> 2307When you interact with Lua API, 2308you are responsible for ensuring consistency. 2309In particular, 2310<em>you are responsible for controlling stack overflow</em>. 2311You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2312to grow the stack size. 2313 2314 2315<p> 2316Whenever Lua calls C, 2317it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available. 2318<code>LUA_MINSTACK</code> is defined as 20, 2319so that usually you do not have to worry about stack space 2320unless your code has loops pushing elements onto the stack. 2321 2322 2323<p> 2324Most query functions accept as indices any value inside the 2325available stack space, that is, indices up to the maximum stack size 2326you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2327Such indices are called <em>acceptable indices</em>. 2328More formally, we define an <em>acceptable index</em> 2329as follows: 2330 2331<pre> 2332 (index < 0 && abs(index) <= top) || 2333 (index > 0 && index <= stackspace) 2334</pre><p> 2335Note that 0 is never an acceptable index. 2336 2337 2338 2339 2340 2341<h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2> 2342 2343<p> 2344Unless otherwise noted, 2345any function that accepts valid indices can also be called with 2346<em>pseudo-indices</em>, 2347which represent some Lua values that are accessible to C code 2348but which are not in the stack. 2349Pseudo-indices are used to access the thread environment, 2350the function environment, 2351the registry, 2352and the upvalues of a C function (see <a href="#3.4">§3.4</a>). 2353 2354 2355<p> 2356The thread environment (where global variables live) is 2357always at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>. 2358The environment of the running C function is always 2359at pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>. 2360 2361 2362<p> 2363To access and change the value of global variables, 2364you can use regular table operations over an environment table. 2365For instance, to access the value of a global variable, do 2366 2367<pre> 2368 lua_getfield(L, LUA_GLOBALSINDEX, varname); 2369</pre> 2370 2371 2372 2373 2374<h2>3.4 - <a name="3.4">C Closures</a></h2> 2375 2376<p> 2377When a C function is created, 2378it is possible to associate some values with it, 2379thus creating a <em>C closure</em>; 2380these values are called <em>upvalues</em> and are 2381accessible to the function whenever it is called 2382(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). 2383 2384 2385<p> 2386Whenever a C function is called, 2387its upvalues are located at specific pseudo-indices. 2388These pseudo-indices are produced by the macro 2389<a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2390The first value associated with a function is at position 2391<code>lua_upvalueindex(1)</code>, and so on. 2392Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 2393where <em>n</em> is greater than the number of upvalues of the 2394current function (but not greater than 256), 2395produces an acceptable (but invalid) index. 2396 2397 2398 2399 2400 2401<h2>3.5 - <a name="3.5">Registry</a></h2> 2402 2403<p> 2404Lua provides a <em>registry</em>, 2405a pre-defined table that can be used by any C code to 2406store whatever Lua value it needs to store. 2407This table is always located at pseudo-index 2408<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2409Any C library can store data into this table, 2410but it should take care to choose keys different from those used 2411by other libraries, to avoid collisions. 2412Typically, you should use as key a string containing your library name 2413or a light userdata with the address of a C object in your code. 2414 2415 2416<p> 2417The integer keys in the registry are used by the reference mechanism, 2418implemented by the auxiliary library, 2419and therefore should not be used for other purposes. 2420 2421 2422 2423 2424 2425<h2>3.6 - <a name="3.6">Error Handling in C</a></h2> 2426 2427<p> 2428Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 2429(You can also choose to use exceptions if you use C++; 2430see file <code>luaconf.h</code>.) 2431When Lua faces any error 2432(such as memory allocation errors, type errors, syntax errors, 2433and runtime errors) 2434it <em>raises</em> an error; 2435that is, it does a long jump. 2436A <em>protected environment</em> uses <code>setjmp</code> 2437to set a recover point; 2438any error jumps to the most recent active recover point. 2439 2440 2441<p> 2442Most functions in the API can throw an error, 2443for instance due to a memory allocation error. 2444The documentation for each function indicates whether 2445it can throw errors. 2446 2447 2448<p> 2449Inside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2450 2451 2452 2453 2454 2455<h2>3.7 - <a name="3.7">Functions and Types</a></h2> 2456 2457<p> 2458Here we list all functions and types from the C API in 2459alphabetical order. 2460Each function has an indicator like this: 2461<span class="apii">[-o, +p, <em>x</em>]</span> 2462 2463 2464<p> 2465The first field, <code>o</code>, 2466is how many elements the function pops from the stack. 2467The second field, <code>p</code>, 2468is how many elements the function pushes onto the stack. 2469(Any function always pushes its results after popping its arguments.) 2470A field in the form <code>x|y</code> means the function can push (or pop) 2471<code>x</code> or <code>y</code> elements, 2472depending on the situation; 2473an interrogation mark '<code>?</code>' means that 2474we cannot know how many elements the function pops/pushes 2475by looking only at its arguments 2476(e.g., they may depend on what is on the stack). 2477The third field, <code>x</code>, 2478tells whether the function may throw errors: 2479'<code>-</code>' means the function never throws any error; 2480'<code>m</code>' means the function may throw an error 2481only due to not enough memory; 2482'<code>e</code>' means the function may throw other kinds of errors; 2483'<code>v</code>' means the function may throw an error on purpose. 2484 2485 2486 2487<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 2488<pre>typedef void * (*lua_Alloc) (void *ud, 2489 void *ptr, 2490 size_t osize, 2491 size_t nsize);</pre> 2492 2493<p> 2494The type of the memory-allocation function used by Lua states. 2495The allocator function must provide a 2496functionality similar to <code>realloc</code>, 2497but not exactly the same. 2498Its arguments are 2499<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 2500<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 2501<code>osize</code>, the original size of the block; 2502<code>nsize</code>, the new size of the block. 2503<code>ptr</code> is <code>NULL</code> if and only if <code>osize</code> is zero. 2504When <code>nsize</code> is zero, the allocator must return <code>NULL</code>; 2505if <code>osize</code> is not zero, 2506it should free the block pointed to by <code>ptr</code>. 2507When <code>nsize</code> is not zero, the allocator returns <code>NULL</code> 2508if and only if it cannot fill the request. 2509When <code>nsize</code> is not zero and <code>osize</code> is zero, 2510the allocator should behave like <code>malloc</code>. 2511When <code>nsize</code> and <code>osize</code> are not zero, 2512the allocator behaves like <code>realloc</code>. 2513Lua assumes that the allocator never fails when 2514<code>osize >= nsize</code>. 2515 2516 2517<p> 2518Here is a simple implementation for the allocator function. 2519It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 2520 2521<pre> 2522 static void *l_alloc (void *ud, void *ptr, size_t osize, 2523 size_t nsize) { 2524 (void)ud; (void)osize; /* not used */ 2525 if (nsize == 0) { 2526 free(ptr); 2527 return NULL; 2528 } 2529 else 2530 return realloc(ptr, nsize); 2531 } 2532</pre><p> 2533This code assumes 2534that <code>free(NULL)</code> has no effect and that 2535<code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>. 2536ANSI C ensures both behaviors. 2537 2538 2539 2540 2541 2542<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 2543<span class="apii">[-0, +0, <em>-</em>]</span> 2544<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 2545 2546<p> 2547Sets a new panic function and returns the old one. 2548 2549 2550<p> 2551If an error happens outside any protected environment, 2552Lua calls a <em>panic function</em> 2553and then calls <code>exit(EXIT_FAILURE)</code>, 2554thus exiting the host application. 2555Your panic function can avoid this exit by 2556never returning (e.g., doing a long jump). 2557 2558 2559<p> 2560The panic function can access the error message at the top of the stack. 2561 2562 2563 2564 2565 2566<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 2567<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 2568<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 2569 2570<p> 2571Calls a function. 2572 2573 2574<p> 2575To call a function you must use the following protocol: 2576first, the function to be called is pushed onto the stack; 2577then, the arguments to the function are pushed 2578in direct order; 2579that is, the first argument is pushed first. 2580Finally you call <a href="#lua_call"><code>lua_call</code></a>; 2581<code>nargs</code> is the number of arguments that you pushed onto the stack. 2582All arguments and the function value are popped from the stack 2583when the function is called. 2584The function results are pushed onto the stack when the function returns. 2585The number of results is adjusted to <code>nresults</code>, 2586unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 2587In this case, <em>all</em> results from the function are pushed. 2588Lua takes care that the returned values fit into the stack space. 2589The function results are pushed onto the stack in direct order 2590(the first result is pushed first), 2591so that after the call the last result is on the top of the stack. 2592 2593 2594<p> 2595Any error inside the called function is propagated upwards 2596(with a <code>longjmp</code>). 2597 2598 2599<p> 2600The following example shows how the host program can do the 2601equivalent to this Lua code: 2602 2603<pre> 2604 a = f("how", t.x, 14) 2605</pre><p> 2606Here it is in C: 2607 2608<pre> 2609 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ 2610 lua_pushstring(L, "how"); /* 1st argument */ 2611 lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ 2612 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 2613 lua_remove(L, -2); /* remove 't' from the stack */ 2614 lua_pushinteger(L, 14); /* 3rd argument */ 2615 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 2616 lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */ 2617</pre><p> 2618Note that the code above is "balanced": 2619at its end, the stack is back to its original configuration. 2620This is considered good programming practice. 2621 2622 2623 2624 2625 2626<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 2627<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 2628 2629<p> 2630Type for C functions. 2631 2632 2633<p> 2634In order to communicate properly with Lua, 2635a C function must use the following protocol, 2636which defines the way parameters and results are passed: 2637a C function receives its arguments from Lua in its stack 2638in direct order (the first argument is pushed first). 2639So, when the function starts, 2640<code>lua_gettop(L)</code> returns the number of arguments received by the function. 2641The first argument (if any) is at index 1 2642and its last argument is at index <code>lua_gettop(L)</code>. 2643To return values to Lua, a C function just pushes them onto the stack, 2644in direct order (the first result is pushed first), 2645and returns the number of results. 2646Any other value in the stack below the results will be properly 2647discarded by Lua. 2648Like a Lua function, a C function called by Lua can also return 2649many results. 2650 2651 2652<p> 2653As an example, the following function receives a variable number 2654of numerical arguments and returns their average and sum: 2655 2656<pre> 2657 static int foo (lua_State *L) { 2658 int n = lua_gettop(L); /* number of arguments */ 2659 lua_Number sum = 0; 2660 int i; 2661 for (i = 1; i <= n; i++) { 2662 if (!lua_isnumber(L, i)) { 2663 lua_pushstring(L, "incorrect argument"); 2664 lua_error(L); 2665 } 2666 sum += lua_tonumber(L, i); 2667 } 2668 lua_pushnumber(L, sum/n); /* first result */ 2669 lua_pushnumber(L, sum); /* second result */ 2670 return 2; /* number of results */ 2671 } 2672</pre> 2673 2674 2675 2676 2677<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 2678<span class="apii">[-0, +0, <em>m</em>]</span> 2679<pre>int lua_checkstack (lua_State *L, int extra);</pre> 2680 2681<p> 2682Ensures that there are at least <code>extra</code> free stack slots in the stack. 2683It returns false if it cannot grow the stack to that size. 2684This function never shrinks the stack; 2685if the stack is already larger than the new size, 2686it is left unchanged. 2687 2688 2689 2690 2691 2692<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 2693<span class="apii">[-0, +0, <em>-</em>]</span> 2694<pre>void lua_close (lua_State *L);</pre> 2695 2696<p> 2697Destroys all objects in the given Lua state 2698(calling the corresponding garbage-collection metamethods, if any) 2699and frees all dynamic memory used by this state. 2700On several platforms, you may not need to call this function, 2701because all resources are naturally released when the host program ends. 2702On the other hand, long-running programs, 2703such as a daemon or a web server, 2704might need to release states as soon as they are not needed, 2705to avoid growing too large. 2706 2707 2708 2709 2710 2711<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 2712<span class="apii">[-n, +1, <em>e</em>]</span> 2713<pre>void lua_concat (lua_State *L, int n);</pre> 2714 2715<p> 2716Concatenates the <code>n</code> values at the top of the stack, 2717pops them, and leaves the result at the top. 2718If <code>n</code> is 1, the result is the single value on the stack 2719(that is, the function does nothing); 2720if <code>n</code> is 0, the result is the empty string. 2721Concatenation is performed following the usual semantics of Lua 2722(see <a href="#2.5.4">§2.5.4</a>). 2723 2724 2725 2726 2727 2728<hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p> 2729<span class="apii">[-0, +(0|1), <em>-</em>]</span> 2730<pre>int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);</pre> 2731 2732<p> 2733Calls the C function <code>func</code> in protected mode. 2734<code>func</code> starts with only one element in its stack, 2735a light userdata containing <code>ud</code>. 2736In case of errors, 2737<a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, 2738plus the error object on the top of the stack; 2739otherwise, it returns zero, and does not change the stack. 2740All values returned by <code>func</code> are discarded. 2741 2742 2743 2744 2745 2746<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 2747<span class="apii">[-0, +1, <em>m</em>]</span> 2748<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 2749 2750<p> 2751Creates a new empty table and pushes it onto the stack. 2752The new table has space pre-allocated 2753for <code>narr</code> array elements and <code>nrec</code> non-array elements. 2754This pre-allocation is useful when you know exactly how many elements 2755the table will have. 2756Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 2757 2758 2759 2760 2761 2762<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 2763<span class="apii">[-0, +0, <em>m</em>]</span> 2764<pre>int lua_dump (lua_State *L, lua_Writer writer, void *data);</pre> 2765 2766<p> 2767Dumps a function as a binary chunk. 2768Receives a Lua function on the top of the stack 2769and produces a binary chunk that, 2770if loaded again, 2771results in a function equivalent to the one dumped. 2772As it produces parts of the chunk, 2773<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 2774with the given <code>data</code> 2775to write them. 2776 2777 2778<p> 2779The value returned is the error code returned by the last 2780call to the writer; 27810 means no errors. 2782 2783 2784<p> 2785This function does not pop the Lua function from the stack. 2786 2787 2788 2789 2790 2791<hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p> 2792<span class="apii">[-0, +0, <em>e</em>]</span> 2793<pre>int lua_equal (lua_State *L, int index1, int index2);</pre> 2794 2795<p> 2796Returns 1 if the two values in acceptable indices <code>index1</code> and 2797<code>index2</code> are equal, 2798following the semantics of the Lua <code>==</code> operator 2799(that is, may call metamethods). 2800Otherwise returns 0. 2801Also returns 0 if any of the indices is non valid. 2802 2803 2804 2805 2806 2807<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 2808<span class="apii">[-1, +0, <em>v</em>]</span> 2809<pre>int lua_error (lua_State *L);</pre> 2810 2811<p> 2812Generates a Lua error. 2813The error message (which can actually be a Lua value of any type) 2814must be on the stack top. 2815This function does a long jump, 2816and therefore never returns. 2817(see <a href="#luaL_error"><code>luaL_error</code></a>). 2818 2819 2820 2821 2822 2823<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 2824<span class="apii">[-0, +0, <em>e</em>]</span> 2825<pre>int lua_gc (lua_State *L, int what, int data);</pre> 2826 2827<p> 2828Controls the garbage collector. 2829 2830 2831<p> 2832This function performs several tasks, 2833according to the value of the parameter <code>what</code>: 2834 2835<ul> 2836 2837<li><b><code>LUA_GCSTOP</code>:</b> 2838stops the garbage collector. 2839</li> 2840 2841<li><b><code>LUA_GCRESTART</code>:</b> 2842restarts the garbage collector. 2843</li> 2844 2845<li><b><code>LUA_GCCOLLECT</code>:</b> 2846performs a full garbage-collection cycle. 2847</li> 2848 2849<li><b><code>LUA_GCCOUNT</code>:</b> 2850returns the current amount of memory (in Kbytes) in use by Lua. 2851</li> 2852 2853<li><b><code>LUA_GCCOUNTB</code>:</b> 2854returns the remainder of dividing the current amount of bytes of 2855memory in use by Lua by 1024. 2856</li> 2857 2858<li><b><code>LUA_GCSTEP</code>:</b> 2859performs an incremental step of garbage collection. 2860The step "size" is controlled by <code>data</code> 2861(larger values mean more steps) in a non-specified way. 2862If you want to control the step size 2863you must experimentally tune the value of <code>data</code>. 2864The function returns 1 if the step finished a 2865garbage-collection cycle. 2866</li> 2867 2868<li><b><code>LUA_GCSETPAUSE</code>:</b> 2869sets <code>data</code> as the new value 2870for the <em>pause</em> of the collector (see <a href="#2.10">§2.10</a>). 2871The function returns the previous value of the pause. 2872</li> 2873 2874<li><b><code>LUA_GCSETSTEPMUL</code>:</b> 2875sets <code>data</code> as the new value for the <em>step multiplier</em> of 2876the collector (see <a href="#2.10">§2.10</a>). 2877The function returns the previous value of the step multiplier. 2878</li> 2879 2880</ul> 2881 2882 2883 2884 2885<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 2886<span class="apii">[-0, +0, <em>-</em>]</span> 2887<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 2888 2889<p> 2890Returns the memory-allocation function of a given state. 2891If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 2892opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. 2893 2894 2895 2896 2897 2898<hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p> 2899<span class="apii">[-0, +1, <em>-</em>]</span> 2900<pre>void lua_getfenv (lua_State *L, int index);</pre> 2901 2902<p> 2903Pushes onto the stack the environment table of 2904the value at the given index. 2905 2906 2907 2908 2909 2910<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 2911<span class="apii">[-0, +1, <em>e</em>]</span> 2912<pre>void lua_getfield (lua_State *L, int index, const char *k);</pre> 2913 2914<p> 2915Pushes onto the stack the value <code>t[k]</code>, 2916where <code>t</code> is the value at the given valid index. 2917As in Lua, this function may trigger a metamethod 2918for the "index" event (see <a href="#2.8">§2.8</a>). 2919 2920 2921 2922 2923 2924<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 2925<span class="apii">[-0, +1, <em>e</em>]</span> 2926<pre>void lua_getglobal (lua_State *L, const char *name);</pre> 2927 2928<p> 2929Pushes onto the stack the value of the global <code>name</code>. 2930It is defined as a macro: 2931 2932<pre> 2933 #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) 2934</pre> 2935 2936 2937 2938 2939<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 2940<span class="apii">[-0, +(0|1), <em>-</em>]</span> 2941<pre>int lua_getmetatable (lua_State *L, int index);</pre> 2942 2943<p> 2944Pushes onto the stack the metatable of the value at the given 2945acceptable index. 2946If the index is not valid, 2947or if the value does not have a metatable, 2948the function returns 0 and pushes nothing on the stack. 2949 2950 2951 2952 2953 2954<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 2955<span class="apii">[-1, +1, <em>e</em>]</span> 2956<pre>void lua_gettable (lua_State *L, int index);</pre> 2957 2958<p> 2959Pushes onto the stack the value <code>t[k]</code>, 2960where <code>t</code> is the value at the given valid index 2961and <code>k</code> is the value at the top of the stack. 2962 2963 2964<p> 2965This function pops the key from the stack 2966(putting the resulting value in its place). 2967As in Lua, this function may trigger a metamethod 2968for the "index" event (see <a href="#2.8">§2.8</a>). 2969 2970 2971 2972 2973 2974<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 2975<span class="apii">[-0, +0, <em>-</em>]</span> 2976<pre>int lua_gettop (lua_State *L);</pre> 2977 2978<p> 2979Returns the index of the top element in the stack. 2980Because indices start at 1, 2981this result is equal to the number of elements in the stack 2982(and so 0 means an empty stack). 2983 2984 2985 2986 2987 2988<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 2989<span class="apii">[-1, +1, <em>-</em>]</span> 2990<pre>void lua_insert (lua_State *L, int index);</pre> 2991 2992<p> 2993Moves the top element into the given valid index, 2994shifting up the elements above this index to open space. 2995Cannot be called with a pseudo-index, 2996because a pseudo-index is not an actual stack position. 2997 2998 2999 3000 3001 3002<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3003<pre>typedef ptrdiff_t lua_Integer;</pre> 3004 3005<p> 3006The type used by the Lua API to represent integral values. 3007 3008 3009<p> 3010By default it is a <code>ptrdiff_t</code>, 3011which is usually the largest signed integral type the machine handles 3012"comfortably". 3013 3014 3015 3016 3017 3018<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3019<span class="apii">[-0, +0, <em>-</em>]</span> 3020<pre>int lua_isboolean (lua_State *L, int index);</pre> 3021 3022<p> 3023Returns 1 if the value at the given acceptable index has type boolean, 3024and 0 otherwise. 3025 3026 3027 3028 3029 3030<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3031<span class="apii">[-0, +0, <em>-</em>]</span> 3032<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3033 3034<p> 3035Returns 1 if the value at the given acceptable index is a C function, 3036and 0 otherwise. 3037 3038 3039 3040 3041 3042<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3043<span class="apii">[-0, +0, <em>-</em>]</span> 3044<pre>int lua_isfunction (lua_State *L, int index);</pre> 3045 3046<p> 3047Returns 1 if the value at the given acceptable index is a function 3048(either C or Lua), and 0 otherwise. 3049 3050 3051 3052 3053 3054<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3055<span class="apii">[-0, +0, <em>-</em>]</span> 3056<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3057 3058<p> 3059Returns 1 if the value at the given acceptable index is a light userdata, 3060and 0 otherwise. 3061 3062 3063 3064 3065 3066<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3067<span class="apii">[-0, +0, <em>-</em>]</span> 3068<pre>int lua_isnil (lua_State *L, int index);</pre> 3069 3070<p> 3071Returns 1 if the value at the given acceptable index is <b>nil</b>, 3072and 0 otherwise. 3073 3074 3075 3076 3077 3078<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3079<span class="apii">[-0, +0, <em>-</em>]</span> 3080<pre>int lua_isnone (lua_State *L, int index);</pre> 3081 3082<p> 3083Returns 1 if the given acceptable index is not valid 3084(that is, it refers to an element outside the current stack), 3085and 0 otherwise. 3086 3087 3088 3089 3090 3091<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3092<span class="apii">[-0, +0, <em>-</em>]</span> 3093<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3094 3095<p> 3096Returns 1 if the given acceptable index is not valid 3097(that is, it refers to an element outside the current stack) 3098or if the value at this index is <b>nil</b>, 3099and 0 otherwise. 3100 3101 3102 3103 3104 3105<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3106<span class="apii">[-0, +0, <em>-</em>]</span> 3107<pre>int lua_isnumber (lua_State *L, int index);</pre> 3108 3109<p> 3110Returns 1 if the value at the given acceptable index is a number 3111or a string convertible to a number, 3112and 0 otherwise. 3113 3114 3115 3116 3117 3118<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3119<span class="apii">[-0, +0, <em>-</em>]</span> 3120<pre>int lua_isstring (lua_State *L, int index);</pre> 3121 3122<p> 3123Returns 1 if the value at the given acceptable index is a string 3124or a number (which is always convertible to a string), 3125and 0 otherwise. 3126 3127 3128 3129 3130 3131<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3132<span class="apii">[-0, +0, <em>-</em>]</span> 3133<pre>int lua_istable (lua_State *L, int index);</pre> 3134 3135<p> 3136Returns 1 if the value at the given acceptable index is a table, 3137and 0 otherwise. 3138 3139 3140 3141 3142 3143<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3144<span class="apii">[-0, +0, <em>-</em>]</span> 3145<pre>int lua_isthread (lua_State *L, int index);</pre> 3146 3147<p> 3148Returns 1 if the value at the given acceptable index is a thread, 3149and 0 otherwise. 3150 3151 3152 3153 3154 3155<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3156<span class="apii">[-0, +0, <em>-</em>]</span> 3157<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3158 3159<p> 3160Returns 1 if the value at the given acceptable index is a userdata 3161(either full or light), and 0 otherwise. 3162 3163 3164 3165 3166 3167<hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p> 3168<span class="apii">[-0, +0, <em>e</em>]</span> 3169<pre>int lua_lessthan (lua_State *L, int index1, int index2);</pre> 3170 3171<p> 3172Returns 1 if the value at acceptable index <code>index1</code> is smaller 3173than the value at acceptable index <code>index2</code>, 3174following the semantics of the Lua <code><</code> operator 3175(that is, may call metamethods). 3176Otherwise returns 0. 3177Also returns 0 if any of the indices is non valid. 3178 3179 3180 3181 3182 3183<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3184<span class="apii">[-0, +1, <em>-</em>]</span> 3185<pre>int lua_load (lua_State *L, 3186 lua_Reader reader, 3187 void *data, 3188 const char *chunkname);</pre> 3189 3190<p> 3191Loads a Lua chunk. 3192If there are no errors, 3193<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua 3194function on top of the stack. 3195Otherwise, it pushes an error message. 3196The return values of <a href="#lua_load"><code>lua_load</code></a> are: 3197 3198<ul> 3199 3200<li><b>0:</b> no errors;</li> 3201 3202<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b> 3203syntax error during pre-compilation;</li> 3204 3205<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> 3206memory allocation error.</li> 3207 3208</ul> 3209 3210<p> 3211This function only loads a chunk; 3212it does not run it. 3213 3214 3215<p> 3216<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary, 3217and loads it accordingly (see program <code>luac</code>). 3218 3219 3220<p> 3221The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function 3222to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 3223The <code>data</code> argument is an opaque value passed to the reader function. 3224 3225 3226<p> 3227The <code>chunkname</code> argument gives a name to the chunk, 3228which is used for error messages and in debug information (see <a href="#3.8">§3.8</a>). 3229 3230 3231 3232 3233 3234<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 3235<span class="apii">[-0, +0, <em>-</em>]</span> 3236<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 3237 3238<p> 3239Creates a new, independent state. 3240Returns <code>NULL</code> if cannot create the state 3241(due to lack of memory). 3242The argument <code>f</code> is the allocator function; 3243Lua does all memory allocation for this state through this function. 3244The second argument, <code>ud</code>, is an opaque pointer that Lua 3245simply passes to the allocator in every call. 3246 3247 3248 3249 3250 3251<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 3252<span class="apii">[-0, +1, <em>m</em>]</span> 3253<pre>void lua_newtable (lua_State *L);</pre> 3254 3255<p> 3256Creates a new empty table and pushes it onto the stack. 3257It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 3258 3259 3260 3261 3262 3263<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 3264<span class="apii">[-0, +1, <em>m</em>]</span> 3265<pre>lua_State *lua_newthread (lua_State *L);</pre> 3266 3267<p> 3268Creates a new thread, pushes it on the stack, 3269and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 3270The new state returned by this function shares with the original state 3271all global objects (such as tables), 3272but has an independent execution stack. 3273 3274 3275<p> 3276There is no explicit function to close or to destroy a thread. 3277Threads are subject to garbage collection, 3278like any Lua object. 3279 3280 3281 3282 3283 3284<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 3285<span class="apii">[-0, +1, <em>m</em>]</span> 3286<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 3287 3288<p> 3289This function allocates a new block of memory with the given size, 3290pushes onto the stack a new full userdata with the block address, 3291and returns this address. 3292 3293 3294<p> 3295Userdata represent C values in Lua. 3296A <em>full userdata</em> represents a block of memory. 3297It is an object (like a table): 3298you must create it, it can have its own metatable, 3299and you can detect when it is being collected. 3300A full userdata is only equal to itself (under raw equality). 3301 3302 3303<p> 3304When Lua collects a full userdata with a <code>gc</code> metamethod, 3305Lua calls the metamethod and marks the userdata as finalized. 3306When this userdata is collected again then 3307Lua frees its corresponding memory. 3308 3309 3310 3311 3312 3313<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 3314<span class="apii">[-1, +(2|0), <em>e</em>]</span> 3315<pre>int lua_next (lua_State *L, int index);</pre> 3316 3317<p> 3318Pops a key from the stack, 3319and pushes a key-value pair from the table at the given index 3320(the "next" pair after the given key). 3321If there are no more elements in the table, 3322then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 3323 3324 3325<p> 3326A typical traversal looks like this: 3327 3328<pre> 3329 /* table is in the stack at index 't' */ 3330 lua_pushnil(L); /* first key */ 3331 while (lua_next(L, t) != 0) { 3332 /* uses 'key' (at index -2) and 'value' (at index -1) */ 3333 printf("%s - %s\n", 3334 lua_typename(L, lua_type(L, -2)), 3335 lua_typename(L, lua_type(L, -1))); 3336 /* removes 'value'; keeps 'key' for next iteration */ 3337 lua_pop(L, 1); 3338 } 3339</pre> 3340 3341<p> 3342While traversing a table, 3343do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 3344unless you know that the key is actually a string. 3345Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em> 3346the value at the given index; 3347this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 3348 3349 3350 3351 3352 3353<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 3354<pre>typedef double lua_Number;</pre> 3355 3356<p> 3357The type of numbers in Lua. 3358By default, it is double, but that can be changed in <code>luaconf.h</code>. 3359 3360 3361<p> 3362Through the configuration file you can change 3363Lua to operate with another type for numbers (e.g., float or long). 3364 3365 3366 3367 3368 3369<hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p> 3370<span class="apii">[-0, +0, <em>-</em>]</span> 3371<pre>size_t lua_objlen (lua_State *L, int index);</pre> 3372 3373<p> 3374Returns the "length" of the value at the given acceptable index: 3375for strings, this is the string length; 3376for tables, this is the result of the length operator ('<code>#</code>'); 3377for userdata, this is the size of the block of memory allocated 3378for the userdata; 3379for other values, it is 0. 3380 3381 3382 3383 3384 3385<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 3386<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span> 3387<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);</pre> 3388 3389<p> 3390Calls a function in protected mode. 3391 3392 3393<p> 3394Both <code>nargs</code> and <code>nresults</code> have the same meaning as 3395in <a href="#lua_call"><code>lua_call</code></a>. 3396If there are no errors during the call, 3397<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 3398However, if there is any error, 3399<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 3400pushes a single value on the stack (the error message), 3401and returns an error code. 3402Like <a href="#lua_call"><code>lua_call</code></a>, 3403<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 3404and its arguments from the stack. 3405 3406 3407<p> 3408If <code>errfunc</code> is 0, 3409then the error message returned on the stack 3410is exactly the original error message. 3411Otherwise, <code>errfunc</code> is the stack index of an 3412<em>error handler function</em>. 3413(In the current implementation, this index cannot be a pseudo-index.) 3414In case of runtime errors, 3415this function will be called with the error message 3416and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 3417 3418 3419<p> 3420Typically, the error handler function is used to add more debug 3421information to the error message, such as a stack traceback. 3422Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 3423since by then the stack has unwound. 3424 3425 3426<p> 3427The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success 3428or one of the following error codes 3429(defined in <code>lua.h</code>): 3430 3431<ul> 3432 3433<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b> 3434a runtime error. 3435</li> 3436 3437<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> 3438memory allocation error. 3439For such errors, Lua does not call the error handler function. 3440</li> 3441 3442<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b> 3443error while running the error handler function. 3444</li> 3445 3446</ul> 3447 3448 3449 3450 3451<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 3452<span class="apii">[-n, +0, <em>-</em>]</span> 3453<pre>void lua_pop (lua_State *L, int n);</pre> 3454 3455<p> 3456Pops <code>n</code> elements from the stack. 3457 3458 3459 3460 3461 3462<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 3463<span class="apii">[-0, +1, <em>-</em>]</span> 3464<pre>void lua_pushboolean (lua_State *L, int b);</pre> 3465 3466<p> 3467Pushes a boolean value with value <code>b</code> onto the stack. 3468 3469 3470 3471 3472 3473<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 3474<span class="apii">[-n, +1, <em>m</em>]</span> 3475<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 3476 3477<p> 3478Pushes a new C closure onto the stack. 3479 3480 3481<p> 3482When a C function is created, 3483it is possible to associate some values with it, 3484thus creating a C closure (see <a href="#3.4">§3.4</a>); 3485these values are then accessible to the function whenever it is called. 3486To associate values with a C function, 3487first these values should be pushed onto the stack 3488(when there are multiple values, the first value is pushed first). 3489Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 3490is called to create and push the C function onto the stack, 3491with the argument <code>n</code> telling how many values should be 3492associated with the function. 3493<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 3494 3495 3496<p> 3497The maximum value for <code>n</code> is 255. 3498 3499 3500 3501 3502 3503<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 3504<span class="apii">[-0, +1, <em>m</em>]</span> 3505<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 3506 3507<p> 3508Pushes a C function onto the stack. 3509This function receives a pointer to a C function 3510and pushes onto the stack a Lua value of type <code>function</code> that, 3511when called, invokes the corresponding C function. 3512 3513 3514<p> 3515Any function to be registered in Lua must 3516follow the correct protocol to receive its parameters 3517and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 3518 3519 3520<p> 3521<code>lua_pushcfunction</code> is defined as a macro: 3522 3523<pre> 3524 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) 3525</pre> 3526 3527 3528 3529 3530<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 3531<span class="apii">[-0, +1, <em>m</em>]</span> 3532<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 3533 3534<p> 3535Pushes onto the stack a formatted string 3536and returns a pointer to this string. 3537It is similar to the C function <code>sprintf</code>, 3538but has some important differences: 3539 3540<ul> 3541 3542<li> 3543You do not have to allocate space for the result: 3544the result is a Lua string and Lua takes care of memory allocation 3545(and deallocation, through garbage collection). 3546</li> 3547 3548<li> 3549The conversion specifiers are quite restricted. 3550There are no flags, widths, or precisions. 3551The conversion specifiers can only be 3552'<code>%%</code>' (inserts a '<code>%</code>' in the string), 3553'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 3554'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 3555'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 3556'<code>%d</code>' (inserts an <code>int</code>), and 3557'<code>%c</code>' (inserts an <code>int</code> as a character). 3558</li> 3559 3560</ul> 3561 3562 3563 3564 3565<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 3566<span class="apii">[-0, +1, <em>-</em>]</span> 3567<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 3568 3569<p> 3570Pushes a number with value <code>n</code> onto the stack. 3571 3572 3573 3574 3575 3576<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 3577<span class="apii">[-0, +1, <em>-</em>]</span> 3578<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 3579 3580<p> 3581Pushes a light userdata onto the stack. 3582 3583 3584<p> 3585Userdata represent C values in Lua. 3586A <em>light userdata</em> represents a pointer. 3587It is a value (like a number): 3588you do not create it, it has no individual metatable, 3589and it is not collected (as it was never created). 3590A light userdata is equal to "any" 3591light userdata with the same C address. 3592 3593 3594 3595 3596 3597<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 3598<span class="apii">[-0, +1, <em>m</em>]</span> 3599<pre>void lua_pushliteral (lua_State *L, const char *s);</pre> 3600 3601<p> 3602This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 3603but can be used only when <code>s</code> is a literal string. 3604In these cases, it automatically provides the string length. 3605 3606 3607 3608 3609 3610<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 3611<span class="apii">[-0, +1, <em>m</em>]</span> 3612<pre>void lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 3613 3614<p> 3615Pushes the string pointed to by <code>s</code> with size <code>len</code> 3616onto the stack. 3617Lua makes (or reuses) an internal copy of the given string, 3618so the memory at <code>s</code> can be freed or reused immediately after 3619the function returns. 3620The string can contain embedded zeros. 3621 3622 3623 3624 3625 3626<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 3627<span class="apii">[-0, +1, <em>-</em>]</span> 3628<pre>void lua_pushnil (lua_State *L);</pre> 3629 3630<p> 3631Pushes a nil value onto the stack. 3632 3633 3634 3635 3636 3637<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 3638<span class="apii">[-0, +1, <em>-</em>]</span> 3639<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 3640 3641<p> 3642Pushes a number with value <code>n</code> onto the stack. 3643 3644 3645 3646 3647 3648<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 3649<span class="apii">[-0, +1, <em>m</em>]</span> 3650<pre>void lua_pushstring (lua_State *L, const char *s);</pre> 3651 3652<p> 3653Pushes the zero-terminated string pointed to by <code>s</code> 3654onto the stack. 3655Lua makes (or reuses) an internal copy of the given string, 3656so the memory at <code>s</code> can be freed or reused immediately after 3657the function returns. 3658The string cannot contain embedded zeros; 3659it is assumed to end at the first zero. 3660 3661 3662 3663 3664 3665<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 3666<span class="apii">[-0, +1, <em>-</em>]</span> 3667<pre>int lua_pushthread (lua_State *L);</pre> 3668 3669<p> 3670Pushes the thread represented by <code>L</code> onto the stack. 3671Returns 1 if this thread is the main thread of its state. 3672 3673 3674 3675 3676 3677<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 3678<span class="apii">[-0, +1, <em>-</em>]</span> 3679<pre>void lua_pushvalue (lua_State *L, int index);</pre> 3680 3681<p> 3682Pushes a copy of the element at the given valid index 3683onto the stack. 3684 3685 3686 3687 3688 3689<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 3690<span class="apii">[-0, +1, <em>m</em>]</span> 3691<pre>const char *lua_pushvfstring (lua_State *L, 3692 const char *fmt, 3693 va_list argp);</pre> 3694 3695<p> 3696Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 3697instead of a variable number of arguments. 3698 3699 3700 3701 3702 3703<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 3704<span class="apii">[-0, +0, <em>-</em>]</span> 3705<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 3706 3707<p> 3708Returns 1 if the two values in acceptable indices <code>index1</code> and 3709<code>index2</code> are primitively equal 3710(that is, without calling metamethods). 3711Otherwise returns 0. 3712Also returns 0 if any of the indices are non valid. 3713 3714 3715 3716 3717 3718<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 3719<span class="apii">[-1, +1, <em>-</em>]</span> 3720<pre>void lua_rawget (lua_State *L, int index);</pre> 3721 3722<p> 3723Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 3724(i.e., without metamethods). 3725 3726 3727 3728 3729 3730<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 3731<span class="apii">[-0, +1, <em>-</em>]</span> 3732<pre>void lua_rawgeti (lua_State *L, int index, int n);</pre> 3733 3734<p> 3735Pushes onto the stack the value <code>t[n]</code>, 3736where <code>t</code> is the value at the given valid index. 3737The access is raw; 3738that is, it does not invoke metamethods. 3739 3740 3741 3742 3743 3744<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 3745<span class="apii">[-2, +0, <em>m</em>]</span> 3746<pre>void lua_rawset (lua_State *L, int index);</pre> 3747 3748<p> 3749Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 3750(i.e., without metamethods). 3751 3752 3753 3754 3755 3756<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 3757<span class="apii">[-1, +0, <em>m</em>]</span> 3758<pre>void lua_rawseti (lua_State *L, int index, int n);</pre> 3759 3760<p> 3761Does the equivalent of <code>t[n] = v</code>, 3762where <code>t</code> is the value at the given valid index 3763and <code>v</code> is the value at the top of the stack. 3764 3765 3766<p> 3767This function pops the value from the stack. 3768The assignment is raw; 3769that is, it does not invoke metamethods. 3770 3771 3772 3773 3774 3775<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 3776<pre>typedef const char * (*lua_Reader) (lua_State *L, 3777 void *data, 3778 size_t *size);</pre> 3779 3780<p> 3781The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 3782Every time it needs another piece of the chunk, 3783<a href="#lua_load"><code>lua_load</code></a> calls the reader, 3784passing along its <code>data</code> parameter. 3785The reader must return a pointer to a block of memory 3786with a new piece of the chunk 3787and set <code>size</code> to the block size. 3788The block must exist until the reader function is called again. 3789To signal the end of the chunk, 3790the reader must return <code>NULL</code> or set <code>size</code> to zero. 3791The reader function may return pieces of any size greater than zero. 3792 3793 3794 3795 3796 3797<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 3798<span class="apii">[-0, +0, <em>e</em>]</span> 3799<pre>void lua_register (lua_State *L, 3800 const char *name, 3801 lua_CFunction f);</pre> 3802 3803<p> 3804Sets the C function <code>f</code> as the new value of global <code>name</code>. 3805It is defined as a macro: 3806 3807<pre> 3808 #define lua_register(L,n,f) \ 3809 (lua_pushcfunction(L, f), lua_setglobal(L, n)) 3810</pre> 3811 3812 3813 3814 3815<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 3816<span class="apii">[-1, +0, <em>-</em>]</span> 3817<pre>void lua_remove (lua_State *L, int index);</pre> 3818 3819<p> 3820Removes the element at the given valid index, 3821shifting down the elements above this index to fill the gap. 3822Cannot be called with a pseudo-index, 3823because a pseudo-index is not an actual stack position. 3824 3825 3826 3827 3828 3829<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 3830<span class="apii">[-1, +0, <em>-</em>]</span> 3831<pre>void lua_replace (lua_State *L, int index);</pre> 3832 3833<p> 3834Moves the top element into the given position (and pops it), 3835without shifting any element 3836(therefore replacing the value at the given position). 3837 3838 3839 3840 3841 3842<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 3843<span class="apii">[-?, +?, <em>-</em>]</span> 3844<pre>int lua_resume (lua_State *L, int narg);</pre> 3845 3846<p> 3847Starts and resumes a coroutine in a given thread. 3848 3849 3850<p> 3851To start a coroutine, you first create a new thread 3852(see <a href="#lua_newthread"><code>lua_newthread</code></a>); 3853then you push onto its stack the main function plus any arguments; 3854then you call <a href="#lua_resume"><code>lua_resume</code></a>, 3855with <code>narg</code> being the number of arguments. 3856This call returns when the coroutine suspends or finishes its execution. 3857When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 3858or all values returned by the body function. 3859<a href="#lua_resume"><code>lua_resume</code></a> returns 3860<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 38610 if the coroutine finishes its execution 3862without errors, 3863or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 3864In case of errors, 3865the stack is not unwound, 3866so you can use the debug API over it. 3867The error message is on the top of the stack. 3868To restart a coroutine, you put on its stack only the values to 3869be passed as results from <code>yield</code>, 3870and then call <a href="#lua_resume"><code>lua_resume</code></a>. 3871 3872 3873 3874 3875 3876<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 3877<span class="apii">[-0, +0, <em>-</em>]</span> 3878<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 3879 3880<p> 3881Changes the allocator function of a given state to <code>f</code> 3882with user data <code>ud</code>. 3883 3884 3885 3886 3887 3888<hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p> 3889<span class="apii">[-1, +0, <em>-</em>]</span> 3890<pre>int lua_setfenv (lua_State *L, int index);</pre> 3891 3892<p> 3893Pops a table from the stack and sets it as 3894the new environment for the value at the given index. 3895If the value at the given index is 3896neither a function nor a thread nor a userdata, 3897<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0. 3898Otherwise it returns 1. 3899 3900 3901 3902 3903 3904<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 3905<span class="apii">[-1, +0, <em>e</em>]</span> 3906<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 3907 3908<p> 3909Does the equivalent to <code>t[k] = v</code>, 3910where <code>t</code> is the value at the given valid index 3911and <code>v</code> is the value at the top of the stack. 3912 3913 3914<p> 3915This function pops the value from the stack. 3916As in Lua, this function may trigger a metamethod 3917for the "newindex" event (see <a href="#2.8">§2.8</a>). 3918 3919 3920 3921 3922 3923<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 3924<span class="apii">[-1, +0, <em>e</em>]</span> 3925<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 3926 3927<p> 3928Pops a value from the stack and 3929sets it as the new value of global <code>name</code>. 3930It is defined as a macro: 3931 3932<pre> 3933 #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) 3934</pre> 3935 3936 3937 3938 3939<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 3940<span class="apii">[-1, +0, <em>-</em>]</span> 3941<pre>int lua_setmetatable (lua_State *L, int index);</pre> 3942 3943<p> 3944Pops a table from the stack and 3945sets it as the new metatable for the value at the given 3946acceptable index. 3947 3948 3949 3950 3951 3952<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 3953<span class="apii">[-2, +0, <em>e</em>]</span> 3954<pre>void lua_settable (lua_State *L, int index);</pre> 3955 3956<p> 3957Does the equivalent to <code>t[k] = v</code>, 3958where <code>t</code> is the value at the given valid index, 3959<code>v</code> is the value at the top of the stack, 3960and <code>k</code> is the value just below the top. 3961 3962 3963<p> 3964This function pops both the key and the value from the stack. 3965As in Lua, this function may trigger a metamethod 3966for the "newindex" event (see <a href="#2.8">§2.8</a>). 3967 3968 3969 3970 3971 3972<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 3973<span class="apii">[-?, +?, <em>-</em>]</span> 3974<pre>void lua_settop (lua_State *L, int index);</pre> 3975 3976<p> 3977Accepts any acceptable index, or 0, 3978and sets the stack top to this index. 3979If the new top is larger than the old one, 3980then the new elements are filled with <b>nil</b>. 3981If <code>index</code> is 0, then all stack elements are removed. 3982 3983 3984 3985 3986 3987<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 3988<pre>typedef struct lua_State lua_State;</pre> 3989 3990<p> 3991Opaque structure that keeps the whole state of a Lua interpreter. 3992The Lua library is fully reentrant: 3993it has no global variables. 3994All information about a state is kept in this structure. 3995 3996 3997<p> 3998A pointer to this state must be passed as the first argument to 3999every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4000which creates a Lua state from scratch. 4001 4002 4003 4004 4005 4006<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4007<span class="apii">[-0, +0, <em>-</em>]</span> 4008<pre>int lua_status (lua_State *L);</pre> 4009 4010<p> 4011Returns the status of the thread <code>L</code>. 4012 4013 4014<p> 4015The status can be 0 for a normal thread, 4016an error code if the thread finished its execution with an error, 4017or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4018 4019 4020 4021 4022 4023<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 4024<span class="apii">[-0, +0, <em>-</em>]</span> 4025<pre>int lua_toboolean (lua_State *L, int index);</pre> 4026 4027<p> 4028Converts the Lua value at the given acceptable index to a C boolean 4029value (0 or 1). 4030Like all tests in Lua, 4031<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value 4032different from <b>false</b> and <b>nil</b>; 4033otherwise it returns 0. 4034It also returns 0 when called with a non-valid index. 4035(If you want to accept only actual boolean values, 4036use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 4037 4038 4039 4040 4041 4042<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 4043<span class="apii">[-0, +0, <em>-</em>]</span> 4044<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 4045 4046<p> 4047Converts a value at the given acceptable index to a C function. 4048That value must be a C function; 4049otherwise, returns <code>NULL</code>. 4050 4051 4052 4053 4054 4055<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 4056<span class="apii">[-0, +0, <em>-</em>]</span> 4057<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 4058 4059<p> 4060Converts the Lua value at the given acceptable index 4061to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 4062The Lua value must be a number or a string convertible to a number 4063(see <a href="#2.2.1">§2.2.1</a>); 4064otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. 4065 4066 4067<p> 4068If the number is not an integer, 4069it is truncated in some non-specified way. 4070 4071 4072 4073 4074 4075<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 4076<span class="apii">[-0, +0, <em>m</em>]</span> 4077<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 4078 4079<p> 4080Converts the Lua value at the given acceptable index to a C string. 4081If <code>len</code> is not <code>NULL</code>, 4082it also sets <code>*len</code> with the string length. 4083The Lua value must be a string or a number; 4084otherwise, the function returns <code>NULL</code>. 4085If the value is a number, 4086then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also 4087<em>changes the actual value in the stack to a string</em>. 4088(This change confuses <a href="#lua_next"><code>lua_next</code></a> 4089when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) 4090 4091 4092<p> 4093<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer 4094to a string inside the Lua state. 4095This string always has a zero ('<code>\0</code>') 4096after its last character (as in C), 4097but can contain other zeros in its body. 4098Because Lua has garbage collection, 4099there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a> 4100will be valid after the corresponding value is removed from the stack. 4101 4102 4103 4104 4105 4106<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 4107<span class="apii">[-0, +0, <em>-</em>]</span> 4108<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 4109 4110<p> 4111Converts the Lua value at the given acceptable index 4112to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 4113The Lua value must be a number or a string convertible to a number 4114(see <a href="#2.2.1">§2.2.1</a>); 4115otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. 4116 4117 4118 4119 4120 4121<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 4122<span class="apii">[-0, +0, <em>-</em>]</span> 4123<pre>const void *lua_topointer (lua_State *L, int index);</pre> 4124 4125<p> 4126Converts the value at the given acceptable index to a generic 4127C pointer (<code>void*</code>). 4128The value can be a userdata, a table, a thread, or a function; 4129otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. 4130Different objects will give different pointers. 4131There is no way to convert the pointer back to its original value. 4132 4133 4134<p> 4135Typically this function is used only for debug information. 4136 4137 4138 4139 4140 4141<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 4142<span class="apii">[-0, +0, <em>m</em>]</span> 4143<pre>const char *lua_tostring (lua_State *L, int index);</pre> 4144 4145<p> 4146Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 4147 4148 4149 4150 4151 4152<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 4153<span class="apii">[-0, +0, <em>-</em>]</span> 4154<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 4155 4156<p> 4157Converts the value at the given acceptable index to a Lua thread 4158(represented as <code>lua_State*</code>). 4159This value must be a thread; 4160otherwise, the function returns <code>NULL</code>. 4161 4162 4163 4164 4165 4166<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 4167<span class="apii">[-0, +0, <em>-</em>]</span> 4168<pre>void *lua_touserdata (lua_State *L, int index);</pre> 4169 4170<p> 4171If the value at the given acceptable index is a full userdata, 4172returns its block address. 4173If the value is a light userdata, 4174returns its pointer. 4175Otherwise, returns <code>NULL</code>. 4176 4177 4178 4179 4180 4181<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 4182<span class="apii">[-0, +0, <em>-</em>]</span> 4183<pre>int lua_type (lua_State *L, int index);</pre> 4184 4185<p> 4186Returns the type of the value in the given acceptable index, 4187or <code>LUA_TNONE</code> for a non-valid index 4188(that is, an index to an "empty" stack position). 4189The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 4190defined in <code>lua.h</code>: 4191<code>LUA_TNIL</code>, 4192<code>LUA_TNUMBER</code>, 4193<code>LUA_TBOOLEAN</code>, 4194<code>LUA_TSTRING</code>, 4195<code>LUA_TTABLE</code>, 4196<code>LUA_TFUNCTION</code>, 4197<code>LUA_TUSERDATA</code>, 4198<code>LUA_TTHREAD</code>, 4199and 4200<code>LUA_TLIGHTUSERDATA</code>. 4201 4202 4203 4204 4205 4206<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 4207<span class="apii">[-0, +0, <em>-</em>]</span> 4208<pre>const char *lua_typename (lua_State *L, int tp);</pre> 4209 4210<p> 4211Returns the name of the type encoded by the value <code>tp</code>, 4212which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 4213 4214 4215 4216 4217 4218<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 4219<pre>typedef int (*lua_Writer) (lua_State *L, 4220 const void* p, 4221 size_t sz, 4222 void* ud);</pre> 4223 4224<p> 4225The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 4226Every time it produces another piece of chunk, 4227<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 4228passing along the buffer to be written (<code>p</code>), 4229its size (<code>sz</code>), 4230and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 4231 4232 4233<p> 4234The writer returns an error code: 42350 means no errors; 4236any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 4237calling the writer again. 4238 4239 4240 4241 4242 4243<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 4244<span class="apii">[-?, +?, <em>-</em>]</span> 4245<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 4246 4247<p> 4248Exchange values between different threads of the <em>same</em> global state. 4249 4250 4251<p> 4252This function pops <code>n</code> values from the stack <code>from</code>, 4253and pushes them onto the stack <code>to</code>. 4254 4255 4256 4257 4258 4259<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 4260<span class="apii">[-?, +?, <em>-</em>]</span> 4261<pre>int lua_yield (lua_State *L, int nresults);</pre> 4262 4263<p> 4264Yields a coroutine. 4265 4266 4267<p> 4268This function should only be called as the 4269return expression of a C function, as follows: 4270 4271<pre> 4272 return lua_yield (L, nresults); 4273</pre><p> 4274When a C function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way, 4275the running coroutine suspends its execution, 4276and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 4277The parameter <code>nresults</code> is the number of values from the stack 4278that are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 4279 4280 4281 4282 4283 4284 4285 4286<h2>3.8 - <a name="3.8">The Debug Interface</a></h2> 4287 4288<p> 4289Lua has no built-in debugging facilities. 4290Instead, it offers a special interface 4291by means of functions and <em>hooks</em>. 4292This interface allows the construction of different 4293kinds of debuggers, profilers, and other tools 4294that need "inside information" from the interpreter. 4295 4296 4297 4298<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 4299<pre>typedef struct lua_Debug { 4300 int event; 4301 const char *name; /* (n) */ 4302 const char *namewhat; /* (n) */ 4303 const char *what; /* (S) */ 4304 const char *source; /* (S) */ 4305 int currentline; /* (l) */ 4306 int nups; /* (u) number of upvalues */ 4307 int linedefined; /* (S) */ 4308 int lastlinedefined; /* (S) */ 4309 char short_src[LUA_IDSIZE]; /* (S) */ 4310 /* private part */ 4311 <em>other fields</em> 4312} lua_Debug;</pre> 4313 4314<p> 4315A structure used to carry different pieces of 4316information about an active function. 4317<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 4318of this structure, for later use. 4319To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 4320call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 4321 4322 4323<p> 4324The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 4325 4326<ul> 4327 4328<li><b><code>source</code>:</b> 4329If the function was defined in a string, 4330then <code>source</code> is that string. 4331If the function was defined in a file, 4332then <code>source</code> starts with a '<code>@</code>' followed by the file name. 4333</li> 4334 4335<li><b><code>short_src</code>:</b> 4336a "printable" version of <code>source</code>, to be used in error messages. 4337</li> 4338 4339<li><b><code>linedefined</code>:</b> 4340the line number where the definition of the function starts. 4341</li> 4342 4343<li><b><code>lastlinedefined</code>:</b> 4344the line number where the definition of the function ends. 4345</li> 4346 4347<li><b><code>what</code>:</b> 4348the string <code>"Lua"</code> if the function is a Lua function, 4349<code>"C"</code> if it is a C function, 4350<code>"main"</code> if it is the main part of a chunk, 4351and <code>"tail"</code> if it was a function that did a tail call. 4352In the latter case, 4353Lua has no other information about the function. 4354</li> 4355 4356<li><b><code>currentline</code>:</b> 4357the current line where the given function is executing. 4358When no line information is available, 4359<code>currentline</code> is set to -1. 4360</li> 4361 4362<li><b><code>name</code>:</b> 4363a reasonable name for the given function. 4364Because functions in Lua are first-class values, 4365they do not have a fixed name: 4366some functions can be the value of multiple global variables, 4367while others can be stored only in a table field. 4368The <code>lua_getinfo</code> function checks how the function was 4369called to find a suitable name. 4370If it cannot find a name, 4371then <code>name</code> is set to <code>NULL</code>. 4372</li> 4373 4374<li><b><code>namewhat</code>:</b> 4375explains the <code>name</code> field. 4376The value of <code>namewhat</code> can be 4377<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 4378<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 4379according to how the function was called. 4380(Lua uses the empty string when no other option seems to apply.) 4381</li> 4382 4383<li><b><code>nups</code>:</b> 4384the number of upvalues of the function. 4385</li> 4386 4387</ul> 4388 4389 4390 4391 4392<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 4393<span class="apii">[-0, +0, <em>-</em>]</span> 4394<pre>lua_Hook lua_gethook (lua_State *L);</pre> 4395 4396<p> 4397Returns the current hook function. 4398 4399 4400 4401 4402 4403<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 4404<span class="apii">[-0, +0, <em>-</em>]</span> 4405<pre>int lua_gethookcount (lua_State *L);</pre> 4406 4407<p> 4408Returns the current hook count. 4409 4410 4411 4412 4413 4414<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 4415<span class="apii">[-0, +0, <em>-</em>]</span> 4416<pre>int lua_gethookmask (lua_State *L);</pre> 4417 4418<p> 4419Returns the current hook mask. 4420 4421 4422 4423 4424 4425<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 4426<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 4427<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 4428 4429<p> 4430Returns information about a specific function or function invocation. 4431 4432 4433<p> 4434To get information about a function invocation, 4435the parameter <code>ar</code> must be a valid activation record that was 4436filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 4437given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 4438 4439 4440<p> 4441To get information about a function you push it onto the stack 4442and start the <code>what</code> string with the character '<code>></code>'. 4443(In that case, 4444<code>lua_getinfo</code> pops the function in the top of the stack.) 4445For instance, to know in which line a function <code>f</code> was defined, 4446you can write the following code: 4447 4448<pre> 4449 lua_Debug ar; 4450 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ 4451 lua_getinfo(L, ">S", &ar); 4452 printf("%d\n", ar.linedefined); 4453</pre> 4454 4455<p> 4456Each character in the string <code>what</code> 4457selects some fields of the structure <code>ar</code> to be filled or 4458a value to be pushed on the stack: 4459 4460<ul> 4461 4462<li><b>'<code>n</code>':</b> fills in the field <code>name</code> and <code>namewhat</code>; 4463</li> 4464 4465<li><b>'<code>S</code>':</b> 4466fills in the fields <code>source</code>, <code>short_src</code>, 4467<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 4468</li> 4469 4470<li><b>'<code>l</code>':</b> fills in the field <code>currentline</code>; 4471</li> 4472 4473<li><b>'<code>u</code>':</b> fills in the field <code>nups</code>; 4474</li> 4475 4476<li><b>'<code>f</code>':</b> 4477pushes onto the stack the function that is 4478running at the given level; 4479</li> 4480 4481<li><b>'<code>L</code>':</b> 4482pushes onto the stack a table whose indices are the 4483numbers of the lines that are valid on the function. 4484(A <em>valid line</em> is a line with some associated code, 4485that is, a line where you can put a break point. 4486Non-valid lines include empty lines and comments.) 4487</li> 4488 4489</ul> 4490 4491<p> 4492This function returns 0 on error 4493(for instance, an invalid option in <code>what</code>). 4494 4495 4496 4497 4498 4499<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 4500<span class="apii">[-0, +(0|1), <em>-</em>]</span> 4501<pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre> 4502 4503<p> 4504Gets information about a local variable of a given activation record. 4505The parameter <code>ar</code> must be a valid activation record that was 4506filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 4507given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 4508The index <code>n</code> selects which local variable to inspect 4509(1 is the first parameter or active local variable, and so on, 4510until the last active local variable). 4511<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 4512and returns its name. 4513 4514 4515<p> 4516Variable names starting with '<code>(</code>' (open parentheses) 4517represent internal variables 4518(loop control variables, temporaries, and C function locals). 4519 4520 4521<p> 4522Returns <code>NULL</code> (and pushes nothing) 4523when the index is greater than 4524the number of active local variables. 4525 4526 4527 4528 4529 4530<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 4531<span class="apii">[-0, +0, <em>-</em>]</span> 4532<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 4533 4534<p> 4535Get information about the interpreter runtime stack. 4536 4537 4538<p> 4539This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 4540an identification of the <em>activation record</em> 4541of the function executing at a given level. 4542Level 0 is the current running function, 4543whereas level <em>n+1</em> is the function that has called level <em>n</em>. 4544When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 4545when called with a level greater than the stack depth, 4546it returns 0. 4547 4548 4549 4550 4551 4552<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 4553<span class="apii">[-0, +(0|1), <em>-</em>]</span> 4554<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 4555 4556<p> 4557Gets information about a closure's upvalue. 4558(For Lua functions, 4559upvalues are the external local variables that the function uses, 4560and that are consequently included in its closure.) 4561<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue, 4562pushes the upvalue's value onto the stack, 4563and returns its name. 4564<code>funcindex</code> points to the closure in the stack. 4565(Upvalues have no particular order, 4566as they are active through the whole function. 4567So, they are numbered in an arbitrary order.) 4568 4569 4570<p> 4571Returns <code>NULL</code> (and pushes nothing) 4572when the index is greater than the number of upvalues. 4573For C functions, this function uses the empty string <code>""</code> 4574as a name for all upvalues. 4575 4576 4577 4578 4579 4580<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 4581<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 4582 4583<p> 4584Type for debugging hook functions. 4585 4586 4587<p> 4588Whenever a hook is called, its <code>ar</code> argument has its field 4589<code>event</code> set to the specific event that triggered the hook. 4590Lua identifies these events with the following constants: 4591<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 4592<a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 4593and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 4594Moreover, for line events, the field <code>currentline</code> is also set. 4595To get the value of any other field in <code>ar</code>, 4596the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 4597For return events, <code>event</code> can be <code>LUA_HOOKRET</code>, 4598the normal value, or <code>LUA_HOOKTAILRET</code>. 4599In the latter case, Lua is simulating a return from 4600a function that did a tail call; 4601in this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 4602 4603 4604<p> 4605While Lua is running a hook, it disables other calls to hooks. 4606Therefore, if a hook calls back Lua to execute a function or a chunk, 4607this execution occurs without any calls to hooks. 4608 4609 4610 4611 4612 4613<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 4614<span class="apii">[-0, +0, <em>-</em>]</span> 4615<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 4616 4617<p> 4618Sets the debugging hook function. 4619 4620 4621<p> 4622Argument <code>f</code> is the hook function. 4623<code>mask</code> specifies on which events the hook will be called: 4624it is formed by a bitwise or of the constants 4625<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 4626<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 4627<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 4628and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 4629The <code>count</code> argument is only meaningful when the mask 4630includes <code>LUA_MASKCOUNT</code>. 4631For each event, the hook is called as explained below: 4632 4633<ul> 4634 4635<li><b>The call hook:</b> is called when the interpreter calls a function. 4636The hook is called just after Lua enters the new function, 4637before the function gets its arguments. 4638</li> 4639 4640<li><b>The return hook:</b> is called when the interpreter returns from a function. 4641The hook is called just before Lua leaves the function. 4642You have no access to the values to be returned by the function. 4643</li> 4644 4645<li><b>The line hook:</b> is called when the interpreter is about to 4646start the execution of a new line of code, 4647or when it jumps back in the code (even to the same line). 4648(This event only happens while Lua is executing a Lua function.) 4649</li> 4650 4651<li><b>The count hook:</b> is called after the interpreter executes every 4652<code>count</code> instructions. 4653(This event only happens while Lua is executing a Lua function.) 4654</li> 4655 4656</ul> 4657 4658<p> 4659A hook is disabled by setting <code>mask</code> to zero. 4660 4661 4662 4663 4664 4665<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 4666<span class="apii">[-(0|1), +0, <em>-</em>]</span> 4667<pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre> 4668 4669<p> 4670Sets the value of a local variable of a given activation record. 4671Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> 4672(see <a href="#lua_getlocal"><code>lua_getlocal</code></a>). 4673<a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack 4674to the variable and returns its name. 4675It also pops the value from the stack. 4676 4677 4678<p> 4679Returns <code>NULL</code> (and pops nothing) 4680when the index is greater than 4681the number of active local variables. 4682 4683 4684 4685 4686 4687<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 4688<span class="apii">[-(0|1), +0, <em>-</em>]</span> 4689<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 4690 4691<p> 4692Sets the value of a closure's upvalue. 4693It assigns the value at the top of the stack 4694to the upvalue and returns its name. 4695It also pops the value from the stack. 4696Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 4697(see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>). 4698 4699 4700<p> 4701Returns <code>NULL</code> (and pops nothing) 4702when the index is greater than the number of upvalues. 4703 4704 4705 4706 4707 4708 4709 4710<h1>4 - <a name="4">The Auxiliary Library</a></h1> 4711 4712<p> 4713 4714The <em>auxiliary library</em> provides several convenient functions 4715to interface C with Lua. 4716While the basic API provides the primitive functions for all 4717interactions between C and Lua, 4718the auxiliary library provides higher-level functions for some 4719common tasks. 4720 4721 4722<p> 4723All functions from the auxiliary library 4724are defined in header file <code>lauxlib.h</code> and 4725have a prefix <code>luaL_</code>. 4726 4727 4728<p> 4729All functions in the auxiliary library are built on 4730top of the basic API, 4731and so they provide nothing that cannot be done with this API. 4732 4733 4734<p> 4735Several functions in the auxiliary library are used to 4736check C function arguments. 4737Their names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. 4738All of these functions throw an error if the check is not satisfied. 4739Because the error message is formatted for arguments 4740(e.g., "<code>bad argument #1</code>"), 4741you should not use these functions for other stack values. 4742 4743 4744 4745<h2>4.1 - <a name="4.1">Functions and Types</a></h2> 4746 4747<p> 4748Here we list all functions and types from the auxiliary library 4749in alphabetical order. 4750 4751 4752 4753<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 4754<span class="apii">[-0, +0, <em>m</em>]</span> 4755<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 4756 4757<p> 4758Adds the character <code>c</code> to the buffer <code>B</code> 4759(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4760 4761 4762 4763 4764 4765<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 4766<span class="apii">[-0, +0, <em>m</em>]</span> 4767<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 4768 4769<p> 4770Adds the string pointed to by <code>s</code> with length <code>l</code> to 4771the buffer <code>B</code> 4772(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4773The string may contain embedded zeros. 4774 4775 4776 4777 4778 4779<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 4780<span class="apii">[-0, +0, <em>m</em>]</span> 4781<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 4782 4783<p> 4784Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 4785a string of length <code>n</code> previously copied to the 4786buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 4787 4788 4789 4790 4791 4792<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 4793<span class="apii">[-0, +0, <em>m</em>]</span> 4794<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 4795 4796<p> 4797Adds the zero-terminated string pointed to by <code>s</code> 4798to the buffer <code>B</code> 4799(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4800The string may not contain embedded zeros. 4801 4802 4803 4804 4805 4806<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 4807<span class="apii">[-1, +0, <em>m</em>]</span> 4808<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 4809 4810<p> 4811Adds the value at the top of the stack 4812to the buffer <code>B</code> 4813(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4814Pops the value. 4815 4816 4817<p> 4818This is the only function on string buffers that can (and must) 4819be called with an extra element on the stack, 4820which is the value to be added to the buffer. 4821 4822 4823 4824 4825 4826<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 4827<span class="apii">[-0, +0, <em>v</em>]</span> 4828<pre>void luaL_argcheck (lua_State *L, 4829 int cond, 4830 int narg, 4831 const char *extramsg);</pre> 4832 4833<p> 4834Checks whether <code>cond</code> is true. 4835If not, raises an error with the following message, 4836where <code>func</code> is retrieved from the call stack: 4837 4838<pre> 4839 bad argument #<narg> to <func> (<extramsg>) 4840</pre> 4841 4842 4843 4844 4845<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 4846<span class="apii">[-0, +0, <em>v</em>]</span> 4847<pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre> 4848 4849<p> 4850Raises an error with the following message, 4851where <code>func</code> is retrieved from the call stack: 4852 4853<pre> 4854 bad argument #<narg> to <func> (<extramsg>) 4855</pre> 4856 4857<p> 4858This function never returns, 4859but it is an idiom to use it in C functions 4860as <code>return luaL_argerror(<em>args</em>)</code>. 4861 4862 4863 4864 4865 4866<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 4867<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 4868 4869<p> 4870Type for a <em>string buffer</em>. 4871 4872 4873<p> 4874A string buffer allows C code to build Lua strings piecemeal. 4875Its pattern of use is as follows: 4876 4877<ul> 4878 4879<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 4880 4881<li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 4882 4883<li> 4884Then you add string pieces to the buffer calling any of 4885the <code>luaL_add*</code> functions. 4886</li> 4887 4888<li> 4889You finish by calling <code>luaL_pushresult(&b)</code>. 4890This call leaves the final string on the top of the stack. 4891</li> 4892 4893</ul> 4894 4895<p> 4896During its normal operation, 4897a string buffer uses a variable number of stack slots. 4898So, while using a buffer, you cannot assume that you know where 4899the top of the stack is. 4900You can use the stack between successive calls to buffer operations 4901as long as that use is balanced; 4902that is, 4903when you call a buffer operation, 4904the stack is at the same level 4905it was immediately after the previous buffer operation. 4906(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 4907After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 4908level when the buffer was initialized, 4909plus the final string on its top. 4910 4911 4912 4913 4914 4915<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 4916<span class="apii">[-0, +0, <em>-</em>]</span> 4917<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 4918 4919<p> 4920Initializes a buffer <code>B</code>. 4921This function does not allocate any space; 4922the buffer must be declared as a variable 4923(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4924 4925 4926 4927 4928 4929<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 4930<span class="apii">[-0, +(0|1), <em>e</em>]</span> 4931<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 4932 4933<p> 4934Calls a metamethod. 4935 4936 4937<p> 4938If the object at index <code>obj</code> has a metatable and this 4939metatable has a field <code>e</code>, 4940this function calls this field and passes the object as its only argument. 4941In this case this function returns 1 and pushes onto the 4942stack the value returned by the call. 4943If there is no metatable or no metamethod, 4944this function returns 0 (without pushing any value on the stack). 4945 4946 4947 4948 4949 4950<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 4951<span class="apii">[-0, +0, <em>v</em>]</span> 4952<pre>void luaL_checkany (lua_State *L, int narg);</pre> 4953 4954<p> 4955Checks whether the function has an argument 4956of any type (including <b>nil</b>) at position <code>narg</code>. 4957 4958 4959 4960 4961 4962<hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p> 4963<span class="apii">[-0, +0, <em>v</em>]</span> 4964<pre>int luaL_checkint (lua_State *L, int narg);</pre> 4965 4966<p> 4967Checks whether the function argument <code>narg</code> is a number 4968and returns this number cast to an <code>int</code>. 4969 4970 4971 4972 4973 4974<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 4975<span class="apii">[-0, +0, <em>v</em>]</span> 4976<pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre> 4977 4978<p> 4979Checks whether the function argument <code>narg</code> is a number 4980and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 4981 4982 4983 4984 4985 4986<hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p> 4987<span class="apii">[-0, +0, <em>v</em>]</span> 4988<pre>long luaL_checklong (lua_State *L, int narg);</pre> 4989 4990<p> 4991Checks whether the function argument <code>narg</code> is a number 4992and returns this number cast to a <code>long</code>. 4993 4994 4995 4996 4997 4998<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 4999<span class="apii">[-0, +0, <em>v</em>]</span> 5000<pre>const char *luaL_checklstring (lua_State *L, int narg, size_t *l);</pre> 5001 5002<p> 5003Checks whether the function argument <code>narg</code> is a string 5004and returns this string; 5005if <code>l</code> is not <code>NULL</code> fills <code>*l</code> 5006with the string's length. 5007 5008 5009<p> 5010This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 5011so all conversions and caveats of that function apply here. 5012 5013 5014 5015 5016 5017<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 5018<span class="apii">[-0, +0, <em>v</em>]</span> 5019<pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre> 5020 5021<p> 5022Checks whether the function argument <code>narg</code> is a number 5023and returns this number. 5024 5025 5026 5027 5028 5029<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 5030<span class="apii">[-0, +0, <em>v</em>]</span> 5031<pre>int luaL_checkoption (lua_State *L, 5032 int narg, 5033 const char *def, 5034 const char *const lst[]);</pre> 5035 5036<p> 5037Checks whether the function argument <code>narg</code> is a string and 5038searches for this string in the array <code>lst</code> 5039(which must be NULL-terminated). 5040Returns the index in the array where the string was found. 5041Raises an error if the argument is not a string or 5042if the string cannot be found. 5043 5044 5045<p> 5046If <code>def</code> is not <code>NULL</code>, 5047the function uses <code>def</code> as a default value when 5048there is no argument <code>narg</code> or if this argument is <b>nil</b>. 5049 5050 5051<p> 5052This is a useful function for mapping strings to C enums. 5053(The usual convention in Lua libraries is 5054to use strings instead of numbers to select options.) 5055 5056 5057 5058 5059 5060<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 5061<span class="apii">[-0, +0, <em>v</em>]</span> 5062<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 5063 5064<p> 5065Grows the stack size to <code>top + sz</code> elements, 5066raising an error if the stack cannot grow to that size. 5067<code>msg</code> is an additional text to go into the error message. 5068 5069 5070 5071 5072 5073<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 5074<span class="apii">[-0, +0, <em>v</em>]</span> 5075<pre>const char *luaL_checkstring (lua_State *L, int narg);</pre> 5076 5077<p> 5078Checks whether the function argument <code>narg</code> is a string 5079and returns this string. 5080 5081 5082<p> 5083This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 5084so all conversions and caveats of that function apply here. 5085 5086 5087 5088 5089 5090<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 5091<span class="apii">[-0, +0, <em>v</em>]</span> 5092<pre>void luaL_checktype (lua_State *L, int narg, int t);</pre> 5093 5094<p> 5095Checks whether the function argument <code>narg</code> has type <code>t</code>. 5096See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 5097 5098 5099 5100 5101 5102<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 5103<span class="apii">[-0, +0, <em>v</em>]</span> 5104<pre>void *luaL_checkudata (lua_State *L, int narg, const char *tname);</pre> 5105 5106<p> 5107Checks whether the function argument <code>narg</code> is a userdata 5108of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 5109 5110 5111 5112 5113 5114<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 5115<span class="apii">[-0, +?, <em>m</em>]</span> 5116<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 5117 5118<p> 5119Loads and runs the given file. 5120It is defined as the following macro: 5121 5122<pre> 5123 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 5124</pre><p> 5125It returns 0 if there are no errors 5126or 1 in case of errors. 5127 5128 5129 5130 5131 5132<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 5133<span class="apii">[-0, +?, <em>m</em>]</span> 5134<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 5135 5136<p> 5137Loads and runs the given string. 5138It is defined as the following macro: 5139 5140<pre> 5141 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 5142</pre><p> 5143It returns 0 if there are no errors 5144or 1 in case of errors. 5145 5146 5147 5148 5149 5150<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 5151<span class="apii">[-0, +0, <em>v</em>]</span> 5152<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 5153 5154<p> 5155Raises an error. 5156The error message format is given by <code>fmt</code> 5157plus any extra arguments, 5158following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 5159It also adds at the beginning of the message the file name and 5160the line number where the error occurred, 5161if this information is available. 5162 5163 5164<p> 5165This function never returns, 5166but it is an idiom to use it in C functions 5167as <code>return luaL_error(<em>args</em>)</code>. 5168 5169 5170 5171 5172 5173<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 5174<span class="apii">[-0, +(0|1), <em>m</em>]</span> 5175<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 5176 5177<p> 5178Pushes onto the stack the field <code>e</code> from the metatable 5179of the object at index <code>obj</code>. 5180If the object does not have a metatable, 5181or if the metatable does not have this field, 5182returns 0 and pushes nothing. 5183 5184 5185 5186 5187 5188<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 5189<span class="apii">[-0, +1, <em>-</em>]</span> 5190<pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre> 5191 5192<p> 5193Pushes onto the stack the metatable associated with name <code>tname</code> 5194in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 5195 5196 5197 5198 5199 5200<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 5201<span class="apii">[-0, +1, <em>m</em>]</span> 5202<pre>const char *luaL_gsub (lua_State *L, 5203 const char *s, 5204 const char *p, 5205 const char *r);</pre> 5206 5207<p> 5208Creates a copy of string <code>s</code> by replacing 5209any occurrence of the string <code>p</code> 5210with the string <code>r</code>. 5211Pushes the resulting string on the stack and returns it. 5212 5213 5214 5215 5216 5217<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 5218<span class="apii">[-0, +1, <em>m</em>]</span> 5219<pre>int luaL_loadbuffer (lua_State *L, 5220 const char *buff, 5221 size_t sz, 5222 const char *name);</pre> 5223 5224<p> 5225Loads a buffer as a Lua chunk. 5226This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 5227buffer pointed to by <code>buff</code> with size <code>sz</code>. 5228 5229 5230<p> 5231This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 5232<code>name</code> is the chunk name, 5233used for debug information and error messages. 5234 5235 5236 5237 5238 5239<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 5240<span class="apii">[-0, +1, <em>m</em>]</span> 5241<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 5242 5243<p> 5244Loads a file as a Lua chunk. 5245This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 5246named <code>filename</code>. 5247If <code>filename</code> is <code>NULL</code>, 5248then it loads from the standard input. 5249The first line in the file is ignored if it starts with a <code>#</code>. 5250 5251 5252<p> 5253This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 5254but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 5255if it cannot open/read the file. 5256 5257 5258<p> 5259As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 5260it does not run it. 5261 5262 5263 5264 5265 5266<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 5267<span class="apii">[-0, +1, <em>m</em>]</span> 5268<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 5269 5270<p> 5271Loads a string as a Lua chunk. 5272This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 5273the zero-terminated string <code>s</code>. 5274 5275 5276<p> 5277This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 5278 5279 5280<p> 5281Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 5282it does not run it. 5283 5284 5285 5286 5287 5288<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 5289<span class="apii">[-0, +1, <em>m</em>]</span> 5290<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 5291 5292<p> 5293If the registry already has the key <code>tname</code>, 5294returns 0. 5295Otherwise, 5296creates a new table to be used as a metatable for userdata, 5297adds it to the registry with key <code>tname</code>, 5298and returns 1. 5299 5300 5301<p> 5302In both cases pushes onto the stack the final value associated 5303with <code>tname</code> in the registry. 5304 5305 5306 5307 5308 5309<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 5310<span class="apii">[-0, +0, <em>-</em>]</span> 5311<pre>lua_State *luaL_newstate (void);</pre> 5312 5313<p> 5314Creates a new Lua state. 5315It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 5316allocator based on the standard C <code>realloc</code> function 5317and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints 5318an error message to the standard error output in case of fatal 5319errors. 5320 5321 5322<p> 5323Returns the new state, 5324or <code>NULL</code> if there is a memory allocation error. 5325 5326 5327 5328 5329 5330<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 5331<span class="apii">[-0, +0, <em>m</em>]</span> 5332<pre>void luaL_openlibs (lua_State *L);</pre> 5333 5334<p> 5335Opens all standard Lua libraries into the given state. 5336 5337 5338 5339 5340 5341<hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p> 5342<span class="apii">[-0, +0, <em>v</em>]</span> 5343<pre>int luaL_optint (lua_State *L, int narg, int d);</pre> 5344 5345<p> 5346If the function argument <code>narg</code> is a number, 5347returns this number cast to an <code>int</code>. 5348If this argument is absent or is <b>nil</b>, 5349returns <code>d</code>. 5350Otherwise, raises an error. 5351 5352 5353 5354 5355 5356<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 5357<span class="apii">[-0, +0, <em>v</em>]</span> 5358<pre>lua_Integer luaL_optinteger (lua_State *L, 5359 int narg, 5360 lua_Integer d);</pre> 5361 5362<p> 5363If the function argument <code>narg</code> is a number, 5364returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 5365If this argument is absent or is <b>nil</b>, 5366returns <code>d</code>. 5367Otherwise, raises an error. 5368 5369 5370 5371 5372 5373<hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p> 5374<span class="apii">[-0, +0, <em>v</em>]</span> 5375<pre>long luaL_optlong (lua_State *L, int narg, long d);</pre> 5376 5377<p> 5378If the function argument <code>narg</code> is a number, 5379returns this number cast to a <code>long</code>. 5380If this argument is absent or is <b>nil</b>, 5381returns <code>d</code>. 5382Otherwise, raises an error. 5383 5384 5385 5386 5387 5388<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 5389<span class="apii">[-0, +0, <em>v</em>]</span> 5390<pre>const char *luaL_optlstring (lua_State *L, 5391 int narg, 5392 const char *d, 5393 size_t *l);</pre> 5394 5395<p> 5396If the function argument <code>narg</code> is a string, 5397returns this string. 5398If this argument is absent or is <b>nil</b>, 5399returns <code>d</code>. 5400Otherwise, raises an error. 5401 5402 5403<p> 5404If <code>l</code> is not <code>NULL</code>, 5405fills the position <code>*l</code> with the results's length. 5406 5407 5408 5409 5410 5411<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 5412<span class="apii">[-0, +0, <em>v</em>]</span> 5413<pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre> 5414 5415<p> 5416If the function argument <code>narg</code> is a number, 5417returns this number. 5418If this argument is absent or is <b>nil</b>, 5419returns <code>d</code>. 5420Otherwise, raises an error. 5421 5422 5423 5424 5425 5426<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 5427<span class="apii">[-0, +0, <em>v</em>]</span> 5428<pre>const char *luaL_optstring (lua_State *L, 5429 int narg, 5430 const char *d);</pre> 5431 5432<p> 5433If the function argument <code>narg</code> is a string, 5434returns this string. 5435If this argument is absent or is <b>nil</b>, 5436returns <code>d</code>. 5437Otherwise, raises an error. 5438 5439 5440 5441 5442 5443<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 5444<span class="apii">[-0, +0, <em>-</em>]</span> 5445<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 5446 5447<p> 5448Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a> 5449where you can copy a string to be added to buffer <code>B</code> 5450(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5451After copying the string into this space you must call 5452<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 5453it to the buffer. 5454 5455 5456 5457 5458 5459<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 5460<span class="apii">[-?, +1, <em>m</em>]</span> 5461<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 5462 5463<p> 5464Finishes the use of buffer <code>B</code> leaving the final string on 5465the top of the stack. 5466 5467 5468 5469 5470 5471<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 5472<span class="apii">[-1, +0, <em>m</em>]</span> 5473<pre>int luaL_ref (lua_State *L, int t);</pre> 5474 5475<p> 5476Creates and returns a <em>reference</em>, 5477in the table at index <code>t</code>, 5478for the object at the top of the stack (and pops the object). 5479 5480 5481<p> 5482A reference is a unique integer key. 5483As long as you do not manually add integer keys into table <code>t</code>, 5484<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 5485You can retrieve an object referred by reference <code>r</code> 5486by calling <code>lua_rawgeti(L, t, r)</code>. 5487Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 5488 5489 5490<p> 5491If the object at the top of the stack is <b>nil</b>, 5492<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 5493The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 5494from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 5495 5496 5497 5498 5499 5500<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 5501<pre>typedef struct luaL_Reg { 5502 const char *name; 5503 lua_CFunction func; 5504} luaL_Reg;</pre> 5505 5506<p> 5507Type for arrays of functions to be registered by 5508<a href="#luaL_register"><code>luaL_register</code></a>. 5509<code>name</code> is the function name and <code>func</code> is a pointer to 5510the function. 5511Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry 5512in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 5513 5514 5515 5516 5517 5518<hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p> 5519<span class="apii">[-(0|1), +1, <em>m</em>]</span> 5520<pre>void luaL_register (lua_State *L, 5521 const char *libname, 5522 const luaL_Reg *l);</pre> 5523 5524<p> 5525Opens a library. 5526 5527 5528<p> 5529When called with <code>libname</code> equal to <code>NULL</code>, 5530it simply registers all functions in the list <code>l</code> 5531(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack. 5532 5533 5534<p> 5535When called with a non-null <code>libname</code>, 5536<code>luaL_register</code> creates a new table <code>t</code>, 5537sets it as the value of the global variable <code>libname</code>, 5538sets it as the value of <code>package.loaded[libname]</code>, 5539and registers on it all functions in the list <code>l</code>. 5540If there is a table in <code>package.loaded[libname]</code> or in 5541variable <code>libname</code>, 5542reuses this table instead of creating a new one. 5543 5544 5545<p> 5546In any case the function leaves the table 5547on the top of the stack. 5548 5549 5550 5551 5552 5553<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 5554<span class="apii">[-0, +0, <em>-</em>]</span> 5555<pre>const char *luaL_typename (lua_State *L, int index);</pre> 5556 5557<p> 5558Returns the name of the type of the value at the given index. 5559 5560 5561 5562 5563 5564<hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p> 5565<span class="apii">[-0, +0, <em>v</em>]</span> 5566<pre>int luaL_typerror (lua_State *L, int narg, const char *tname);</pre> 5567 5568<p> 5569Generates an error with a message like the following: 5570 5571<pre> 5572 <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>) 5573</pre><p> 5574where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>, 5575<code><em>func</em></code> is the name of the current function, 5576and <code><em>rt</em></code> is the type name of the actual argument. 5577 5578 5579 5580 5581 5582<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 5583<span class="apii">[-0, +0, <em>-</em>]</span> 5584<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 5585 5586<p> 5587Releases reference <code>ref</code> from the table at index <code>t</code> 5588(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 5589The entry is removed from the table, 5590so that the referred object can be collected. 5591The reference <code>ref</code> is also freed to be used again. 5592 5593 5594<p> 5595If <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>, 5596<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 5597 5598 5599 5600 5601 5602<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 5603<span class="apii">[-0, +1, <em>m</em>]</span> 5604<pre>void luaL_where (lua_State *L, int lvl);</pre> 5605 5606<p> 5607Pushes onto the stack a string identifying the current position 5608of the control at level <code>lvl</code> in the call stack. 5609Typically this string has the following format: 5610 5611<pre> 5612 <em>chunkname</em>:<em>currentline</em>: 5613</pre><p> 5614Level 0 is the running function, 5615level 1 is the function that called the running function, 5616etc. 5617 5618 5619<p> 5620This function is used to build a prefix for error messages. 5621 5622 5623 5624 5625 5626 5627 5628<h1>5 - <a name="5">Standard Libraries</a></h1> 5629 5630<p> 5631The standard Lua libraries provide useful functions 5632that are implemented directly through the C API. 5633Some of these functions provide essential services to the language 5634(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 5635others provide access to "outside" services (e.g., I/O); 5636and others could be implemented in Lua itself, 5637but are quite useful or have critical performance requirements that 5638deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 5639 5640 5641<p> 5642All libraries are implemented through the official C API 5643and are provided as separate C modules. 5644Currently, Lua has the following standard libraries: 5645 5646<ul> 5647 5648<li>basic library,</li> which includes the coroutine sub-library; 5649 5650<li>package library;</li> 5651 5652<li>string manipulation;</li> 5653 5654<li>table manipulation;</li> 5655 5656<li>mathematical functions (sin, log, etc.);</li> 5657 5658<li>input and output;</li> 5659 5660<li>operating system facilities;</li> 5661 5662<li>debug facilities.</li> 5663 5664</ul><p> 5665Except for the basic and package libraries, 5666each library provides all its functions as fields of a global table 5667or as methods of its objects. 5668 5669 5670<p> 5671To have access to these libraries, 5672the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 5673which opens all standard libraries. 5674Alternatively, 5675it can open them individually by calling 5676<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 5677<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 5678<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 5679<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 5680<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 5681<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 5682<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), 5683and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 5684These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a> 5685and should not be called directly: 5686you must call them like any other Lua C function, 5687e.g., by using <a href="#lua_call"><code>lua_call</code></a>. 5688 5689 5690 5691<h2>5.1 - <a name="5.1">Basic Functions</a></h2> 5692 5693<p> 5694The basic library provides some core functions to Lua. 5695If you do not include this library in your application, 5696you should check carefully whether you need to provide 5697implementations for some of its facilities. 5698 5699 5700<p> 5701<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 5702Issues an error when 5703the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 5704otherwise, returns all its arguments. 5705<code>message</code> is an error message; 5706when absent, it defaults to "assertion failed!" 5707 5708 5709 5710 5711<p> 5712<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage (opt [, arg])</code></a></h3> 5713 5714 5715<p> 5716This function is a generic interface to the garbage collector. 5717It performs different functions according to its first argument, <code>opt</code>: 5718 5719<ul> 5720 5721<li><b>"stop":</b> 5722stops the garbage collector. 5723</li> 5724 5725<li><b>"restart":</b> 5726restarts the garbage collector. 5727</li> 5728 5729<li><b>"collect":</b> 5730performs a full garbage-collection cycle. 5731</li> 5732 5733<li><b>"count":</b> 5734returns the total memory in use by Lua (in Kbytes). 5735</li> 5736 5737<li><b>"step":</b> 5738performs a garbage-collection step. 5739The step "size" is controlled by <code>arg</code> 5740(larger values mean more steps) in a non-specified way. 5741If you want to control the step size 5742you must experimentally tune the value of <code>arg</code>. 5743Returns <b>true</b> if the step finished a collection cycle. 5744</li> 5745 5746<li><b>"setpause":</b> 5747sets <code>arg</code> as the new value for the <em>pause</em> of 5748the collector (see <a href="#2.10">§2.10</a>). 5749Returns the previous value for <em>pause</em>. 5750</li> 5751 5752<li><b>"setstepmul":</b> 5753sets <code>arg</code> as the new value for the <em>step multiplier</em> of 5754the collector (see <a href="#2.10">§2.10</a>). 5755Returns the previous value for <em>step</em>. 5756</li> 5757 5758</ul> 5759 5760 5761 5762<p> 5763<hr><h3><a name="pdf-dofile"><code>dofile (filename)</code></a></h3> 5764Opens the named file and executes its contents as a Lua chunk. 5765When called without arguments, 5766<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 5767Returns all values returned by the chunk. 5768In case of errors, <code>dofile</code> propagates the error 5769to its caller (that is, <code>dofile</code> does not run in protected mode). 5770 5771 5772 5773 5774<p> 5775<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 5776Terminates the last protected function called 5777and returns <code>message</code> as the error message. 5778Function <code>error</code> never returns. 5779 5780 5781<p> 5782Usually, <code>error</code> adds some information about the error position 5783at the beginning of the message. 5784The <code>level</code> argument specifies how to get the error position. 5785With level 1 (the default), the error position is where the 5786<code>error</code> function was called. 5787Level 2 points the error to where the function 5788that called <code>error</code> was called; and so on. 5789Passing a level 0 avoids the addition of error position information 5790to the message. 5791 5792 5793 5794 5795<p> 5796<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 5797A global variable (not a function) that 5798holds the global environment (that is, <code>_G._G = _G</code>). 5799Lua itself does not use this variable; 5800changing its value does not affect any environment, 5801nor vice-versa. 5802(Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) 5803 5804 5805 5806 5807<p> 5808<hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3> 5809Returns the current environment in use by the function. 5810<code>f</code> can be a Lua function or a number 5811that specifies the function at that stack level: 5812Level 1 is the function calling <code>getfenv</code>. 5813If the given function is not a Lua function, 5814or if <code>f</code> is 0, 5815<code>getfenv</code> returns the global environment. 5816The default for <code>f</code> is 1. 5817 5818 5819 5820 5821<p> 5822<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 5823 5824 5825<p> 5826If <code>object</code> does not have a metatable, returns <b>nil</b>. 5827Otherwise, 5828if the object's metatable has a <code>"__metatable"</code> field, 5829returns the associated value. 5830Otherwise, returns the metatable of the given object. 5831 5832 5833 5834 5835<p> 5836<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 5837 5838 5839<p> 5840Returns three values: an iterator function, the table <code>t</code>, and 0, 5841so that the construction 5842 5843<pre> 5844 for i,v in ipairs(t) do <em>body</em> end 5845</pre><p> 5846will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···, 5847up to the first integer key absent from the table. 5848 5849 5850 5851 5852<p> 5853<hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3> 5854 5855 5856<p> 5857Loads a chunk using function <code>func</code> to get its pieces. 5858Each call to <code>func</code> must return a string that concatenates 5859with previous results. 5860A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 5861 5862 5863<p> 5864If there are no errors, 5865returns the compiled chunk as a function; 5866otherwise, returns <b>nil</b> plus the error message. 5867The environment of the returned function is the global environment. 5868 5869 5870<p> 5871<code>chunkname</code> is used as the chunk name for error messages 5872and debug information. 5873When absent, 5874it defaults to "<code>=(load)</code>". 5875 5876 5877 5878 5879<p> 5880<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3> 5881 5882 5883<p> 5884Similar to <a href="#pdf-load"><code>load</code></a>, 5885but gets the chunk from file <code>filename</code> 5886or from the standard input, 5887if no file name is given. 5888 5889 5890 5891 5892<p> 5893<hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3> 5894 5895 5896<p> 5897Similar to <a href="#pdf-load"><code>load</code></a>, 5898but gets the chunk from the given string. 5899 5900 5901<p> 5902To load and run a given string, use the idiom 5903 5904<pre> 5905 assert(loadstring(s))() 5906</pre> 5907 5908<p> 5909When absent, 5910<code>chunkname</code> defaults to the given string. 5911 5912 5913 5914 5915<p> 5916<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 5917 5918 5919<p> 5920Allows a program to traverse all fields of a table. 5921Its first argument is a table and its second argument 5922is an index in this table. 5923<code>next</code> returns the next index of the table 5924and its associated value. 5925When called with <b>nil</b> as its second argument, 5926<code>next</code> returns an initial index 5927and its associated value. 5928When called with the last index, 5929or with <b>nil</b> in an empty table, 5930<code>next</code> returns <b>nil</b>. 5931If the second argument is absent, then it is interpreted as <b>nil</b>. 5932In particular, 5933you can use <code>next(t)</code> to check whether a table is empty. 5934 5935 5936<p> 5937The order in which the indices are enumerated is not specified, 5938<em>even for numeric indices</em>. 5939(To traverse a table in numeric order, 5940use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) 5941 5942 5943<p> 5944The behavior of <code>next</code> is <em>undefined</em> if, 5945during the traversal, 5946you assign any value to a non-existent field in the table. 5947You may however modify existing fields. 5948In particular, you may clear existing fields. 5949 5950 5951 5952 5953<p> 5954<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 5955 5956 5957<p> 5958Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 5959so that the construction 5960 5961<pre> 5962 for k,v in pairs(t) do <em>body</em> end 5963</pre><p> 5964will iterate over all key–value pairs of table <code>t</code>. 5965 5966 5967<p> 5968See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 5969the table during its traversal. 5970 5971 5972 5973 5974<p> 5975<hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3> 5976 5977 5978<p> 5979Calls function <code>f</code> with 5980the given arguments in <em>protected mode</em>. 5981This means that any error inside <code>f</code> is not propagated; 5982instead, <code>pcall</code> catches the error 5983and returns a status code. 5984Its first result is the status code (a boolean), 5985which is true if the call succeeds without errors. 5986In such case, <code>pcall</code> also returns all results from the call, 5987after this first result. 5988In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 5989 5990 5991 5992 5993<p> 5994<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 5995Receives any number of arguments, 5996and prints their values to <code>stdout</code>, 5997using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. 5998<code>print</code> is not intended for formatted output, 5999but only as a quick way to show a value, 6000typically for debugging. 6001For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. 6002 6003 6004 6005 6006<p> 6007<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 6008Checks whether <code>v1</code> is equal to <code>v2</code>, 6009without invoking any metamethod. 6010Returns a boolean. 6011 6012 6013 6014 6015<p> 6016<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 6017Gets the real value of <code>table[index]</code>, 6018without invoking any metamethod. 6019<code>table</code> must be a table; 6020<code>index</code> may be any value. 6021 6022 6023 6024 6025<p> 6026<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 6027Sets the real value of <code>table[index]</code> to <code>value</code>, 6028without invoking any metamethod. 6029<code>table</code> must be a table, 6030<code>index</code> any value different from <b>nil</b>, 6031and <code>value</code> any Lua value. 6032 6033 6034<p> 6035This function returns <code>table</code>. 6036 6037 6038 6039 6040<p> 6041<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 6042 6043 6044<p> 6045If <code>index</code> is a number, 6046returns all arguments after argument number <code>index</code>. 6047Otherwise, <code>index</code> must be the string <code>"#"</code>, 6048and <code>select</code> returns the total number of extra arguments it received. 6049 6050 6051 6052 6053<p> 6054<hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3> 6055 6056 6057<p> 6058Sets the environment to be used by the given function. 6059<code>f</code> can be a Lua function or a number 6060that specifies the function at that stack level: 6061Level 1 is the function calling <code>setfenv</code>. 6062<code>setfenv</code> returns the given function. 6063 6064 6065<p> 6066As a special case, when <code>f</code> is 0 <code>setfenv</code> changes 6067the environment of the running thread. 6068In this case, <code>setfenv</code> returns no values. 6069 6070 6071 6072 6073<p> 6074<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 6075 6076 6077<p> 6078Sets the metatable for the given table. 6079(You cannot change the metatable of other types from Lua, only from C.) 6080If <code>metatable</code> is <b>nil</b>, 6081removes the metatable of the given table. 6082If the original metatable has a <code>"__metatable"</code> field, 6083raises an error. 6084 6085 6086<p> 6087This function returns <code>table</code>. 6088 6089 6090 6091 6092<p> 6093<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 6094Tries to convert its argument to a number. 6095If the argument is already a number or a string convertible 6096to a number, then <code>tonumber</code> returns this number; 6097otherwise, it returns <b>nil</b>. 6098 6099 6100<p> 6101An optional argument specifies the base to interpret the numeral. 6102The base may be any integer between 2 and 36, inclusive. 6103In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 6104represents 10, '<code>B</code>' represents 11, and so forth, 6105with '<code>Z</code>' representing 35. 6106In base 10 (the default), the number can have a decimal part, 6107as well as an optional exponent part (see <a href="#2.1">§2.1</a>). 6108In other bases, only unsigned integers are accepted. 6109 6110 6111 6112 6113<p> 6114<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3> 6115Receives an argument of any type and 6116converts it to a string in a reasonable format. 6117For complete control of how numbers are converted, 6118use <a href="#pdf-string.format"><code>string.format</code></a>. 6119 6120 6121<p> 6122If the metatable of <code>e</code> has a <code>"__tostring"</code> field, 6123then <code>tostring</code> calls the corresponding value 6124with <code>e</code> as argument, 6125and uses the result of the call as its result. 6126 6127 6128 6129 6130<p> 6131<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 6132Returns the type of its only argument, coded as a string. 6133The possible results of this function are 6134"<code>nil</code>" (a string, not the value <b>nil</b>), 6135"<code>number</code>", 6136"<code>string</code>", 6137"<code>boolean</code>", 6138"<code>table</code>", 6139"<code>function</code>", 6140"<code>thread</code>", 6141and "<code>userdata</code>". 6142 6143 6144 6145 6146<p> 6147<hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3> 6148Returns the elements from the given table. 6149This function is equivalent to 6150 6151<pre> 6152 return list[i], list[i+1], ···, list[j] 6153</pre><p> 6154except that the above code can be written only for a fixed number 6155of elements. 6156By default, <code>i</code> is 1 and <code>j</code> is the length of the list, 6157as defined by the length operator (see <a href="#2.5.5">§2.5.5</a>). 6158 6159 6160 6161 6162<p> 6163<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 6164A global variable (not a function) that 6165holds a string containing the current interpreter version. 6166The current contents of this variable is "<code>Lua 5.1</code>". 6167 6168 6169 6170 6171<p> 6172<hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3> 6173 6174 6175<p> 6176This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 6177except that you can set a new error handler. 6178 6179 6180<p> 6181<code>xpcall</code> calls function <code>f</code> in protected mode, 6182using <code>err</code> as the error handler. 6183Any error inside <code>f</code> is not propagated; 6184instead, <code>xpcall</code> catches the error, 6185calls the <code>err</code> function with the original error object, 6186and returns a status code. 6187Its first result is the status code (a boolean), 6188which is true if the call succeeds without errors. 6189In this case, <code>xpcall</code> also returns all results from the call, 6190after this first result. 6191In case of any error, 6192<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. 6193 6194 6195 6196 6197 6198 6199 6200<h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2> 6201 6202<p> 6203The operations related to coroutines comprise a sub-library of 6204the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 6205See <a href="#2.11">§2.11</a> for a general description of coroutines. 6206 6207 6208<p> 6209<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 6210 6211 6212<p> 6213Creates a new coroutine, with body <code>f</code>. 6214<code>f</code> must be a Lua function. 6215Returns this new coroutine, 6216an object with type <code>"thread"</code>. 6217 6218 6219 6220 6221<p> 6222<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 6223 6224 6225<p> 6226Starts or continues the execution of coroutine <code>co</code>. 6227The first time you resume a coroutine, 6228it starts running its body. 6229The values <code>val1</code>, ··· are passed 6230as the arguments to the body function. 6231If the coroutine has yielded, 6232<code>resume</code> restarts it; 6233the values <code>val1</code>, ··· are passed 6234as the results from the yield. 6235 6236 6237<p> 6238If the coroutine runs without any errors, 6239<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 6240(if the coroutine yields) or any values returned by the body function 6241(if the coroutine terminates). 6242If there is any error, 6243<code>resume</code> returns <b>false</b> plus the error message. 6244 6245 6246 6247 6248<p> 6249<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 6250 6251 6252<p> 6253Returns the running coroutine, 6254or <b>nil</b> when called by the main thread. 6255 6256 6257 6258 6259<p> 6260<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 6261 6262 6263<p> 6264Returns the status of coroutine <code>co</code>, as a string: 6265<code>"running"</code>, 6266if the coroutine is running (that is, it called <code>status</code>); 6267<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 6268or if it has not started running yet; 6269<code>"normal"</code> if the coroutine is active but not running 6270(that is, it has resumed another coroutine); 6271and <code>"dead"</code> if the coroutine has finished its body function, 6272or if it has stopped with an error. 6273 6274 6275 6276 6277<p> 6278<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 6279 6280 6281<p> 6282Creates a new coroutine, with body <code>f</code>. 6283<code>f</code> must be a Lua function. 6284Returns a function that resumes the coroutine each time it is called. 6285Any arguments passed to the function behave as the 6286extra arguments to <code>resume</code>. 6287Returns the same values returned by <code>resume</code>, 6288except the first boolean. 6289In case of error, propagates the error. 6290 6291 6292 6293 6294<p> 6295<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 6296 6297 6298<p> 6299Suspends the execution of the calling coroutine. 6300The coroutine cannot be running a C function, 6301a metamethod, or an iterator. 6302Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 6303 6304 6305 6306 6307 6308 6309 6310<h2>5.3 - <a name="5.3">Modules</a></h2> 6311 6312<p> 6313The package library provides basic 6314facilities for loading and building modules in Lua. 6315It exports two of its functions directly in the global environment: 6316<a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. 6317Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. 6318 6319 6320<p> 6321<hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3> 6322 6323 6324<p> 6325Creates a module. 6326If there is a table in <code>package.loaded[name]</code>, 6327this table is the module. 6328Otherwise, if there is a global table <code>t</code> with the given name, 6329this table is the module. 6330Otherwise creates a new table <code>t</code> and 6331sets it as the value of the global <code>name</code> and 6332the value of <code>package.loaded[name]</code>. 6333This function also initializes <code>t._NAME</code> with the given name, 6334<code>t._M</code> with the module (<code>t</code> itself), 6335and <code>t._PACKAGE</code> with the package name 6336(the full module name minus last component; see below). 6337Finally, <code>module</code> sets <code>t</code> as the new environment 6338of the current function and the new value of <code>package.loaded[name]</code>, 6339so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. 6340 6341 6342<p> 6343If <code>name</code> is a compound name 6344(that is, one with components separated by dots), 6345<code>module</code> creates (or reuses, if they already exist) 6346tables for each component. 6347For instance, if <code>name</code> is <code>a.b.c</code>, 6348then <code>module</code> stores the module table in field <code>c</code> of 6349field <code>b</code> of global <code>a</code>. 6350 6351 6352<p> 6353This function can receive optional <em>options</em> after 6354the module name, 6355where each option is a function to be applied over the module. 6356 6357 6358 6359 6360<p> 6361<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 6362 6363 6364<p> 6365Loads the given module. 6366The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 6367to determine whether <code>modname</code> is already loaded. 6368If it is, then <code>require</code> returns the value stored 6369at <code>package.loaded[modname]</code>. 6370Otherwise, it tries to find a <em>loader</em> for the module. 6371 6372 6373<p> 6374To find a loader, 6375<code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array. 6376By changing this array, 6377we can change how <code>require</code> looks for a module. 6378The following explanation is based on the default configuration 6379for <a href="#pdf-package.loaders"><code>package.loaders</code></a>. 6380 6381 6382<p> 6383First <code>require</code> queries <code>package.preload[modname]</code>. 6384If it has a value, 6385this value (which should be a function) is the loader. 6386Otherwise <code>require</code> searches for a Lua loader using the 6387path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 6388If that also fails, it searches for a C loader using the 6389path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 6390If that also fails, 6391it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>). 6392 6393 6394<p> 6395Once a loader is found, 6396<code>require</code> calls the loader with a single argument, <code>modname</code>. 6397If the loader returns any value, 6398<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 6399If the loader returns no value and 6400has not assigned any value to <code>package.loaded[modname]</code>, 6401then <code>require</code> assigns <b>true</b> to this entry. 6402In any case, <code>require</code> returns the 6403final value of <code>package.loaded[modname]</code>. 6404 6405 6406<p> 6407If there is any error loading or running the module, 6408or if it cannot find any loader for the module, 6409then <code>require</code> signals an error. 6410 6411 6412 6413 6414<p> 6415<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 6416 6417 6418<p> 6419The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 6420 6421 6422<p> 6423Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 6424it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 6425using the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 6426or a default path defined in <code>luaconf.h</code>. 6427 6428 6429 6430 6431<p> 6432 6433<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 6434 6435 6436<p> 6437A table used by <a href="#pdf-require"><code>require</code></a> to control which 6438modules are already loaded. 6439When you require a module <code>modname</code> and 6440<code>package.loaded[modname]</code> is not false, 6441<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 6442 6443 6444 6445 6446<p> 6447<hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3> 6448 6449 6450<p> 6451A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 6452 6453 6454<p> 6455Each entry in this table is a <em>searcher function</em>. 6456When looking for a module, 6457<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 6458with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 6459sole parameter. 6460The function can return another function (the module <em>loader</em>) 6461or a string explaining why it did not find that module 6462(or <b>nil</b> if it has nothing to say). 6463Lua initializes this table with four functions. 6464 6465 6466<p> 6467The first searcher simply looks for a loader in the 6468<a href="#pdf-package.preload"><code>package.preload</code></a> table. 6469 6470 6471<p> 6472The second searcher looks for a loader as a Lua library, 6473using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 6474A path is a sequence of <em>templates</em> separated by semicolons. 6475For each template, 6476the searcher will change each interrogation 6477mark in the template by <code>filename</code>, 6478which is the module name with each dot replaced by a 6479"directory separator" (such as "<code>/</code>" in Unix); 6480then it will try to open the resulting file name. 6481So, for instance, if the Lua path is the string 6482 6483<pre> 6484 "./?.lua;./?.lc;/usr/local/?/init.lua" 6485</pre><p> 6486the search for a Lua file for module <code>foo</code> 6487will try to open the files 6488<code>./foo.lua</code>, <code>./foo.lc</code>, and 6489<code>/usr/local/foo/init.lua</code>, in that order. 6490 6491 6492<p> 6493The third searcher looks for a loader as a C library, 6494using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 6495For instance, 6496if the C path is the string 6497 6498<pre> 6499 "./?.so;./?.dll;/usr/local/?/init.so" 6500</pre><p> 6501the searcher for module <code>foo</code> 6502will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 6503and <code>/usr/local/foo/init.so</code>, in that order. 6504Once it finds a C library, 6505this searcher first uses a dynamic link facility to link the 6506application with the library. 6507Then it tries to find a C function inside the library to 6508be used as the loader. 6509The name of this C function is the string "<code>luaopen_</code>" 6510concatenated with a copy of the module name where each dot 6511is replaced by an underscore. 6512Moreover, if the module name has a hyphen, 6513its prefix up to (and including) the first hyphen is removed. 6514For instance, if the module name is <code>a.v1-b.c</code>, 6515the function name will be <code>luaopen_b_c</code>. 6516 6517 6518<p> 6519The fourth searcher tries an <em>all-in-one loader</em>. 6520It searches the C path for a library for 6521the root name of the given module. 6522For instance, when requiring <code>a.b.c</code>, 6523it will search for a C library for <code>a</code>. 6524If found, it looks into it for an open function for 6525the submodule; 6526in our example, that would be <code>luaopen_a_b_c</code>. 6527With this facility, a package can pack several C submodules 6528into one single library, 6529with each submodule keeping its original open function. 6530 6531 6532 6533 6534<p> 6535<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 6536 6537 6538<p> 6539Dynamically links the host program with the C library <code>libname</code>. 6540Inside this library, looks for a function <code>funcname</code> 6541and returns this function as a C function. 6542(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). 6543 6544 6545<p> 6546This is a low-level function. 6547It completely bypasses the package and module system. 6548Unlike <a href="#pdf-require"><code>require</code></a>, 6549it does not perform any path searching and 6550does not automatically adds extensions. 6551<code>libname</code> must be the complete file name of the C library, 6552including if necessary a path and extension. 6553<code>funcname</code> must be the exact name exported by the C library 6554(which may depend on the C compiler and linker used). 6555 6556 6557<p> 6558This function is not supported by ANSI C. 6559As such, it is only available on some platforms 6560(Windows, Linux, Mac OS X, Solaris, BSD, 6561plus other Unix systems that support the <code>dlfcn</code> standard). 6562 6563 6564 6565 6566<p> 6567<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 6568 6569 6570<p> 6571The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 6572 6573 6574<p> 6575At start-up, Lua initializes this variable with 6576the value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 6577with a default path defined in <code>luaconf.h</code>, 6578if the environment variable is not defined. 6579Any "<code>;;</code>" in the value of the environment variable 6580is replaced by the default path. 6581 6582 6583 6584 6585<p> 6586<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 6587 6588 6589<p> 6590A table to store loaders for specific modules 6591(see <a href="#pdf-require"><code>require</code></a>). 6592 6593 6594 6595 6596<p> 6597<hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3> 6598 6599 6600<p> 6601Sets a metatable for <code>module</code> with 6602its <code>__index</code> field referring to the global environment, 6603so that this module inherits values 6604from the global environment. 6605To be used as an option to function <a href="#pdf-module"><code>module</code></a>. 6606 6607 6608 6609 6610 6611 6612 6613<h2>5.4 - <a name="5.4">String Manipulation</a></h2> 6614 6615<p> 6616This library provides generic functions for string manipulation, 6617such as finding and extracting substrings, and pattern matching. 6618When indexing a string in Lua, the first character is at position 1 6619(not at 0, as in C). 6620Indices are allowed to be negative and are interpreted as indexing backwards, 6621from the end of the string. 6622Thus, the last character is at position -1, and so on. 6623 6624 6625<p> 6626The string library provides all its functions inside the table 6627<a name="pdf-string"><code>string</code></a>. 6628It also sets a metatable for strings 6629where the <code>__index</code> field points to the <code>string</code> table. 6630Therefore, you can use the string functions in object-oriented style. 6631For instance, <code>string.byte(s, i)</code> 6632can be written as <code>s:byte(i)</code>. 6633 6634 6635<p> 6636The string library assumes one-byte character encodings. 6637 6638 6639<p> 6640<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 6641Returns the internal numerical codes of the characters <code>s[i]</code>, 6642<code>s[i+1]</code>, ···, <code>s[j]</code>. 6643The default value for <code>i</code> is 1; 6644the default value for <code>j</code> is <code>i</code>. 6645 6646 6647<p> 6648Note that numerical codes are not necessarily portable across platforms. 6649 6650 6651 6652 6653<p> 6654<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 6655Receives zero or more integers. 6656Returns a string with length equal to the number of arguments, 6657in which each character has the internal numerical code equal 6658to its corresponding argument. 6659 6660 6661<p> 6662Note that numerical codes are not necessarily portable across platforms. 6663 6664 6665 6666 6667<p> 6668<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3> 6669 6670 6671<p> 6672Returns a string containing a binary representation of the given function, 6673so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns 6674a copy of the function. 6675<code>function</code> must be a Lua function without upvalues. 6676 6677 6678 6679 6680<p> 6681<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 6682Looks for the first match of 6683<code>pattern</code> in the string <code>s</code>. 6684If it finds a match, then <code>find</code> returns the indices of <code>s</code> 6685where this occurrence starts and ends; 6686otherwise, it returns <b>nil</b>. 6687A third, optional numerical argument <code>init</code> specifies 6688where to start the search; 6689its default value is 1 and can be negative. 6690A value of <b>true</b> as a fourth, optional argument <code>plain</code> 6691turns off the pattern matching facilities, 6692so the function does a plain "find substring" operation, 6693with no characters in <code>pattern</code> being considered "magic". 6694Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 6695 6696 6697<p> 6698If the pattern has captures, 6699then in a successful match 6700the captured values are also returned, 6701after the two indices. 6702 6703 6704 6705 6706<p> 6707<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 6708Returns a formatted version of its variable number of arguments 6709following the description given in its first argument (which must be a string). 6710The format string follows the same rules as the <code>printf</code> family of 6711standard C functions. 6712The only differences are that the options/modifiers 6713<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, 6714and <code>h</code> are not supported 6715and that there is an extra option, <code>q</code>. 6716The <code>q</code> option formats a string in a form suitable to be safely read 6717back by the Lua interpreter: 6718the string is written between double quotes, 6719and all double quotes, newlines, embedded zeros, 6720and backslashes in the string 6721are correctly escaped when written. 6722For instance, the call 6723 6724<pre> 6725 string.format('%q', 'a string with "quotes" and \n new line') 6726</pre><p> 6727will produce the string: 6728 6729<pre> 6730 "a string with \"quotes\" and \ 6731 new line" 6732</pre> 6733 6734<p> 6735The options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>, 6736<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all 6737expect a number as argument, 6738whereas <code>q</code> and <code>s</code> expect a string. 6739 6740 6741<p> 6742This function does not accept string values 6743containing embedded zeros, 6744except as arguments to the <code>q</code> option. 6745 6746 6747 6748 6749<p> 6750<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 6751Returns an iterator function that, 6752each time it is called, 6753returns the next captures from <code>pattern</code> over string <code>s</code>. 6754If <code>pattern</code> specifies no captures, 6755then the whole match is produced in each call. 6756 6757 6758<p> 6759As an example, the following loop 6760 6761<pre> 6762 s = "hello world from Lua" 6763 for w in string.gmatch(s, "%a+") do 6764 print(w) 6765 end 6766</pre><p> 6767will iterate over all the words from string <code>s</code>, 6768printing one per line. 6769The next example collects all pairs <code>key=value</code> from the 6770given string into a table: 6771 6772<pre> 6773 t = {} 6774 s = "from=world, to=Lua" 6775 for k, v in string.gmatch(s, "(%w+)=(%w+)") do 6776 t[k] = v 6777 end 6778</pre> 6779 6780<p> 6781For this function, a '<code>^</code>' at the start of a pattern does not 6782work as an anchor, as this would prevent the iteration. 6783 6784 6785 6786 6787<p> 6788<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 6789Returns a copy of <code>s</code> 6790in which all (or the first <code>n</code>, if given) 6791occurrences of the <code>pattern</code> have been 6792replaced by a replacement string specified by <code>repl</code>, 6793which can be a string, a table, or a function. 6794<code>gsub</code> also returns, as its second value, 6795the total number of matches that occurred. 6796 6797 6798<p> 6799If <code>repl</code> is a string, then its value is used for replacement. 6800The character <code>%</code> works as an escape character: 6801any sequence in <code>repl</code> of the form <code>%<em>n</em></code>, 6802with <em>n</em> between 1 and 9, 6803stands for the value of the <em>n</em>-th captured substring (see below). 6804The sequence <code>%0</code> stands for the whole match. 6805The sequence <code>%%</code> stands for a single <code>%</code>. 6806 6807 6808<p> 6809If <code>repl</code> is a table, then the table is queried for every match, 6810using the first capture as the key; 6811if the pattern specifies no captures, 6812then the whole match is used as the key. 6813 6814 6815<p> 6816If <code>repl</code> is a function, then this function is called every time a 6817match occurs, with all captured substrings passed as arguments, 6818in order; 6819if the pattern specifies no captures, 6820then the whole match is passed as a sole argument. 6821 6822 6823<p> 6824If the value returned by the table query or by the function call 6825is a string or a number, 6826then it is used as the replacement string; 6827otherwise, if it is <b>false</b> or <b>nil</b>, 6828then there is no replacement 6829(that is, the original match is kept in the string). 6830 6831 6832<p> 6833Here are some examples: 6834 6835<pre> 6836 x = string.gsub("hello world", "(%w+)", "%1 %1") 6837 --> x="hello hello world world" 6838 6839 x = string.gsub("hello world", "%w+", "%0 %0", 1) 6840 --> x="hello hello world" 6841 6842 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 6843 --> x="world hello Lua from" 6844 6845 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 6846 --> x="home = /home/roberto, user = roberto" 6847 6848 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 6849 return loadstring(s)() 6850 end) 6851 --> x="4+5 = 9" 6852 6853 local t = {name="lua", version="5.1"} 6854 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 6855 --> x="lua-5.1.tar.gz" 6856</pre> 6857 6858 6859 6860<p> 6861<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 6862Receives a string and returns its length. 6863The empty string <code>""</code> has length 0. 6864Embedded zeros are counted, 6865so <code>"a\000bc\000"</code> has length 5. 6866 6867 6868 6869 6870<p> 6871<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 6872Receives a string and returns a copy of this string with all 6873uppercase letters changed to lowercase. 6874All other characters are left unchanged. 6875The definition of what an uppercase letter is depends on the current locale. 6876 6877 6878 6879 6880<p> 6881<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 6882Looks for the first <em>match</em> of 6883<code>pattern</code> in the string <code>s</code>. 6884If it finds one, then <code>match</code> returns 6885the captures from the pattern; 6886otherwise it returns <b>nil</b>. 6887If <code>pattern</code> specifies no captures, 6888then the whole match is returned. 6889A third, optional numerical argument <code>init</code> specifies 6890where to start the search; 6891its default value is 1 and can be negative. 6892 6893 6894 6895 6896<p> 6897<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3> 6898Returns a string that is the concatenation of <code>n</code> copies of 6899the string <code>s</code>. 6900 6901 6902 6903 6904<p> 6905<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 6906Returns a string that is the string <code>s</code> reversed. 6907 6908 6909 6910 6911<p> 6912<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 6913Returns the substring of <code>s</code> that 6914starts at <code>i</code> and continues until <code>j</code>; 6915<code>i</code> and <code>j</code> can be negative. 6916If <code>j</code> is absent, then it is assumed to be equal to -1 6917(which is the same as the string length). 6918In particular, 6919the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 6920with length <code>j</code>, 6921and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 6922with length <code>i</code>. 6923 6924 6925 6926 6927<p> 6928<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 6929Receives a string and returns a copy of this string with all 6930lowercase letters changed to uppercase. 6931All other characters are left unchanged. 6932The definition of what a lowercase letter is depends on the current locale. 6933 6934 6935 6936<h3>5.4.1 - <a name="5.4.1">Patterns</a></h3> 6937 6938 6939<h4>Character Class:</h4><p> 6940A <em>character class</em> is used to represent a set of characters. 6941The following combinations are allowed in describing a character class: 6942 6943<ul> 6944 6945<li><b><em>x</em>:</b> 6946(where <em>x</em> is not one of the <em>magic characters</em> 6947<code>^$()%.[]*+-?</code>) 6948represents the character <em>x</em> itself. 6949</li> 6950 6951<li><b><code>.</code>:</b> (a dot) represents all characters.</li> 6952 6953<li><b><code>%a</code>:</b> represents all letters.</li> 6954 6955<li><b><code>%c</code>:</b> represents all control characters.</li> 6956 6957<li><b><code>%d</code>:</b> represents all digits.</li> 6958 6959<li><b><code>%l</code>:</b> represents all lowercase letters.</li> 6960 6961<li><b><code>%p</code>:</b> represents all punctuation characters.</li> 6962 6963<li><b><code>%s</code>:</b> represents all space characters.</li> 6964 6965<li><b><code>%u</code>:</b> represents all uppercase letters.</li> 6966 6967<li><b><code>%w</code>:</b> represents all alphanumeric characters.</li> 6968 6969<li><b><code>%x</code>:</b> represents all hexadecimal digits.</li> 6970 6971<li><b><code>%z</code>:</b> represents the character with representation 0.</li> 6972 6973<li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character) 6974represents the character <em>x</em>. 6975This is the standard way to escape the magic characters. 6976Any punctuation character (even the non magic) 6977can be preceded by a '<code>%</code>' 6978when used to represent itself in a pattern. 6979</li> 6980 6981<li><b><code>[<em>set</em>]</code>:</b> 6982represents the class which is the union of all 6983characters in <em>set</em>. 6984A range of characters can be specified by 6985separating the end characters of the range with a '<code>-</code>'. 6986All classes <code>%</code><em>x</em> described above can also be used as 6987components in <em>set</em>. 6988All other characters in <em>set</em> represent themselves. 6989For example, <code>[%w_]</code> (or <code>[_%w]</code>) 6990represents all alphanumeric characters plus the underscore, 6991<code>[0-7]</code> represents the octal digits, 6992and <code>[0-7%l%-]</code> represents the octal digits plus 6993the lowercase letters plus the '<code>-</code>' character. 6994 6995 6996<p> 6997The interaction between ranges and classes is not defined. 6998Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 6999have no meaning. 7000</li> 7001 7002<li><b><code>[^<em>set</em>]</code>:</b> 7003represents the complement of <em>set</em>, 7004where <em>set</em> is interpreted as above. 7005</li> 7006 7007</ul><p> 7008For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 7009the corresponding uppercase letter represents the complement of the class. 7010For instance, <code>%S</code> represents all non-space characters. 7011 7012 7013<p> 7014The definitions of letter, space, and other character groups 7015depend on the current locale. 7016In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 7017 7018 7019 7020 7021 7022<h4>Pattern Item:</h4><p> 7023A <em>pattern item</em> can be 7024 7025<ul> 7026 7027<li> 7028a single character class, 7029which matches any single character in the class; 7030</li> 7031 7032<li> 7033a single character class followed by '<code>*</code>', 7034which matches 0 or more repetitions of characters in the class. 7035These repetition items will always match the longest possible sequence; 7036</li> 7037 7038<li> 7039a single character class followed by '<code>+</code>', 7040which matches 1 or more repetitions of characters in the class. 7041These repetition items will always match the longest possible sequence; 7042</li> 7043 7044<li> 7045a single character class followed by '<code>-</code>', 7046which also matches 0 or more repetitions of characters in the class. 7047Unlike '<code>*</code>', 7048these repetition items will always match the <em>shortest</em> possible sequence; 7049</li> 7050 7051<li> 7052a single character class followed by '<code>?</code>', 7053which matches 0 or 1 occurrence of a character in the class; 7054</li> 7055 7056<li> 7057<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 7058such item matches a substring equal to the <em>n</em>-th captured string 7059(see below); 7060</li> 7061 7062<li> 7063<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 7064such item matches strings that start with <em>x</em>, end with <em>y</em>, 7065and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 7066This means that, if one reads the string from left to right, 7067counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 7068the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 7069For instance, the item <code>%b()</code> matches expressions with 7070balanced parentheses. 7071</li> 7072 7073</ul> 7074 7075 7076 7077 7078<h4>Pattern:</h4><p> 7079A <em>pattern</em> is a sequence of pattern items. 7080A '<code>^</code>' at the beginning of a pattern anchors the match at the 7081beginning of the subject string. 7082A '<code>$</code>' at the end of a pattern anchors the match at the 7083end of the subject string. 7084At other positions, 7085'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 7086 7087 7088 7089 7090 7091<h4>Captures:</h4><p> 7092A pattern can contain sub-patterns enclosed in parentheses; 7093they describe <em>captures</em>. 7094When a match succeeds, the substrings of the subject string 7095that match captures are stored (<em>captured</em>) for future use. 7096Captures are numbered according to their left parentheses. 7097For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 7098the part of the string matching <code>"a*(.)%w(%s*)"</code> is 7099stored as the first capture (and therefore has number 1); 7100the character matching "<code>.</code>" is captured with number 2, 7101and the part matching "<code>%s*</code>" has number 3. 7102 7103 7104<p> 7105As a special case, the empty capture <code>()</code> captures 7106the current string position (a number). 7107For instance, if we apply the pattern <code>"()aa()"</code> on the 7108string <code>"flaaap"</code>, there will be two captures: 3 and 5. 7109 7110 7111<p> 7112A pattern cannot contain embedded zeros. Use <code>%z</code> instead. 7113 7114 7115 7116 7117 7118 7119 7120 7121 7122 7123 7124<h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p> 7125This library provides generic functions for table manipulation. 7126It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 7127 7128 7129<p> 7130Most functions in the table library assume that the table 7131represents an array or a list. 7132For these functions, when we talk about the "length" of a table 7133we mean the result of the length operator. 7134 7135 7136<p> 7137<hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3> 7138Given an array where all elements are strings or numbers, 7139returns <code>table[i]..sep..table[i+1] ··· sep..table[j]</code>. 7140The default value for <code>sep</code> is the empty string, 7141the default for <code>i</code> is 1, 7142and the default for <code>j</code> is the length of the table. 7143If <code>i</code> is greater than <code>j</code>, returns the empty string. 7144 7145 7146 7147 7148<p> 7149<hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3> 7150 7151 7152<p> 7153Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, 7154shifting up other elements to open space, if necessary. 7155The default value for <code>pos</code> is <code>n+1</code>, 7156where <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>), 7157so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 7158of table <code>t</code>. 7159 7160 7161 7162 7163<p> 7164<hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3> 7165 7166 7167<p> 7168Returns the largest positive numerical index of the given table, 7169or zero if the table has no positive numerical indices. 7170(To do its job this function does a linear traversal of 7171the whole table.) 7172 7173 7174 7175 7176<p> 7177<hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3> 7178 7179 7180<p> 7181Removes from <code>table</code> the element at position <code>pos</code>, 7182shifting down other elements to close the space, if necessary. 7183Returns the value of the removed element. 7184The default value for <code>pos</code> is <code>n</code>, 7185where <code>n</code> is the length of the table, 7186so that a call <code>table.remove(t)</code> removes the last element 7187of table <code>t</code>. 7188 7189 7190 7191 7192<p> 7193<hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3> 7194Sorts table elements in a given order, <em>in-place</em>, 7195from <code>table[1]</code> to <code>table[n]</code>, 7196where <code>n</code> is the length of the table. 7197If <code>comp</code> is given, 7198then it must be a function that receives two table elements, 7199and returns true 7200when the first is less than the second 7201(so that <code>not comp(a[i+1],a[i])</code> will be true after the sort). 7202If <code>comp</code> is not given, 7203then the standard Lua operator <code><</code> is used instead. 7204 7205 7206<p> 7207The sort algorithm is not stable; 7208that is, elements considered equal by the given order 7209may have their relative positions changed by the sort. 7210 7211 7212 7213 7214 7215 7216 7217<h2>5.6 - <a name="5.6">Mathematical Functions</a></h2> 7218 7219<p> 7220This library is an interface to the standard C math library. 7221It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>. 7222 7223 7224<p> 7225<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 7226 7227 7228<p> 7229Returns the absolute value of <code>x</code>. 7230 7231 7232 7233 7234<p> 7235<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 7236 7237 7238<p> 7239Returns the arc cosine of <code>x</code> (in radians). 7240 7241 7242 7243 7244<p> 7245<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 7246 7247 7248<p> 7249Returns the arc sine of <code>x</code> (in radians). 7250 7251 7252 7253 7254<p> 7255<hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3> 7256 7257 7258<p> 7259Returns the arc tangent of <code>x</code> (in radians). 7260 7261 7262 7263 7264<p> 7265<hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3> 7266 7267 7268<p> 7269Returns the arc tangent of <code>y/x</code> (in radians), 7270but uses the signs of both parameters to find the 7271quadrant of the result. 7272(It also handles correctly the case of <code>x</code> being zero.) 7273 7274 7275 7276 7277<p> 7278<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 7279 7280 7281<p> 7282Returns the smallest integer larger than or equal to <code>x</code>. 7283 7284 7285 7286 7287<p> 7288<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 7289 7290 7291<p> 7292Returns the cosine of <code>x</code> (assumed to be in radians). 7293 7294 7295 7296 7297<p> 7298<hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3> 7299 7300 7301<p> 7302Returns the hyperbolic cosine of <code>x</code>. 7303 7304 7305 7306 7307<p> 7308<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 7309 7310 7311<p> 7312Returns the angle <code>x</code> (given in radians) in degrees. 7313 7314 7315 7316 7317<p> 7318<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 7319 7320 7321<p> 7322Returns the value <em>e<sup>x</sup></em>. 7323 7324 7325 7326 7327<p> 7328<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 7329 7330 7331<p> 7332Returns the largest integer smaller than or equal to <code>x</code>. 7333 7334 7335 7336 7337<p> 7338<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 7339 7340 7341<p> 7342Returns the remainder of the division of <code>x</code> by <code>y</code> 7343that rounds the quotient towards zero. 7344 7345 7346 7347 7348<p> 7349<hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3> 7350 7351 7352<p> 7353Returns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>, 7354<code>e</code> is an integer and the absolute value of <code>m</code> is 7355in the range <em>[0.5, 1)</em> 7356(or zero when <code>x</code> is zero). 7357 7358 7359 7360 7361<p> 7362<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 7363 7364 7365<p> 7366The value <code>HUGE_VAL</code>, 7367a value larger than or equal to any other numerical value. 7368 7369 7370 7371 7372<p> 7373<hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3> 7374 7375 7376<p> 7377Returns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer). 7378 7379 7380 7381 7382<p> 7383<hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3> 7384 7385 7386<p> 7387Returns the natural logarithm of <code>x</code>. 7388 7389 7390 7391 7392<p> 7393<hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3> 7394 7395 7396<p> 7397Returns the base-10 logarithm of <code>x</code>. 7398 7399 7400 7401 7402<p> 7403<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 7404 7405 7406<p> 7407Returns the maximum value among its arguments. 7408 7409 7410 7411 7412<p> 7413<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 7414 7415 7416<p> 7417Returns the minimum value among its arguments. 7418 7419 7420 7421 7422<p> 7423<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 7424 7425 7426<p> 7427Returns two numbers, 7428the integral part of <code>x</code> and the fractional part of <code>x</code>. 7429 7430 7431 7432 7433<p> 7434<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 7435 7436 7437<p> 7438The value of <em>pi</em>. 7439 7440 7441 7442 7443<p> 7444<hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3> 7445 7446 7447<p> 7448Returns <em>x<sup>y</sup></em>. 7449(You can also use the expression <code>x^y</code> to compute this value.) 7450 7451 7452 7453 7454<p> 7455<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 7456 7457 7458<p> 7459Returns the angle <code>x</code> (given in degrees) in radians. 7460 7461 7462 7463 7464<p> 7465<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 7466 7467 7468<p> 7469This function is an interface to the simple 7470pseudo-random generator function <code>rand</code> provided by ANSI C. 7471(No guarantees can be given for its statistical properties.) 7472 7473 7474<p> 7475When called without arguments, 7476returns a uniform pseudo-random real number 7477in the range <em>[0,1)</em>. 7478When called with an integer number <code>m</code>, 7479<code>math.random</code> returns 7480a uniform pseudo-random integer in the range <em>[1, m]</em>. 7481When called with two integer numbers <code>m</code> and <code>n</code>, 7482<code>math.random</code> returns a uniform pseudo-random 7483integer in the range <em>[m, n]</em>. 7484 7485 7486 7487 7488<p> 7489<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 7490 7491 7492<p> 7493Sets <code>x</code> as the "seed" 7494for the pseudo-random generator: 7495equal seeds produce equal sequences of numbers. 7496 7497 7498 7499 7500<p> 7501<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 7502 7503 7504<p> 7505Returns the sine of <code>x</code> (assumed to be in radians). 7506 7507 7508 7509 7510<p> 7511<hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3> 7512 7513 7514<p> 7515Returns the hyperbolic sine of <code>x</code>. 7516 7517 7518 7519 7520<p> 7521<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 7522 7523 7524<p> 7525Returns the square root of <code>x</code>. 7526(You can also use the expression <code>x^0.5</code> to compute this value.) 7527 7528 7529 7530 7531<p> 7532<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 7533 7534 7535<p> 7536Returns the tangent of <code>x</code> (assumed to be in radians). 7537 7538 7539 7540 7541<p> 7542<hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3> 7543 7544 7545<p> 7546Returns the hyperbolic tangent of <code>x</code>. 7547 7548 7549 7550 7551 7552 7553 7554<h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2> 7555 7556<p> 7557The I/O library provides two different styles for file manipulation. 7558The first one uses implicit file descriptors; 7559that is, there are operations to set a default input file and a 7560default output file, 7561and all input/output operations are over these default files. 7562The second style uses explicit file descriptors. 7563 7564 7565<p> 7566When using implicit file descriptors, 7567all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 7568When using explicit file descriptors, 7569the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor 7570and then all operations are supplied as methods of the file descriptor. 7571 7572 7573<p> 7574The table <code>io</code> also provides 7575three predefined file descriptors with their usual meanings from C: 7576<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>. 7577The I/O library never closes these files. 7578 7579 7580<p> 7581Unless otherwise stated, 7582all I/O functions return <b>nil</b> on failure 7583(plus an error message as a second result and 7584a system-dependent error code as a third result) 7585and some value different from <b>nil</b> on success. 7586 7587 7588<p> 7589<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 7590 7591 7592<p> 7593Equivalent to <code>file:close()</code>. 7594Without a <code>file</code>, closes the default output file. 7595 7596 7597 7598 7599<p> 7600<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 7601 7602 7603<p> 7604Equivalent to <code>file:flush</code> over the default output file. 7605 7606 7607 7608 7609<p> 7610<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 7611 7612 7613<p> 7614When called with a file name, it opens the named file (in text mode), 7615and sets its handle as the default input file. 7616When called with a file handle, 7617it simply sets this file handle as the default input file. 7618When called without parameters, 7619it returns the current default input file. 7620 7621 7622<p> 7623In case of errors this function raises the error, 7624instead of returning an error code. 7625 7626 7627 7628 7629<p> 7630<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3> 7631 7632 7633<p> 7634Opens the given file name in read mode 7635and returns an iterator function that, 7636each time it is called, 7637returns a new line from the file. 7638Therefore, the construction 7639 7640<pre> 7641 for line in io.lines(filename) do <em>body</em> end 7642</pre><p> 7643will iterate over all lines of the file. 7644When the iterator function detects the end of file, 7645it returns <b>nil</b> (to finish the loop) and automatically closes the file. 7646 7647 7648<p> 7649The call <code>io.lines()</code> (with no file name) is equivalent 7650to <code>io.input():lines()</code>; 7651that is, it iterates over the lines of the default input file. 7652In this case it does not close the file when the loop ends. 7653 7654 7655 7656 7657<p> 7658<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 7659 7660 7661<p> 7662This function opens a file, 7663in the mode specified in the string <code>mode</code>. 7664It returns a new file handle, 7665or, in case of errors, <b>nil</b> plus an error message. 7666 7667 7668<p> 7669The <code>mode</code> string can be any of the following: 7670 7671<ul> 7672<li><b>"r":</b> read mode (the default);</li> 7673<li><b>"w":</b> write mode;</li> 7674<li><b>"a":</b> append mode;</li> 7675<li><b>"r+":</b> update mode, all previous data is preserved;</li> 7676<li><b>"w+":</b> update mode, all previous data is erased;</li> 7677<li><b>"a+":</b> append update mode, previous data is preserved, 7678 writing is only allowed at the end of file.</li> 7679</ul><p> 7680The <code>mode</code> string can also have a '<code>b</code>' at the end, 7681which is needed in some systems to open the file in binary mode. 7682This string is exactly what is used in the 7683standard C function <code>fopen</code>. 7684 7685 7686 7687 7688<p> 7689<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 7690 7691 7692<p> 7693Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 7694 7695 7696 7697 7698<p> 7699<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 7700 7701 7702<p> 7703Starts program <code>prog</code> in a separated process and returns 7704a file handle that you can use to read data from this program 7705(if <code>mode</code> is <code>"r"</code>, the default) 7706or to write data to this program 7707(if <code>mode</code> is <code>"w"</code>). 7708 7709 7710<p> 7711This function is system dependent and is not available 7712on all platforms. 7713 7714 7715 7716 7717<p> 7718<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 7719 7720 7721<p> 7722Equivalent to <code>io.input():read</code>. 7723 7724 7725 7726 7727<p> 7728<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 7729 7730 7731<p> 7732Returns a handle for a temporary file. 7733This file is opened in update mode 7734and it is automatically removed when the program ends. 7735 7736 7737 7738 7739<p> 7740<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 7741 7742 7743<p> 7744Checks whether <code>obj</code> is a valid file handle. 7745Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 7746<code>"closed file"</code> if <code>obj</code> is a closed file handle, 7747or <b>nil</b> if <code>obj</code> is not a file handle. 7748 7749 7750 7751 7752<p> 7753<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 7754 7755 7756<p> 7757Equivalent to <code>io.output():write</code>. 7758 7759 7760 7761 7762<p> 7763<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 7764 7765 7766<p> 7767Closes <code>file</code>. 7768Note that files are automatically closed when 7769their handles are garbage collected, 7770but that takes an unpredictable amount of time to happen. 7771 7772 7773 7774 7775<p> 7776<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 7777 7778 7779<p> 7780Saves any written data to <code>file</code>. 7781 7782 7783 7784 7785<p> 7786<hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3> 7787 7788 7789<p> 7790Returns an iterator function that, 7791each time it is called, 7792returns a new line from the file. 7793Therefore, the construction 7794 7795<pre> 7796 for line in file:lines() do <em>body</em> end 7797</pre><p> 7798will iterate over all lines of the file. 7799(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 7800when the loop ends.) 7801 7802 7803 7804 7805<p> 7806<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 7807 7808 7809<p> 7810Reads the file <code>file</code>, 7811according to the given formats, which specify what to read. 7812For each format, 7813the function returns a string (or a number) with the characters read, 7814or <b>nil</b> if it cannot read data with the specified format. 7815When called without formats, 7816it uses a default format that reads the entire next line 7817(see below). 7818 7819 7820<p> 7821The available formats are 7822 7823<ul> 7824 7825<li><b>"*n":</b> 7826reads a number; 7827this is the only format that returns a number instead of a string. 7828</li> 7829 7830<li><b>"*a":</b> 7831reads the whole file, starting at the current position. 7832On end of file, it returns the empty string. 7833</li> 7834 7835<li><b>"*l":</b> 7836reads the next line (skipping the end of line), 7837returning <b>nil</b> on end of file. 7838This is the default format. 7839</li> 7840 7841<li><b><em>number</em>:</b> 7842reads a string with up to this number of characters, 7843returning <b>nil</b> on end of file. 7844If number is zero, 7845it reads nothing and returns an empty string, 7846or <b>nil</b> on end of file. 7847</li> 7848 7849</ul> 7850 7851 7852 7853<p> 7854<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3> 7855 7856 7857<p> 7858Sets and gets the file position, 7859measured from the beginning of the file, 7860to the position given by <code>offset</code> plus a base 7861specified by the string <code>whence</code>, as follows: 7862 7863<ul> 7864<li><b>"set":</b> base is position 0 (beginning of the file);</li> 7865<li><b>"cur":</b> base is current position;</li> 7866<li><b>"end":</b> base is end of file;</li> 7867</ul><p> 7868In case of success, function <code>seek</code> returns the final file position, 7869measured in bytes from the beginning of the file. 7870If this function fails, it returns <b>nil</b>, 7871plus a string describing the error. 7872 7873 7874<p> 7875The default value for <code>whence</code> is <code>"cur"</code>, 7876and for <code>offset</code> is 0. 7877Therefore, the call <code>file:seek()</code> returns the current 7878file position, without changing it; 7879the call <code>file:seek("set")</code> sets the position to the 7880beginning of the file (and returns 0); 7881and the call <code>file:seek("end")</code> sets the position to the 7882end of the file, and returns its size. 7883 7884 7885 7886 7887<p> 7888<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 7889 7890 7891<p> 7892Sets the buffering mode for an output file. 7893There are three available modes: 7894 7895<ul> 7896 7897<li><b>"no":</b> 7898no buffering; the result of any output operation appears immediately. 7899</li> 7900 7901<li><b>"full":</b> 7902full buffering; output operation is performed only 7903when the buffer is full (or when you explicitly <code>flush</code> the file 7904(see <a href="#pdf-io.flush"><code>io.flush</code></a>)). 7905</li> 7906 7907<li><b>"line":</b> 7908line buffering; output is buffered until a newline is output 7909or there is any input from some special files 7910(such as a terminal device). 7911</li> 7912 7913</ul><p> 7914For the last two cases, <code>size</code> 7915specifies the size of the buffer, in bytes. 7916The default is an appropriate size. 7917 7918 7919 7920 7921<p> 7922<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 7923 7924 7925<p> 7926Writes the value of each of its arguments to 7927the <code>file</code>. 7928The arguments must be strings or numbers. 7929To write other values, 7930use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. 7931 7932 7933 7934 7935 7936 7937 7938<h2>5.8 - <a name="5.8">Operating System Facilities</a></h2> 7939 7940<p> 7941This library is implemented through table <a name="pdf-os"><code>os</code></a>. 7942 7943 7944<p> 7945<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 7946 7947 7948<p> 7949Returns an approximation of the amount in seconds of CPU time 7950used by the program. 7951 7952 7953 7954 7955<p> 7956<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 7957 7958 7959<p> 7960Returns a string or a table containing date and time, 7961formatted according to the given string <code>format</code>. 7962 7963 7964<p> 7965If the <code>time</code> argument is present, 7966this is the time to be formatted 7967(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 7968Otherwise, <code>date</code> formats the current time. 7969 7970 7971<p> 7972If <code>format</code> starts with '<code>!</code>', 7973then the date is formatted in Coordinated Universal Time. 7974After this optional character, 7975if <code>format</code> is the string "<code>*t</code>", 7976then <code>date</code> returns a table with the following fields: 7977<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31), 7978<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61), 7979<code>wday</code> (weekday, Sunday is 1), 7980<code>yday</code> (day of the year), 7981and <code>isdst</code> (daylight saving flag, a boolean). 7982 7983 7984<p> 7985If <code>format</code> is not "<code>*t</code>", 7986then <code>date</code> returns the date as a string, 7987formatted according to the same rules as the C function <code>strftime</code>. 7988 7989 7990<p> 7991When called without arguments, 7992<code>date</code> returns a reasonable date and time representation that depends on 7993the host system and on the current locale 7994(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). 7995 7996 7997 7998 7999<p> 8000<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 8001 8002 8003<p> 8004Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. 8005In POSIX, Windows, and some other systems, 8006this value is exactly <code>t2</code><em>-</em><code>t1</code>. 8007 8008 8009 8010 8011<p> 8012<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 8013 8014 8015<p> 8016This function is equivalent to the C function <code>system</code>. 8017It passes <code>command</code> to be executed by an operating system shell. 8018It returns a status code, which is system-dependent. 8019If <code>command</code> is absent, then it returns nonzero if a shell is available 8020and zero otherwise. 8021 8022 8023 8024 8025<p> 8026<hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3> 8027 8028 8029<p> 8030Calls the C function <code>exit</code>, 8031with an optional <code>code</code>, 8032to terminate the host program. 8033The default value for <code>code</code> is the success code. 8034 8035 8036 8037 8038<p> 8039<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 8040 8041 8042<p> 8043Returns the value of the process environment variable <code>varname</code>, 8044or <b>nil</b> if the variable is not defined. 8045 8046 8047 8048 8049<p> 8050<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 8051 8052 8053<p> 8054Deletes the file or directory with the given name. 8055Directories must be empty to be removed. 8056If this function fails, it returns <b>nil</b>, 8057plus a string describing the error. 8058 8059 8060 8061 8062<p> 8063<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 8064 8065 8066<p> 8067Renames file or directory named <code>oldname</code> to <code>newname</code>. 8068If this function fails, it returns <b>nil</b>, 8069plus a string describing the error. 8070 8071 8072 8073 8074<p> 8075<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 8076 8077 8078<p> 8079Sets the current locale of the program. 8080<code>locale</code> is a string specifying a locale; 8081<code>category</code> is an optional string describing which category to change: 8082<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 8083<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 8084the default category is <code>"all"</code>. 8085The function returns the name of the new locale, 8086or <b>nil</b> if the request cannot be honored. 8087 8088 8089<p> 8090If <code>locale</code> is the empty string, 8091the current locale is set to an implementation-defined native locale. 8092If <code>locale</code> is the string "<code>C</code>", 8093the current locale is set to the standard C locale. 8094 8095 8096<p> 8097When called with <b>nil</b> as the first argument, 8098this function only returns the name of the current locale 8099for the given category. 8100 8101 8102 8103 8104<p> 8105<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 8106 8107 8108<p> 8109Returns the current time when called without arguments, 8110or a time representing the date and time specified by the given table. 8111This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 8112and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code> 8113(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function). 8114 8115 8116<p> 8117The returned value is a number, whose meaning depends on your system. 8118In POSIX, Windows, and some other systems, this number counts the number 8119of seconds since some given start time (the "epoch"). 8120In other systems, the meaning is not specified, 8121and the number returned by <code>time</code> can be used only as an argument to 8122<code>date</code> and <code>difftime</code>. 8123 8124 8125 8126 8127<p> 8128<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 8129 8130 8131<p> 8132Returns a string with a file name that can 8133be used for a temporary file. 8134The file must be explicitly opened before its use 8135and explicitly removed when no longer needed. 8136 8137 8138<p> 8139On some systems (POSIX), 8140this function also creates a file with that name, 8141to avoid security risks. 8142(Someone else might create the file with wrong permissions 8143in the time between getting the name and creating the file.) 8144You still have to open the file to use it 8145and to remove it (even if you do not use it). 8146 8147 8148<p> 8149When possible, 8150you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 8151which automatically removes the file when the program ends. 8152 8153 8154 8155 8156 8157 8158 8159<h2>5.9 - <a name="5.9">The Debug Library</a></h2> 8160 8161<p> 8162This library provides 8163the functionality of the debug interface to Lua programs. 8164You should exert care when using this library. 8165The functions provided here should be used exclusively for debugging 8166and similar tasks, such as profiling. 8167Please resist the temptation to use them as a 8168usual programming tool: 8169they can be very slow. 8170Moreover, several of these functions 8171violate some assumptions about Lua code 8172(e.g., that variables local to a function 8173cannot be accessed from outside or 8174that userdata metatables cannot be changed by Lua code) 8175and therefore can compromise otherwise secure code. 8176 8177 8178<p> 8179All functions in this library are provided 8180inside the <a name="pdf-debug"><code>debug</code></a> table. 8181All functions that operate over a thread 8182have an optional first argument which is the 8183thread to operate over. 8184The default is always the current thread. 8185 8186 8187<p> 8188<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 8189 8190 8191<p> 8192Enters an interactive mode with the user, 8193running each string that the user enters. 8194Using simple commands and other debug facilities, 8195the user can inspect global and local variables, 8196change their values, evaluate expressions, and so on. 8197A line containing only the word <code>cont</code> finishes this function, 8198so that the caller continues its execution. 8199 8200 8201<p> 8202Note that commands for <code>debug.debug</code> are not lexically nested 8203within any function, and so have no direct access to local variables. 8204 8205 8206 8207 8208<p> 8209<hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3> 8210Returns the environment of object <code>o</code>. 8211 8212 8213 8214 8215<p> 8216<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 8217 8218 8219<p> 8220Returns the current hook settings of the thread, as three values: 8221the current hook function, the current hook mask, 8222and the current hook count 8223(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 8224 8225 8226 8227 8228<p> 8229<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3> 8230 8231 8232<p> 8233Returns a table with information about a function. 8234You can give the function directly, 8235or you can give a number as the value of <code>function</code>, 8236which means the function running at level <code>function</code> of the call stack 8237of the given thread: 8238level 0 is the current function (<code>getinfo</code> itself); 8239level 1 is the function that called <code>getinfo</code>; 8240and so on. 8241If <code>function</code> is a number larger than the number of active functions, 8242then <code>getinfo</code> returns <b>nil</b>. 8243 8244 8245<p> 8246The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 8247with the string <code>what</code> describing which fields to fill in. 8248The default for <code>what</code> is to get all information available, 8249except the table of valid lines. 8250If present, 8251the option '<code>f</code>' 8252adds a field named <code>func</code> with the function itself. 8253If present, 8254the option '<code>L</code>' 8255adds a field named <code>activelines</code> with the table of 8256valid lines. 8257 8258 8259<p> 8260For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 8261a table with a name for the current function, 8262if a reasonable name can be found, 8263and the expression <code>debug.getinfo(print)</code> 8264returns a table with all available information 8265about the <a href="#pdf-print"><code>print</code></a> function. 8266 8267 8268 8269 8270<p> 8271<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3> 8272 8273 8274<p> 8275This function returns the name and the value of the local variable 8276with index <code>local</code> of the function at level <code>level</code> of the stack. 8277(The first parameter or local variable has index 1, and so on, 8278until the last active local variable.) 8279The function returns <b>nil</b> if there is no local 8280variable with the given index, 8281and raises an error when called with a <code>level</code> out of range. 8282(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 8283 8284 8285<p> 8286Variable names starting with '<code>(</code>' (open parentheses) 8287represent internal variables 8288(loop control variables, temporaries, and C function locals). 8289 8290 8291 8292 8293<p> 8294<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3> 8295 8296 8297<p> 8298Returns the metatable of the given <code>object</code> 8299or <b>nil</b> if it does not have a metatable. 8300 8301 8302 8303 8304<p> 8305<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 8306 8307 8308<p> 8309Returns the registry table (see <a href="#3.5">§3.5</a>). 8310 8311 8312 8313 8314<p> 8315<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3> 8316 8317 8318<p> 8319This function returns the name and the value of the upvalue 8320with index <code>up</code> of the function <code>func</code>. 8321The function returns <b>nil</b> if there is no upvalue with the given index. 8322 8323 8324 8325 8326<p> 8327<hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3> 8328 8329 8330<p> 8331Sets the environment of the given <code>object</code> to the given <code>table</code>. 8332Returns <code>object</code>. 8333 8334 8335 8336 8337<p> 8338<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 8339 8340 8341<p> 8342Sets the given function as a hook. 8343The string <code>mask</code> and the number <code>count</code> describe 8344when the hook will be called. 8345The string mask may have the following characters, 8346with the given meaning: 8347 8348<ul> 8349<li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li> 8350<li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li> 8351<li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li> 8352</ul><p> 8353With a <code>count</code> different from zero, 8354the hook is called after every <code>count</code> instructions. 8355 8356 8357<p> 8358When called without arguments, 8359<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 8360 8361 8362<p> 8363When the hook is called, its first parameter is a string 8364describing the event that has triggered its call: 8365<code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>, 8366when simulating a return from a tail call), 8367<code>"line"</code>, and <code>"count"</code>. 8368For line events, 8369the hook also gets the new line number as its second parameter. 8370Inside a hook, 8371you can call <code>getinfo</code> with level 2 to get more information about 8372the running function 8373(level 0 is the <code>getinfo</code> function, 8374and level 1 is the hook function), 8375unless the event is <code>"tail return"</code>. 8376In this case, Lua is only simulating the return, 8377and a call to <code>getinfo</code> will return invalid data. 8378 8379 8380 8381 8382<p> 8383<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 8384 8385 8386<p> 8387This function assigns the value <code>value</code> to the local variable 8388with index <code>local</code> of the function at level <code>level</code> of the stack. 8389The function returns <b>nil</b> if there is no local 8390variable with the given index, 8391and raises an error when called with a <code>level</code> out of range. 8392(You can call <code>getinfo</code> to check whether the level is valid.) 8393Otherwise, it returns the name of the local variable. 8394 8395 8396 8397 8398<p> 8399<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3> 8400 8401 8402<p> 8403Sets the metatable for the given <code>object</code> to the given <code>table</code> 8404(which can be <b>nil</b>). 8405 8406 8407 8408 8409<p> 8410<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3> 8411 8412 8413<p> 8414This function assigns the value <code>value</code> to the upvalue 8415with index <code>up</code> of the function <code>func</code>. 8416The function returns <b>nil</b> if there is no upvalue 8417with the given index. 8418Otherwise, it returns the name of the upvalue. 8419 8420 8421 8422 8423<p> 8424<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])</code></a></h3> 8425 8426 8427<p> 8428Returns a string with a traceback of the call stack. 8429An optional <code>message</code> string is appended 8430at the beginning of the traceback. 8431An optional <code>level</code> number tells at which level 8432to start the traceback 8433(default is 1, the function calling <code>traceback</code>). 8434 8435 8436 8437 8438 8439 8440 8441<h1>6 - <a name="6">Lua Stand-alone</a></h1> 8442 8443<p> 8444Although Lua has been designed as an extension language, 8445to be embedded in a host C program, 8446it is also frequently used as a stand-alone language. 8447An interpreter for Lua as a stand-alone language, 8448called simply <code>lua</code>, 8449is provided with the standard distribution. 8450The stand-alone interpreter includes 8451all standard libraries, including the debug library. 8452Its usage is: 8453 8454<pre> 8455 lua [options] [script [args]] 8456</pre><p> 8457The options are: 8458 8459<ul> 8460<li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li> 8461<li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li> 8462<li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li> 8463<li><b><code>-v</code>:</b> prints version information;</li> 8464<li><b><code>--</code>:</b> stops handling options;</li> 8465<li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li> 8466</ul><p> 8467After handling its options, <code>lua</code> runs the given <em>script</em>, 8468passing to it the given <em>args</em> as string arguments. 8469When called without arguments, 8470<code>lua</code> behaves as <code>lua -v -i</code> 8471when the standard input (<code>stdin</code>) is a terminal, 8472and as <code>lua -</code> otherwise. 8473 8474 8475<p> 8476Before running any argument, 8477the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>. 8478If its format is <code>@<em>filename</em></code>, 8479then <code>lua</code> executes the file. 8480Otherwise, <code>lua</code> executes the string itself. 8481 8482 8483<p> 8484All options are handled in order, except <code>-i</code>. 8485For instance, an invocation like 8486 8487<pre> 8488 $ lua -e'a=1' -e 'print(a)' script.lua 8489</pre><p> 8490will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'), 8491and finally run the file <code>script.lua</code> with no arguments. 8492(Here <code>$</code> is the shell prompt. Your prompt may be different.) 8493 8494 8495<p> 8496Before starting to run the script, 8497<code>lua</code> collects all arguments in the command line 8498in a global table called <code>arg</code>. 8499The script name is stored at index 0, 8500the first argument after the script name goes to index 1, 8501and so on. 8502Any arguments before the script name 8503(that is, the interpreter name plus the options) 8504go to negative indices. 8505For instance, in the call 8506 8507<pre> 8508 $ lua -la b.lua t1 t2 8509</pre><p> 8510the interpreter first runs the file <code>a.lua</code>, 8511then creates a table 8512 8513<pre> 8514 arg = { [-2] = "lua", [-1] = "-la", 8515 [0] = "b.lua", 8516 [1] = "t1", [2] = "t2" } 8517</pre><p> 8518and finally runs the file <code>b.lua</code>. 8519The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ··· 8520as arguments; 8521it can also access these arguments with the vararg expression '<code>...</code>'. 8522 8523 8524<p> 8525In interactive mode, 8526if you write an incomplete statement, 8527the interpreter waits for its completion 8528by issuing a different prompt. 8529 8530 8531<p> 8532If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 8533then its value is used as the prompt. 8534Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 8535its value is used as the secondary prompt 8536(issued during incomplete statements). 8537Therefore, both prompts can be changed directly on the command line 8538or in any Lua programs by assigning to <code>_PROMPT</code>. 8539See the next example: 8540 8541<pre> 8542 $ lua -e"_PROMPT='myprompt> '" -i 8543</pre><p> 8544(The outer pair of quotes is for the shell, 8545the inner pair is for Lua.) 8546Note the use of <code>-i</code> to enter interactive mode; 8547otherwise, 8548the program would just end silently 8549right after the assignment to <code>_PROMPT</code>. 8550 8551 8552<p> 8553To allow the use of Lua as a 8554script interpreter in Unix systems, 8555the stand-alone interpreter skips 8556the first line of a chunk if it starts with <code>#</code>. 8557Therefore, Lua scripts can be made into executable programs 8558by using <code>chmod +x</code> and the <code>#!</code> form, 8559as in 8560 8561<pre> 8562 #!/usr/local/bin/lua 8563</pre><p> 8564(Of course, 8565the location of the Lua interpreter may be different in your machine. 8566If <code>lua</code> is in your <code>PATH</code>, 8567then 8568 8569<pre> 8570 #!/usr/bin/env lua 8571</pre><p> 8572is a more portable solution.) 8573 8574 8575 8576<h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1> 8577 8578<p> 8579Here we list the incompatibilities that you may find when moving a program 8580from Lua 5.0 to Lua 5.1. 8581You can avoid most of the incompatibilities compiling Lua with 8582appropriate options (see file <code>luaconf.h</code>). 8583However, 8584all these compatibility options will be removed in the next version of Lua. 8585 8586 8587 8588<h2>7.1 - <a name="7.1">Changes in the Language</a></h2> 8589<ul> 8590 8591<li> 8592The vararg system changed from the pseudo-argument <code>arg</code> with a 8593table with the extra arguments to the vararg expression. 8594(See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) 8595</li> 8596 8597<li> 8598There was a subtle change in the scope of the implicit 8599variables of the <b>for</b> statement and for the <b>repeat</b> statement. 8600</li> 8601 8602<li> 8603The long string/long comment syntax (<code>[[<em>string</em>]]</code>) 8604does not allow nesting. 8605You can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases. 8606(See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) 8607</li> 8608 8609</ul> 8610 8611 8612 8613 8614<h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2> 8615<ul> 8616 8617<li> 8618Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. 8619(See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.) 8620</li> 8621 8622<li> 8623When <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its 8624third argument, 8625whenever this function returns <b>nil</b> or <b>false</b> the 8626replacement string is the whole match, 8627instead of the empty string. 8628</li> 8629 8630<li> 8631Function <code>table.setn</code> was deprecated. 8632Function <code>table.getn</code> corresponds 8633to the new length operator (<code>#</code>); 8634use the operator instead of the function. 8635(See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.) 8636</li> 8637 8638<li> 8639Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>. 8640(See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.) 8641</li> 8642 8643<li> 8644Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>. 8645(See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.) 8646</li> 8647 8648<li> 8649Functions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated. 8650You can use a for loop with <code>pairs</code> or <code>ipairs</code> instead. 8651</li> 8652 8653<li> 8654There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to 8655the new module system. 8656However, the new behavior is mostly compatible with the old, 8657but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead 8658of from <code>LUA_PATH</code>. 8659</li> 8660 8661<li> 8662Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments. 8663Function <code>gcinfo</code> is deprecated; 8664use <code>collectgarbage("count")</code> instead. 8665</li> 8666 8667</ul> 8668 8669 8670 8671 8672<h2>7.3 - <a name="7.3">Changes in the API</a></h2> 8673<ul> 8674 8675<li> 8676The <code>luaopen_*</code> functions (to open libraries) 8677cannot be called directly, 8678like a regular C function. 8679They must be called through Lua, 8680like a Lua function. 8681</li> 8682 8683<li> 8684Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to 8685allow the user to set a memory-allocation function. 8686You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to 8687create a state with a standard allocation function 8688(based on <code>realloc</code>). 8689</li> 8690 8691<li> 8692Functions <code>luaL_getn</code> and <code>luaL_setn</code> 8693(from the auxiliary library) are deprecated. 8694Use <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code> 8695and nothing instead of <code>luaL_setn</code>. 8696</li> 8697 8698<li> 8699Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>. 8700</li> 8701 8702<li> 8703Function <code>luaL_checkudata</code> now throws an error when the given value 8704is not a userdata of the expected type. 8705(In Lua 5.0 it returned <code>NULL</code>.) 8706</li> 8707 8708</ul> 8709 8710 8711 8712 8713<h1>8 - <a name="8">The Complete Syntax of Lua</a></h1> 8714 8715<p> 8716Here is the complete syntax of Lua in extended BNF. 8717(It does not describe operator precedences.) 8718 8719 8720 8721 8722<pre> 8723 8724 chunk ::= {stat [`<b>;</b>´]} [laststat [`<b>;</b>´]] 8725 8726 block ::= chunk 8727 8728 stat ::= varlist `<b>=</b>´ explist | 8729 functioncall | 8730 <b>do</b> block <b>end</b> | 8731 <b>while</b> exp <b>do</b> block <b>end</b> | 8732 <b>repeat</b> block <b>until</b> exp | 8733 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 8734 <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> | 8735 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 8736 <b>function</b> funcname funcbody | 8737 <b>local</b> <b>function</b> Name funcbody | 8738 <b>local</b> namelist [`<b>=</b>´ explist] 8739 8740 laststat ::= <b>return</b> [explist] | <b>break</b> 8741 8742 funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] 8743 8744 varlist ::= var {`<b>,</b>´ var} 8745 8746 var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name 8747 8748 namelist ::= Name {`<b>,</b>´ Name} 8749 8750 explist ::= {exp `<b>,</b>´} exp 8751 8752 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function | 8753 prefixexp | tableconstructor | exp binop exp | unop exp 8754 8755 prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ 8756 8757 functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args 8758 8759 args ::= `<b>(</b>´ [explist] `<b>)</b>´ | tableconstructor | String 8760 8761 function ::= <b>function</b> funcbody 8762 8763 funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> 8764 8765 parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ 8766 8767 tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ 8768 8769 fieldlist ::= field {fieldsep field} [fieldsep] 8770 8771 field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp 8772 8773 fieldsep ::= `<b>,</b>´ | `<b>;</b>´ 8774 8775 binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ | 8776 `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ | 8777 <b>and</b> | <b>or</b> 8778 8779 unop ::= `<b>-</b>´ | <b>not</b> | `<b>#</b>´ 8780 8781</pre> 8782 8783<p> 8784 8785 8786 8787 8788 8789 8790 8791<HR> 8792<SMALL> 8793Last update: 8794Mon Aug 18 13:25:46 BRT 2008 8795</SMALL> 8796<!-- 8797Last change: revised for Lua 5.1.4 8798--> 8799 8800</body></html> 8801 8802