| blob | 63d28ae0c2f3a76e2711e5e7c201eabcfd90148d |
2 <HTML>
3 <HEAD>
8 </HEAD>
10 <BODY>
12 <H1>
14 Lua 5.3 Reference Manual
15 </H1>
17 <P>
18 by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
20 <P>
21 <SMALL>
23 Freely available under the terms of the
25 </SMALL>
29 ·
31 ·
33 </DIV>
35 <!-- ====================================================================== -->
36 <p>
38 <!-- Id: manual.of,v 1.151 2015/06/10 21:08:57 roberto Exp -->
45 <p>
46 Lua is an extension programming language designed to support
47 general procedural programming with data description
48 facilities.
49 Lua also offers good support for object-oriented programming,
50 functional programming, and data-driven programming.
51 Lua is intended to be used as a powerful, lightweight,
52 embeddable scripting language for any program that needs one.
54 the common subset of Standard C and C++.
57 <p>
58 As an extension language, Lua has no notion of a "main" program:
61 The host program can invoke functions to execute a piece of Lua code,
62 can write and read Lua variables,
63 and can register C functions to be called by Lua code.
64 Through the use of C functions, Lua can be augmented to cope with
65 a wide range of different domains,
66 thus creating customized programming languages sharing a syntactical framework.
68 which uses the Lua library to offer a complete, standalone Lua interpreter,
69 for interactive or batch use.
72 <p>
73 Lua is free software,
74 and is provided as usual with no guarantees,
75 as stated in its license.
76 The implementation described in this manual is available
80 <p>
81 Like any other reference manual,
82 this document is dry in places.
83 For a discussion of the decisions behind the design of Lua,
84 see the technical papers available at Lua's web site.
85 For a detailed introduction to programming in Lua,
92 <p>
93 This section describes the basic concepts of the language.
99 <p>
101 This means that
102 variables do not have types; only values do.
103 There are no type definitions in the language.
104 All values carry their own type.
107 <p>
109 This means that all values can be stored in variables,
110 passed as arguments to other functions, and returned as results.
113 <p>
114 There are eight basic types in Lua:
119 whose main property is to be different from any other value;
120 it usually represents the absence of a useful value.
123 any other value makes it true.
125 integer numbers and real (floating-point) numbers.
128 Lua is 8-bit clean:
129 strings can contain any 8-bit value,
131 Lua is also encoding-agnostic;
132 it makes no assumptions about the contents of a string.
135 <p>
137 or two subtypes,
139 Lua has explicit rules about when each representation is used,
140 but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>).
141 Therefore,
142 the programmer may choose to mostly ignore the difference
143 between integers and floats
144 or to assume complete control over the representation of each number.
146 but you can also compile Lua so that it
148 The option with 32 bits for both integers and floats
149 is particularly attractive
150 for small machines and embedded systems.
154 <p>
155 Lua can call (and manipulate) functions written in Lua and
160 <p>
162 be stored in Lua variables.
163 A userdata value represents a block of raw memory.
164 There are two kinds of userdata:
166 which is an object with a block of memory managed by Lua,
168 which is simply a C pointer value.
169 Userdata has no predefined operations in Lua,
170 except assignment and identity test.
172 the programmer can define operations for full userdata values
174 Userdata values cannot be created or modified in Lua,
175 only through the C API.
176 This guarantees the integrity of data owned by the host program.
179 <p>
182 Lua threads are not related to operating-system threads.
183 Lua supports coroutines on all systems,
184 even those that do not support threads natively.
187 <p>
189 that is, arrays that can be indexed not only with numbers,
196 Conversely, any key that is not part of a table has
200 <p>
201 Tables are the sole data-structuring mechanism in Lua;
202 they can be used to represent ordinary arrays, sequences,
203 symbol tables, sets, records, graphs, trees, etc.
204 To represent records, Lua uses the field name as an index.
205 The language supports this representation by
207 There are several convenient ways to create tables in Lua
211 <p>
218 <p>
219 Like indices,
220 the values of table fields can be of any type.
221 In particular,
222 because functions are first-class values,
223 table fields can contain functions.
227 <p>
228 The indexing of tables follows
229 the definition of raw equality in the language.
231 denote the same table element
233 (that is, equal without metamethods).
234 In particular, floats with integral values
235 are equal to their respective integers
237 To avoid ambiguities,
238 any float with integral value used as a key
239 is converted to its respective integer.
241 the actual key inserted into the table will be the
243 (On the other hand,
245 denote different table entries.)
248 <p>
252 Assignment, parameter passing, and function returns
253 always manipulate references to such values;
254 these operations do not imply any kind of copy.
257 <p>
258 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
267 <p>
269 any reference to a free name
272 Moreover, every chunk is compiled in the scope of
277 <p>
279 the translation of free names,
281 In particular,
282 you can define new variables and parameters with that name.
284 visible at that point in the program,
288 <p>
292 <p>
295 In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value.
299 <p>
300 When Lua loads a chunk,
303 Therefore, by default,
304 free names in Lua code refer to entries in the global environment
306 Moreover, all standard libraries are loaded in the global environment
307 and some functions there operate on that environment.
308 You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>)
309 to load a chunk with a different environment.
310 (In C, you have to load the chunk and then change the value
311 of its first upvalue.)
319 <p>
320 Because Lua is an embedded extension language,
321 all Lua actions start from C code in the host program
322 calling a function from the Lua library.
323 (When you use Lua standalone,
325 Whenever an error occurs during
326 the compilation or execution of a Lua chunk,
327 control returns to the host,
328 which can take appropriate measures
329 (such as printing an error message).
332 <p>
333 Lua code can explicitly generate an error by calling the
335 If you need to catch errors in Lua,
336 you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a>
340 <p>
341 Whenever there is an error,
343 is propagated with information about the error.
344 Lua itself only generates errors whose error object is a string,
345 but programs may generate errors with
346 any value as the error object.
347 It is up to the Lua program or its host to handle such error objects.
350 <p>
351 When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>,
353 to be called in case of errors.
354 This function is called with the original error message
355 and returns a new error message.
356 It is called before the error unwinds the stack,
357 so that it can gather more information about the error,
358 for instance by inspecting the stack and creating a stack traceback.
359 This message handler is still protected by the protected call;
360 so, an error inside the message handler
361 will call the message handler again.
362 If this loop goes on for too long,
363 Lua breaks it and returns an appropriate message.
371 <p>
374 that defines the behavior of the original value
375 under certain special operations.
376 You can change several aspects of the behavior
377 of operations over a value by setting specific fields in its metatable.
378 For instance, when a non-numeric value is the operand of an addition,
379 Lua checks for a function in the field "<code>__add</code>" of the value's metatable.
380 If it finds one,
381 Lua calls this function to perform the addition.
384 <p>
388 and the metamethod is the function that performs the addition.
391 <p>
392 You can query the metatable of any value
396 <p>
397 You can replace the metatable of tables
399 You cannot change the metatable of other types from Lua code
401 you must use the C API for that.
404 <p>
405 Tables and full userdata have individual metatables
406 (although multiple tables and userdata can share their metatables).
407 Values of all other types share one single metatable per type;
408 that is, there is one single metatable for all numbers,
409 one for all strings, etc.
410 By default, a value has no metatable,
414 <p>
415 A metatable controls how an object behaves in
416 arithmetic operations, bitwise operations,
417 order comparisons, concatenation, length operation, calls, and indexing.
418 A metatable also can define a function to be called
422 <p>
423 A detailed list of events controlled by metatables is given next.
424 Each operation is identified by its corresponding event name.
425 The key for each event is a string with its name prefixed by
427 for instance, the key for operation "add" is the
428 string "<code>__add</code>".
429 Note that queries for metamethods are always raw;
430 the access to a metamethod does not invoke other metamethods.
433 <p>
434 For the unary operators (negation, length, and bitwise not),
435 the metamethod is computed and called with a dummy second operand,
436 equal to the first one.
437 This extra operand is only to simplify Lua's internals
438 (by making these operators behave like a binary operation)
439 and may be removed in future versions.
440 (For most uses this extra operand is irrelevant.)
444 <ul>
449 If any operand for an addition is not a number
450 (nor a string coercible to a number),
451 Lua will try to call a metamethod.
452 First, Lua will check the first operand (even if it is valid).
453 If that operand does not define a metamethod for the "<code>__add</code>" event,
454 then Lua will check the second operand.
455 If Lua can find a metamethod,
456 it calls the metamethod with the two operands as arguments,
457 and the result of the call
458 (adjusted to one value)
459 is the result of the operation.
460 Otherwise,
461 it raises an error.
462 </li>
467 Behavior similar to the "add" operation.
468 </li>
473 Behavior similar to the "add" operation.
474 </li>
479 Behavior similar to the "add" operation.
480 </li>
485 Behavior similar to the "add" operation.
486 </li>
491 Behavior similar to the "add" operation.
492 </li>
497 Behavior similar to the "add" operation.
498 </li>
503 Behavior similar to the "add" operation.
504 </li>
509 Behavior similar to the "add" operation,
510 except that Lua will try a metamethod
511 if any operand is neither an integer
513 </li>
518 Behavior similar to the "band" operation.
519 </li>
524 Behavior similar to the "band" operation.
525 </li>
530 Behavior similar to the "band" operation.
531 </li>
536 Behavior similar to the "band" operation.
537 </li>
542 Behavior similar to the "band" operation.
543 </li>
548 Behavior similar to the "add" operation,
549 except that Lua will try a metamethod
550 if any operand is neither a string nor a number
551 (which is always coercible to a string).
552 </li>
557 If the object is not a string,
558 Lua will try its metamethod.
559 If there is a metamethod,
560 Lua calls it with the object as argument,
561 and the result of the call
562 (always adjusted to one value)
563 is the result of the operation.
564 If there is no metamethod but the object is a table,
566 Otherwise, Lua raises an error.
567 </li>
572 Behavior similar to the "add" operation,
573 except that Lua will try a metamethod only when the values
574 being compared are either both tables or both full userdata
575 and they are not primitively equal.
576 The result of the call is always converted to a boolean.
577 </li>
582 Behavior similar to the "add" operation,
583 except that Lua will try a metamethod only when the values
584 being compared are neither both numbers nor both strings.
585 The result of the call is always converted to a boolean.
586 </li>
591 Unlike other operations,
592 The less-equal operation can use two different events.
593 First, Lua looks for the "<code>__le</code>" metamethod in both operands,
594 like in the "lt" operation.
595 If it cannot find such a metamethod,
596 then it will try the "<code>__lt</code>" event,
598 As with the other comparison operators,
599 the result is always a boolean.
600 (This use of the "<code>__lt</code>" event can be removed in future versions;
601 it is also slower than a real "<code>__le</code>" metamethod.)
602 </li>
612 <p>
613 Despite the name,
614 the metamethod for this event can be either a function or a table.
615 If it is a function,
617 If it is a table,
619 (This indexing is regular, not raw,
620 and therefore can trigger another metamethod.)
621 </li>
626 Like the index event,
632 <p>
633 Like with indexing,
634 the metamethod for this event can be either a function or a table.
635 If it is a function,
637 If it is a table,
638 Lua does an indexing assignment to this table with the same key and value.
639 (This assignment is regular, not raw,
640 and therefore can trigger another metamethod.)
643 <p>
644 Whenever there is a "newindex" metamethod,
645 Lua does not perform the primitive assignment.
646 (If necessary,
648 to do the assignment.)
649 </li>
654 This event happens when Lua tries to call a non-function value
657 If present,
660 </li>
662 </ul>
664 <p>
665 It is a good practice to add all needed metamethods to a table
666 before setting it as a metatable of some object.
667 In particular, the "<code>__gc</code>" metamethod works only when this order
676 <p>
677 Lua performs automatic memory management.
678 This means that
679 you do not have to worry about allocating memory for new objects
680 or freeing it when the objects are no longer needed.
681 Lua manages memory automatically by running
683 (that is, objects that are no longer accessible from Lua).
684 All memory used by Lua is subject to automatic management:
685 strings, tables, userdata, functions, threads, internal structures, etc.
688 <p>
689 Lua implements an incremental mark-and-sweep collector.
690 It uses two numbers to control its garbage-collection cycles:
693 Both use percentage points as units
697 <p>
698 The garbage-collector pause
699 controls how long the collector waits before starting a new cycle.
700 Larger values make the collector less aggressive.
701 Values smaller than 100 mean the collector will not wait to
702 start a new cycle.
703 A value of 200 means that the collector waits for the total memory in use
704 to double before starting a new cycle.
707 <p>
708 The garbage-collector step multiplier
709 controls the relative speed of the collector relative to
710 memory allocation.
711 Larger values make the collector more aggressive but also increase
712 the size of each incremental step.
713 You should not use values smaller than 100,
714 because they make the collector too slow and
715 can result in the collector never finishing a cycle.
716 The default is 200,
717 which means that the collector runs at "twice"
718 the speed of memory allocation.
721 <p>
722 If you set the step multiplier to a very large number
723 (larger than 10% of the maximum number of
724 bytes that the program may use),
725 the collector behaves like a stop-the-world collector.
726 If you then set the pause to 200,
727 the collector behaves as in old Lua versions,
728 doing a complete collection every time Lua doubles its
729 memory usage.
732 <p>
735 You can also use these functions to control
736 the collector directly (e.g., stop and restart it).
742 <p>
743 You can set garbage-collector metamethods for tables
744 and, using the C API,
747 Finalizers allow you to coordinate Lua's garbage collection
748 with external resource management
749 (such as closing files, network or database connections,
750 or freeing your own memory).
753 <p>
754 For an object (table or userdata) to be finalized when collected,
757 You mark an object for finalization when you set its metatable
758 and the metatable has a field indexed by the string "<code>__gc</code>".
760 and later create that field in the metatable,
761 the object will not be marked for finalization.
764 <p>
765 When a marked object becomes garbage,
766 it is not collected immediately by the garbage collector.
767 Instead, Lua puts it in a list.
768 After the collection,
769 Lua goes through that list.
770 For each object in the list,
772 If it is a function,
773 Lua calls it with the object as its single argument;
774 if the metamethod is not a function,
775 Lua simply ignores it.
778 <p>
779 At the end of each garbage-collection cycle,
780 the finalizers for objects are called in
781 the reverse order that the objects were marked for finalization,
782 among those collected in that cycle;
783 that is, the first finalizer to be called is the one associated
784 with the object marked last in the program.
785 The execution of each finalizer may occur at any point during
786 the execution of the regular code.
789 <p>
790 Because the object being collected must still be used by the finalizer,
791 that object (and other objects accessible only through it)
793 Usually, this resurrection is transient,
794 and the object memory is freed in the next garbage-collection cycle.
795 However, if the finalizer stores the object in some global place
796 (e.g., a global variable),
797 then the resurrection is permanent.
798 Moreover, if the finalizer marks a finalizing object for finalization again,
799 its finalizer will be called again in the next cycle where the
800 object is unreachable.
801 In any case,
802 the object memory is freed only in a GC cycle where
803 the object is unreachable and not marked for finalization.
806 <p>
808 Lua calls the finalizers of all objects marked for finalization,
809 following the reverse order that they were marked.
810 If any finalizer marks objects for collection during that phase,
811 these marks have no effect.
819 <p>
822 A weak reference is ignored by the garbage collector.
823 In other words,
824 if the only references to an object are weak references,
825 then the garbage collector will collect that object.
828 <p>
829 A weak table can have weak keys, weak values, or both.
830 A table with weak values allows the collection of its values,
831 but prevents the collection of its keys.
832 A table with both weak keys and weak values allows the collection of
833 both keys and values.
834 In any case, if either the key or the value is collected,
835 the whole pair is removed from the table.
836 The weakness of a table is controlled by the
839 the keys in the table are weak.
841 the values in the table are weak.
844 <p>
845 A table with weak keys and strong values
847 In an ephemeron table,
848 a value is considered reachable only if its key is reachable.
849 In particular,
850 if the only reference to a key comes through its value,
851 the pair is removed.
854 <p>
855 Any change in the weakness of a table may take effect only
856 at the next collect cycle.
857 In particular, if you change the weakness to a stronger mode,
858 Lua may still collect some items from that table
859 before the change takes effect.
862 <p>
863 Only objects that have an explicit construction
864 are removed from weak tables.
865 Values, such as numbers and light C functions,
866 are not subject to garbage collection,
867 and therefore are not removed from weak tables
868 (unless their associated values are collected).
869 Although strings are subject to garbage collection,
870 they do not have an explicit construction,
871 and therefore are not removed from weak tables.
874 <p>
875 Resurrected objects
876 (that is, objects being finalized
877 and objects accessible only through objects being finalized)
878 have a special behavior in weak tables.
879 They are removed from weak values before running their finalizers,
880 but are removed from weak keys only in the next collection
881 after running their finalizers, when such objects are actually freed.
882 This behavior allows the finalizer to access properties
883 associated with the object through weak tables.
886 <p>
887 If a weak table is among the resurrected objects in a collection cycle,
888 it may not be properly cleared until the next cycle.
898 <p>
899 Lua supports coroutines,
901 A coroutine in Lua represents an independent thread of execution.
902 Unlike threads in multithread systems, however,
903 a coroutine only suspends its execution by explicitly calling
904 a yield function.
907 <p>
908 You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
909 Its sole argument is a function
910 that is the main function of the coroutine.
913 it does not start the coroutine.
916 <p>
917 You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
919 passing as its first argument
921 the coroutine starts its execution by
922 calling its main function.
923 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
924 as arguments to that function.
925 After the coroutine starts running,
929 <p>
930 A coroutine can terminate its execution in two ways:
931 normally, when its main function returns
932 (explicitly or implicitly, after the last instruction);
933 and abnormally, if there is an unprotected error.
934 In case of normal termination,
936 plus any values returned by the coroutine main function.
937 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
938 plus an error message.
941 <p>
943 When a coroutine yields,
944 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
945 even if the yield happens inside nested function calls
946 (that is, not in the main function,
947 but in a function directly or indirectly called by the main function).
948 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
950 The next time you resume the same coroutine,
951 it continues its execution from the point where it yielded,
952 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
956 <p>
958 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
959 but instead of returning the coroutine itself,
960 it returns a function that, when called, resumes the coroutine.
961 Any arguments passed to this function
963 <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>,
964 except the first one (the boolean error code).
967 any error is propagated to the caller.
970 <p>
971 As an example of how coroutines work,
972 consider the following code:
974 <pre>
975 function foo (a)
976 print("foo", a)
977 return coroutine.yield(2*a)
978 end
980 co = coroutine.create(function (a,b)
981 print("co-body", a, b)
982 local r = foo(a+1)
983 print("co-body", r)
984 local r, s = coroutine.yield(a+b, a-b)
985 print("co-body", r, s)
986 return b, "end"
987 end)
993 </pre><p>
994 When you run it, it produces the following output:
996 <pre>
997 co-body 1 10
998 foo 2
999 main true 4
1000 co-body r
1002 co-body x y
1003 main true 10 end
1004 main false cannot resume dead coroutine
1005 </pre>
1007 <p>
1008 You can also create and manipulate coroutines through the C API:
1009 see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
1018 <p>
1019 This section describes the lexis, the syntax, and the semantics of Lua.
1020 In other words,
1021 this section describes
1022 which tokens are valid,
1023 how they can be combined,
1024 and what their combinations mean.
1027 <p>
1028 Language constructs will be explained using the usual extended BNF notation,
1029 in which
1032 Non-terminals are shown like non-terminal,
1036 at the end of this manual.
1042 <p>
1043 Lua is a free-form language.
1044 It ignores spaces (including new lines) and comments
1045 between lexical elements (tokens),
1046 except as delimiters between names and keywords.
1049 <p>
1052 in Lua can be any string of letters,
1053 digits, and underscores,
1054 not beginning with a digit.
1055 Identifiers are used to name variables, table fields, and labels.
1058 <p>
1060 and cannot be used as names:
1063 <pre>
1064 and break do else elseif end
1065 false for function goto if in
1066 local nil not or repeat return
1067 then true until while
1068 </pre>
1070 <p>
1071 Lua is a case-sensitive language:
1073 are two different, valid names.
1074 As a convention,
1075 programs should avoid creating
1076 names that start with an underscore followed by
1080 <p>
1081 The following strings denote other tokens:
1083 <pre>
1084 + - * / % ^ #
1087 ( ) { } [ ] ::
1088 ; : , . .. ...
1089 </pre>
1091 <p>
1093 can be delimited by matching single or double quotes,
1094 and can contain the following C-like escape sequences:
1104 and '<code>\'</code>' (apostrophe [single quote]).
1105 A backslash followed by a real newline
1106 results in a newline in the string.
1107 The escape sequence '<code>\z</code>' skips the following span
1108 of white-space characters,
1109 including line breaks;
1110 it is particularly useful to break and indent a long literal string
1111 into multiple lines without adding the newlines and spaces
1112 into the string contents.
1115 <p>
1116 Strings in Lua can contain any 8-bit value, including embedded zeros,
1117 which can be specified as '<code>\0</code>'.
1118 More generally,
1119 we can specify any byte in a literal string by its numeric value.
1120 This can be done
1121 with the escape sequence <code>\x<em>XX</em></code>,
1122 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
1123 or with the escape sequence <code>\<em>ddd</em></code>,
1124 where <em>ddd</em> is a sequence of up to three decimal digits.
1125 (Note that if a decimal escape sequence is to be followed by a digit,
1126 it must be expressed using exactly three digits.)
1129 <p>
1130 The UTF-8 encoding of a Unicode character
1131 can be inserted in a literal string with
1132 the escape sequence <code>\u{<em>XXX</em>}</code>
1133 (note the mandatory enclosing brackets),
1134 where <em>XXX</em> is a sequence of one or more hexadecimal digits
1135 representing the character code point.
1138 <p>
1139 Literal strings can also be defined using a long format
1140 enclosed by <em>long brackets</em>.
1141 We define an <em>opening long bracket of level <em>n</em></em> as an opening
1142 square bracket followed by <em>n</em> equal signs followed by another
1143 opening square bracket.
1144 So, an opening long bracket of level 0 is written as <code>[[</code>,
1145 an opening long bracket of level 1 is written as <code>[=[</code>,
1146 and so on.
1147 A <em>closing long bracket</em> is defined similarly;
1148 for instance,
1149 a closing long bracket of level 4 is written as <code>]====]</code>.
1150 A <em>long literal</em> starts with an opening long bracket of any level and
1151 ends at the first closing long bracket of the same level.
1152 It can contain any text except a closing bracket of the same level.
1153 Literals in this bracketed form can run for several lines,
1154 do not interpret any escape sequences,
1155 and ignore long brackets of any other level.
1156 Any kind of end-of-line sequence
1157 (carriage return, newline, carriage return followed by newline,
1158 or newline followed by carriage return)
1159 is converted to a simple newline.
1162 <p>
1163 Any byte in a literal string not
1164 explicitly affected by the previous rules represents itself.
1165 However, Lua opens files for parsing in text mode,
1166 and the system file functions may have problems with
1167 some control characters.
1168 So, it is safer to represent
1169 non-text data as a quoted literal with
1170 explicit escape sequences for non-text characters.
1173 <p>
1174 For convenience,
1175 when the opening long bracket is immediately followed by a newline,
1176 the newline is not included in the string.
1177 As an example, in a system using ASCII
1178 (in which '<code>a</code>' is coded as 97,
1179 newline is coded as 10, and '<code>1</code>' is coded as 49),
1180 the five literal strings below denote the same string:
1182 <pre>
1183 a = 'alo\n123"'
1185 a = '\97lo\10\04923"'
1186 a = [[alo
1188 a = [==[
1189 alo
1190 123"]==]
1191 </pre>
1193 <p>
1195 can be written with an optional fractional part
1196 and an optional decimal exponent,
1198 Lua also accepts hexadecimal constants,
1200 Hexadecimal constants also accept an optional fractional part
1201 plus an optional binary exponent,
1203 A numeric constant with a fractional dot or an exponent
1204 denotes a float;
1205 otherwise it denotes an integer.
1206 Examples of valid integer constants are
1208 <pre>
1209 3 345 0xff 0xBEBADA
1210 </pre><p>
1211 Examples of valid float constants are
1213 <pre>
1216 </pre>
1218 <p>
1220 anywhere outside a string.
1223 which runs until the end of the line.
1225 which runs until the corresponding closing long bracket.
1226 Long comments are frequently used to disable code temporarily.
1234 <p>
1235 Variables are places that store values.
1236 There are three kinds of variables in Lua:
1237 global variables, local variables, and table fields.
1240 <p>
1241 A single name can denote a global variable or a local variable
1242 (or a function's formal parameter,
1243 which is a particular kind of local variable):
1245 <pre>
1246 var ::= Name
1247 </pre><p>
1251 <p>
1252 Any variable name is assumed to be global unless explicitly declared
1255 local variables can be freely accessed by functions
1259 <p>
1263 <p>
1264 Square brackets are used to index a table:
1266 <pre>
1268 </pre><p>
1269 The meaning of accesses to table fields can be changed via metatables.
1274 This function is not defined or callable in Lua.
1275 We use it here only for explanatory purposes.)
1278 <p>
1282 <pre>
1284 </pre>
1286 <p>
1289 Due to the way that chunks are compiled,
1298 <p>
1299 Lua supports an almost conventional set of statements,
1300 similar to those in Pascal or C.
1301 This set includes
1302 assignments, control structures, function calls,
1303 and variable declarations.
1309 <p>
1310 A block is a list of statements,
1311 which are executed sequentially:
1313 <pre>
1314 block ::= {stat}
1315 </pre><p>
1317 that allow you to separate statements with semicolons,
1318 start a block with a semicolon
1319 or write two semicolons in sequence:
1321 <pre>
1323 </pre>
1325 <p>
1326 Function calls and assignments
1327 can start with an open parenthesis.
1328 This possibility leads to an ambiguity in Lua's grammar.
1329 Consider the following fragment:
1331 <pre>
1332 a = b + c
1333 (print or io.write)('done')
1334 </pre><p>
1335 The grammar could see it in two ways:
1337 <pre>
1338 a = b + c(print or io.write)('done')
1340 a = b + c; (print or io.write)('done')
1341 </pre><p>
1342 The current parser always sees such constructions
1343 in the first way,
1344 interpreting the open parenthesis
1345 as the start of the arguments to a call.
1346 To avoid this ambiguity,
1347 it is a good practice to always precede with a semicolon
1348 statements that start with a parenthesis:
1350 <pre>
1351 ;(print or io.write)('done')
1352 </pre>
1354 <p>
1355 A block can be explicitly delimited to produce a single statement:
1357 <pre>
1359 </pre><p>
1360 Explicit blocks are useful
1361 to control the scope of variable declarations.
1362 Explicit blocks are also sometimes used to
1372 <p>
1374 Syntactically,
1375 a chunk is simply a block:
1377 <pre>
1378 chunk ::= block
1379 </pre>
1381 <p>
1382 Lua handles a chunk as the body of an anonymous function
1383 with a variable number of arguments
1385 As such, chunks can define local variables,
1386 receive arguments, and return values.
1387 Moreover, such anonymous function is compiled as in the
1388 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>).
1390 even if it does not use that variable.
1393 <p>
1394 A chunk can be stored in a file or in a string inside the host program.
1395 To execute a chunk,
1397 precompiling the chunk's code into instructions for a virtual machine,
1398 and then Lua executes the compiled code
1399 with an interpreter for the virtual machine.
1402 <p>
1403 Chunks can also be precompiled into binary form;
1404 see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
1405 Programs in source and compiled forms are interchangeable;
1406 Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
1414 <p>
1415 Lua allows multiple assignments.
1416 Therefore, the syntax for assignment
1417 defines a list of variables on the left side
1418 and a list of expressions on the right side.
1419 The elements in both lists are separated by commas:
1421 <pre>
1425 </pre><p>
1429 <p>
1430 Before the assignment,
1432 the list of variables.
1433 If there are more values than needed,
1434 the excess values are thrown away.
1435 If there are fewer values than needed,
1437 If the list of expressions ends with a function call,
1438 then all values returned by that call enter the list of values,
1439 before the adjustment
1443 <p>
1444 The assignment statement first evaluates all its expressions
1445 and only then the assignments are performed.
1446 Thus the code
1448 <pre>
1449 i = 3
1451 </pre><p>
1455 Similarly, the line
1457 <pre>
1458 x, y = y, x
1459 </pre><p>
1461 and
1463 <pre>
1464 x, y, z = y, z, x
1465 </pre><p>
1469 <p>
1470 The meaning of assignments to global variables
1471 and table fields can be changed via metatables.
1476 This function is not defined or callable in Lua.
1477 We use it here only for explanatory purposes.)
1480 <p>
1482 is equivalent to the assignment
1490 The control structures
1492 familiar syntax:
1497 <pre>
1500 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
1501 </pre><p>
1505 <p>
1506 The condition expression of a
1507 control structure can return any value.
1510 (in particular, the number 0 and the empty string are also true).
1513 <p>
1516 but only after the condition.
1517 So, the condition can refer to local variables
1518 declared inside the loop block.
1521 <p>
1523 For syntactical reasons,
1524 labels in Lua are considered statements too:
1528 <pre>
1530 stat ::= label
1532 </pre>
1534 <p>
1535 A label is visible in the entire block where it is defined,
1536 except
1537 inside nested blocks where a label with the same name is defined and
1538 inside nested functions.
1539 A goto may jump to any visible label as long as it does not
1540 enter into the scope of a local variable.
1543 <p>
1545 as they perform no actions.
1548 <p>
1551 skipping to the next statement after the loop:
1554 <pre>
1556 </pre><p>
1560 <p>
1562 from a function or a chunk
1563 (which is an anonymous function).
1565 Functions can return more than one value,
1568 <pre>
1570 </pre>
1572 <p>
1574 as the last statement of a block.
1576 then an explicit inner block can be used,
1586 <p>
1589 one numerical and one generic.
1592 <p>
1594 control variable runs through an arithmetic progression.
1595 It has the following syntax:
1597 <pre>
1598 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b>
1599 </pre><p>
1605 <pre>
1607 </pre><p>
1608 is equivalent to the code:
1610 <pre>
1611 do
1612 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
1615 while true do
1617 if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then
1618 break
1619 end
1622 end
1623 end
1624 </pre>
1626 <p>
1627 Note the following:
1629 <ul>
1631 <li>
1632 All three control expressions are evaluated only once,
1633 before the loop starts.
1634 They must all result in numbers.
1635 </li>
1637 <li>
1638 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
1639 The names shown here are for explanatory purposes only.
1640 </li>
1642 <li>
1643 If the third expression (the step) is absent,
1645 </li>
1647 <li>
1649 </li>
1651 <li>
1653 If you need its value after the loop,
1654 assign it to another variable before exiting the loop.
1655 </li>
1657 </ul>
1659 <p>
1662 On each iteration, the iterator function is called to produce a new value,
1666 <pre>
1669 </pre><p>
1672 <pre>
1673 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end
1674 </pre><p>
1675 is equivalent to the code:
1677 <pre>
1678 do
1680 while true do
1681 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
1685 end
1686 end
1687 </pre><p>
1688 Note the following:
1690 <ul>
1692 <li>
1697 </li>
1699 <li>
1700 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
1701 The names are here for explanatory purposes only.
1702 </li>
1704 <li>
1706 </li>
1708 <li>
1711 If you need these values,
1712 then assign them to other variables before breaking or exiting the loop.
1713 </li>
1715 </ul>
1721 To allow possible side-effects,
1722 function calls can be executed as statements:
1724 <pre>
1725 stat ::= functioncall
1726 </pre><p>
1727 In this case, all returned values are thrown away.
1735 Local variables can be declared anywhere inside a block.
1736 The declaration can include an initial assignment:
1738 <pre>
1740 </pre><p>
1741 If present, an initial assignment has the same semantics
1746 <p>
1748 and so local variables can be declared in a chunk outside any explicit block.
1751 <p>
1762 <p>
1763 The basic expressions in Lua are the following:
1765 <pre>
1766 exp ::= prefixexp
1768 exp ::= Numeral
1769 exp ::= LiteralString
1770 exp ::= functiondef
1771 exp ::= tableconstructor
1773 exp ::= exp binop exp
1774 exp ::= unop exp
1776 </pre>
1778 <p>
1784 Vararg expressions,
1786 directly inside a vararg function;
1790 <p>
1793 relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>),
1801 <p>
1802 Both function calls and vararg expressions can result in multiple values.
1804 then its return list is adjusted to zero elements,
1805 thus discarding all returned values.
1806 If an expression is used as the last (or the only) element
1807 of a list of expressions,
1808 then no adjustment is made
1809 (unless the expression is enclosed in parentheses).
1810 In all other contexts,
1811 Lua adjusts the result list to one element,
1812 either discarding all values except the first one
1816 <p>
1817 Here are some examples:
1819 <pre>
1820 f() -- adjusted to 0 results
1821 g(f(), x) -- f() is adjusted to 1 result
1822 g(x, f()) -- g gets x plus all results from f()
1823 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
1824 a,b = ... -- a gets the first vararg parameter, b gets
1825 -- the second (both a and b can get nil if there
1826 -- is no corresponding vararg parameter)
1828 a,b,c = x, f() -- f() is adjusted to 2 results
1829 a,b,c = f() -- f() is adjusted to 3 results
1830 return f() -- returns all results from f()
1831 return ... -- returns all received vararg parameters
1832 return x,y,f() -- returns x, y, and all results from f()
1833 {f()} -- creates a list with all results from f()
1834 {...} -- creates a list with all vararg parameters
1835 {f(), nil} -- f() is adjusted to 1 result
1836 </pre>
1838 <p>
1839 Any expression enclosed in parentheses always results in only one value.
1840 Thus,
1849 Lua supports the following arithmetic operators:
1851 <ul>
1860 </ul>
1862 <p>
1863 With the exception of exponentiation and float division,
1864 the arithmetic operators work as follows:
1865 If both operands are integers,
1866 the operation is performed over integers and the result is an integer.
1867 Otherwise, if both operands are numbers
1868 or strings that can be converted to
1870 then they are converted to floats,
1871 the operation is performed following the usual rules
1872 for floating-point arithmetic
1873 (usually the IEEE 754 standard),
1874 and the result is a float.
1877 <p>
1879 always convert their operands to floats
1880 and the result is always a float.
1882 so that it works for non-integer exponents too.
1885 <p>
1887 that rounds the quotient towards minus infinity,
1888 that is, the floor of the division of its operands.
1891 <p>
1892 Modulo is defined as the remainder of a division
1893 that rounds the quotient towards minus infinity (floor division).
1896 <p>
1897 In case of overflows in integer arithmetic,
1899 according to the usual rules of two-complement arithmetic.
1900 (In other words,
1901 they return the unique representable integer
1907 Lua supports the following bitwise operators:
1909 <ul>
1916 </ul>
1918 <p>
1919 All bitwise operations convert its operands to integers
1921 operate on all bits of those integers,
1922 and result in an integer.
1925 <p>
1926 Both right and left shifts fill the vacant bits with zeros.
1927 Negative displacements shift to the other direction;
1928 displacements with absolute values equal to or higher than
1929 the number of bits in an integer
1930 result in zero (as all bits are shifted out).
1937 Lua provides some automatic conversions between some
1938 types and representations at run time.
1939 Bitwise operators always convert float operands to integers.
1940 Exponentiation and float division
1941 always convert integer operands to floats.
1942 All other arithmetic operations applied to mixed numbers
1943 (integers and floats) convert the integer operand to a float;
1945 The C API also converts both integers to floats and
1946 floats to integers, as needed.
1947 Moreover, string concatenation accepts numbers as arguments,
1948 besides strings.
1951 <p>
1952 Lua also converts strings to numbers,
1953 whenever a number is expected.
1956 <p>
1957 In a conversion from integer to float,
1958 if the integer value has an exact representation as a float,
1959 that is the result.
1960 Otherwise,
1961 the conversion gets the nearest higher or
1962 the nearest lower representable value.
1963 This kind of conversion never fails.
1966 <p>
1967 The conversion from float to integer
1968 checks whether the float has an exact representation as an integer
1969 (that is, the float has an integral value and
1970 it is in the range of integer representation).
1971 If it does, that representation is the result.
1972 Otherwise, the conversion fails.
1975 <p>
1976 The conversion from strings to numbers goes as follows:
1977 First, the string is converted to an integer or a float,
1978 following its syntax and the rules of the Lua lexer.
1979 (The string may have also leading and trailing spaces and a sign.)
1980 Then, the resulting number (float or integer)
1981 is converted to the type (float or integer) required by the context
1982 (e.g., the operation that forced the conversion).
1985 <p>
1986 The conversion from numbers to strings uses a
1987 non-specified human-readable format.
1988 For complete control over how numbers are converted to strings,
1997 Lua supports the following relational operators:
1999 <ul>
2006 </ul><p>
2010 <p>
2013 Otherwise, the values of the operands are compared.
2014 Strings are compared in the obvious way.
2015 Numbers are equal if they denote the same mathematical value.
2018 <p>
2019 Tables, userdata, and threads
2020 are compared by reference:
2021 two objects are considered equal only if they are the same object.
2022 Every time you create a new object
2023 (a table, userdata, or thread),
2024 this new object is different from any previously existing object.
2025 Closures with the same reference are always equal.
2026 Closures with any detectable difference
2027 (different behavior, different definition) are always different.
2030 <p>
2031 You can change the way that Lua compares tables and userdata
2035 <p>
2036 Equality comparisons do not convert strings to numbers
2037 or vice versa.
2040 entries in a table.
2043 <p>
2047 <p>
2048 The order operators work as follows.
2049 If both arguments are numbers,
2050 then they are compared according to their mathematical values
2051 (regardless of their subtypes).
2052 Otherwise, if both arguments are strings,
2053 then their values are compared according to the current locale.
2060 <p>
2061 Following the IEEE 754 standard,
2062 NaN is considered neither smaller than,
2063 nor equal to, nor greater than any value (including itself).
2070 The logical operators in Lua are
2074 and anything else as true.
2077 <p>
2086 that is,
2087 the second operand is evaluated only if necessary.
2088 Here are some examples:
2090 <pre>
2095 false and error() --> false
2096 false and nil --> false
2097 false or nil --> nil
2099 </pre><p>
2100 (In this manual,
2108 The string concatenation operator in Lua is
2110 If both operands are strings or numbers, then they are converted to
2120 <p>
2122 The length of a string is its number of bytes
2123 (that is, the usual meaning of string length when each
2124 character is one byte).
2127 <p>
2128 A program can modify the behavior of the length operator for
2129 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
2132 <p>
2136 that is,
2140 Note that a table like
2142 <pre>
2144 </pre><p>
2148 to the set of positive numeric keys of that table.)
2149 Note, however, that non-numeric keys do not interfere
2150 with whether a table is a sequence.
2157 Operator precedence in Lua follows the table below,
2158 from lower to higher priority:
2160 <pre>
2161 or
2162 and
2164 |
2165 ~
2166 &
2167 << >>
2168 ..
2169 + -
2170 * / // %
2171 unary operators (not # - ~)
2172 ^
2173 </pre><p>
2174 As usual,
2175 you can use parentheses to change the precedences of an expression.
2177 operators are right associative.
2178 All other binary operators are left associative.
2185 Table constructors are expressions that create tables.
2186 Every time a constructor is evaluated, a new table is created.
2187 A constructor can be used to create an empty table
2188 or to create a table and initialize some of its fields.
2189 The general syntax for constructors is
2191 <pre>
2193 fieldlist ::= field {fieldsep field} [fieldsep]
2194 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp
2196 </pre>
2198 <p>
2205 starting with 1.
2206 Fields in the other formats do not affect this counting.
2207 For example,
2209 <pre>
2211 </pre><p>
2212 is equivalent to
2214 <pre>
2215 do
2216 local t = {}
2217 t[f(1)] = g
2224 a = t
2225 end
2226 </pre>
2228 <p>
2229 The order of the assignments in a constructor is undefined.
2230 (This order would be relevant only when there are repeated keys.)
2233 <p>
2235 and the expression is a function call or a vararg expression,
2236 then all values returned by this expression enter the list consecutively
2240 <p>
2241 The field list can have an optional trailing separator,
2242 as a convenience for machine-generated code.
2249 A function call in Lua has the following syntax:
2251 <pre>
2252 functioncall ::= prefixexp args
2253 </pre><p>
2254 In a function call,
2255 first prefixexp and args are evaluated.
2257 then this function is called
2258 with the given arguments.
2259 Otherwise, the prefixexp "call" metamethod is called,
2260 having as first parameter the value of prefixexp,
2261 followed by the original call arguments
2265 <p>
2266 The form
2268 <pre>
2270 </pre><p>
2271 can be used to call "methods".
2277 <p>
2278 Arguments have the following syntax:
2280 <pre>
2282 args ::= tableconstructor
2283 args ::= LiteralString
2284 </pre><p>
2285 All argument expressions are evaluated before the call.
2288 that is, the argument list is a single new table.
2292 that is, the argument list is a single literal string.
2295 <p>
2300 in a tail call,
2301 the called function reuses the stack entry of the calling function.
2302 Therefore, there is no limit on the number of nested tail calls that
2303 a program can execute.
2304 However, a tail call erases any debug information about the
2305 calling function.
2306 Note that a tail call only happens with a particular syntax,
2308 this syntax makes the calling function return exactly
2309 the returns of the called function.
2310 So, none of the following examples are tail calls:
2312 <pre>
2313 return (f(x)) -- results adjusted to 1
2314 return 2 * f(x)
2315 return x, f(x) -- additional results
2316 f(x); return -- results discarded
2317 return x or f(x) -- results adjusted to 1
2318 </pre>
2325 <p>
2326 The syntax for function definition is
2328 <pre>
2331 </pre>
2333 <p>
2334 The following syntactic sugar simplifies function definitions:
2336 <pre>
2340 </pre><p>
2341 The statement
2343 <pre>
2345 </pre><p>
2346 translates to
2348 <pre>
2350 </pre><p>
2351 The statement
2353 <pre>
2355 </pre><p>
2356 translates to
2358 <pre>
2360 </pre><p>
2361 The statement
2363 <pre>
2365 </pre><p>
2366 translates to
2368 <pre>
2370 </pre><p>
2371 not to
2373 <pre>
2375 </pre><p>
2376 (This only makes a difference when the body of the function
2380 <p>
2381 A function definition is an executable expression,
2383 When Lua precompiles a chunk,
2384 all its function bodies are precompiled too.
2385 Then, whenever Lua executes the function definition,
2388 is the final value of the expression.
2391 <p>
2392 Parameters act as local variables that are
2393 initialized with the argument values:
2395 <pre>
2396 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’
2397 </pre><p>
2398 When a function is called,
2399 the list of arguments is adjusted to
2400 the length of the list of parameters,
2403 at the end of its parameter list.
2404 A vararg function does not adjust its argument list;
2405 instead, it collects all extra arguments and supplies them
2407 which is also written as three dots.
2408 The value of this expression is a list of all actual extra arguments,
2409 similar to a function with multiple results.
2410 If a vararg expression is used inside another expression
2411 or in the middle of a list of expressions,
2412 then its return list is adjusted to one element.
2413 If the expression is used as the last element of a list of expressions,
2414 then no adjustment is made
2415 (unless that last expression is enclosed in parentheses).
2418 <p>
2419 As an example, consider the following definitions:
2421 <pre>
2422 function f(a, b) end
2423 function g(a, b, ...) end
2425 </pre><p>
2426 Then, we have the following mapping from arguments to parameters and
2427 to the vararg expression:
2429 <pre>
2430 CALL PARAMETERS
2442 </pre>
2444 <p>
2446 If control reaches the end of a function
2448 then the function returns with no results.
2451 <p>
2453 There is a system-dependent limit on the number of values
2454 that a function may return.
2455 This limit is guaranteed to be larger than 1000.
2458 <p>
2462 Thus, the statement
2464 <pre>
2466 </pre><p>
2467 is syntactic sugar for
2469 <pre>
2471 </pre>
2480 <p>
2482 Lua is a lexically scoped language.
2483 The scope of a local variable begins at the first statement after
2484 its declaration and lasts until the last non-void statement
2485 of the innermost block that includes the declaration.
2486 Consider the following example:
2488 <pre>
2489 x = 10 -- global variable
2490 do -- new block
2491 local x = x -- new 'x', with value 10
2493 x = x+1
2494 do -- another block
2495 local x = x+1 -- another 'x'
2497 end
2499 end
2501 </pre>
2503 <p>
2509 <p>
2510 Because of the lexical scoping rules,
2511 local variables can be freely accessed by functions
2512 defined inside their scope.
2513 A local variable used by an inner function is called
2515 inside the inner function.
2518 <p>
2520 defines new local variables.
2521 Consider the following example:
2523 <pre>
2524 a = {}
2525 local x = 20
2527 local y = 0
2528 a[i] = function () y=y+1; return x+y end
2529 end
2530 </pre><p>
2531 The loop creates ten closures
2532 (that is, ten instances of the anonymous function).
2542 <p>
2544 This section describes the C API for Lua, that is,
2545 the set of C functions available to the host program to communicate
2546 with Lua.
2547 All API functions and related types and constants
2551 <p>
2552 Even when we use the term "function",
2553 any facility in the API may be provided as a macro instead.
2554 Except where stated otherwise,
2555 all such macros use each of their arguments exactly once
2556 (except for the first argument, which is always a Lua state),
2557 and so do not generate any hidden side-effects.
2560 <p>
2561 As in most C libraries,
2562 the Lua API functions do not check their arguments for validity or consistency.
2563 However, you can change this behavior by compiling Lua
2570 <p>
2572 Each element in this stack represents a Lua value
2576 <p>
2577 Whenever Lua calls C, the called function gets a new stack,
2578 which is independent of previous stacks and of stacks of
2579 C functions that are still active.
2580 This stack initially contains any arguments to the C function
2581 and it is where the C function pushes its results
2585 <p>
2586 For convenience,
2587 most query operations in the API do not follow a strict stack discipline.
2588 Instead, they can refer to any element in the stack
2590 A positive index represents an absolute stack position
2592 a negative index represents an offset relative to the top of the stack.
2595 (that is, the element that was pushed onto the stack first)
2596 and
2599 (that is, the element at the top)
2608 <p>
2609 When you interact with the Lua API,
2610 you are responsible for ensuring consistency.
2611 In particular,
2614 to ensure that the stack has enough space for pushing new elements.
2617 <p>
2618 Whenever Lua calls C,
2619 it ensures that the stack has space for
2622 so that usually you do not have to worry about stack space
2623 unless your code has loops pushing elements onto the stack.
2626 <p>
2627 When you call a Lua function
2629 Lua ensures that the stack has enough space for all results,
2630 but it does not ensure any extra space.
2631 So, before pushing anything in the stack after such a call
2640 <p>
2641 Any function in the API that receives stack indices
2645 <p>
2647 position that stores a modifiable Lua value.
2652 which represent some positions that are accessible to C code
2653 but that are not in the stack.
2658 <p>
2659 Functions that do not need a specific mutable position,
2660 but only a value (e.g., query functions),
2661 can be called with acceptable indices.
2663 but it also can be any positive index after the stack top
2664 within the space allocated for the stack,
2665 that is, indices up to the stack size.
2666 (Note that 0 is never an acceptable index.)
2667 Except when noted otherwise,
2668 functions in the API work with acceptable indices.
2671 <p>
2672 Acceptable indices serve to avoid extra tests
2673 against the stack top when querying the stack.
2674 For instance, a C function can query its third argument
2675 without the need to first check whether there is a third argument,
2676 that is, without the need to check whether 3 is a valid index.
2679 <p>
2680 For functions that can be called with acceptable indices,
2681 any non-valid index is treated as if it
2683 which behaves like a nil value.
2691 <p>
2692 When a C function is created,
2693 it is possible to associate some values with it,
2697 accessible to the function whenever it is called.
2700 <p>
2701 Whenever a C function is called,
2702 its upvalues are located at specific pseudo-indices.
2703 These pseudo-indices are produced by the macro
2705 The first upvalue associated with a function is at index
2709 current function (but not greater than 256),
2710 produces an acceptable but invalid index.
2718 <p>
2720 a predefined table that can be used by any C code to
2721 store whatever Lua values it needs to store.
2722 The registry table is always located at pseudo-index
2724 Any C library can store data into this table,
2725 but it must take care to choose keys
2726 that are different from those used
2727 by other libraries, to avoid collisions.
2728 Typically, you should use as key a string containing your library name,
2729 or a light userdata with the address of a C object in your code,
2730 or any Lua object created by your code.
2731 As with variable names,
2732 string keys starting with an underscore followed by
2733 uppercase letters are reserved for Lua.
2736 <p>
2737 The integer keys in the registry are used
2739 and by some predefined values.
2740 Therefore, integer keys must not be used for other purposes.
2743 <p>
2744 When you create a new Lua state,
2745 its registry comes with some predefined values.
2746 These predefined values are indexed with integer keys
2748 The following constants are defined:
2750 <ul>
2751 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
2752 the main thread of the state.
2753 (The main thread is the one created together with the state.)
2754 </li>
2756 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
2757 the global environment.
2758 </li>
2759 </ul>
2766 <p>
2768 (Lua will use exceptions if you compile it as C++;
2770 When Lua faces any error
2771 (such as a memory allocation error, type errors, syntax errors,
2772 and runtime errors)
2774 that is, it does a long jump.
2776 to set a recovery point;
2777 any error jumps to the most recent active recovery point.
2780 <p>
2781 If an error happens outside any protected environment,
2784 thus exiting the host application.
2785 Your panic function can avoid this exit by
2786 never returning
2787 (e.g., doing a long jump to your own recovery point outside Lua).
2790 <p>
2792 in particular, the error message is at the top of the stack.
2793 However, there is no guarantee about stack space.
2794 To push anything on the stack,
2798 <p>
2799 Most functions in the API can raise an error,
2800 for instance due to a memory allocation error.
2801 The documentation for each function indicates whether
2802 it can raise errors.
2805 <p>
2806 Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2814 <p>
2817 and this API function yields
2818 (directly or indirectly by calling another function that yields),
2823 <p>
2824 To avoid this kind of problem,
2825 Lua raises an error whenever it tries to yield across an API call,
2826 except for three functions:
2827 <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
2832 <p>
2833 We need to set some terminology to explain continuations.
2834 We have a C function called from Lua which we will call
2836 This original function then calls one of those three functions in the C API,
2838 that then yields the current thread.
2839 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
2840 or when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a>
2841 and the function called by them yields.)
2844 <p>
2845 Suppose the running thread yields while executing the callee function.
2846 After the thread resumes,
2847 it eventually will finish running the callee function.
2848 However,
2849 the callee function cannot return to the original function,
2850 because its frame in the C stack was destroyed by the yield.
2852 which was given as an argument to the callee function.
2853 As the name implies,
2854 the continuation function should continue the task
2855 of the original function.
2858 <p>
2859 As an illustration, consider the following function:
2861 <pre>
2862 int original_function (lua_State *L) {
2863 ... /* code 1 */
2864 status = lua_pcall(L, n, m, h); /* calls Lua */
2865 ... /* code 2 */
2866 }
2867 </pre><p>
2868 Now we want to allow
2870 First, we can rewrite our function like here:
2872 <pre>
2873 int k (lua_State *L, int status, lua_KContext ctx) {
2874 ... /* code 2 */
2875 }
2877 int original_function (lua_State *L) {
2878 ... /* code 1 */
2879 return k(L, lua_pcall(L, n, m, h), ctx);
2880 }
2881 </pre><p>
2882 In the above code,
2884 <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
2885 which should do all the work that the original function
2889 (errors or yielding),
2890 so we rewrite the code as here,
2891 replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
2893 <pre>
2894 int original_function (lua_State *L) {
2895 ... /* code 1 */
2896 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
2897 }
2898 </pre><p>
2899 Note the external, explicit call to the continuation:
2900 Lua will call the continuation only if needed, that is,
2901 in case of errors or resuming after a yield.
2902 If the called function returns normally without ever yielding,
2903 <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
2904 (Of course, instead of calling the continuation in that case,
2905 you can do the equivalent work directly inside the original function.)
2908 <p>
2909 Besides the Lua state,
2910 the continuation function has two other parameters:
2913 (Lua does not use this context value;
2914 it only passes this value from the original function to the
2915 continuation function.)
2917 the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
2918 except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
2920 For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
2921 the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
2922 (For these two functions,
2923 Lua will not call the continuation in case of errors,
2924 because they do not handle errors.)
2926 you should call the continuation function
2929 directly the continuation function,
2933 <p>
2934 Lua treats the continuation function as if it were the original function.
2935 The continuation function receives the same Lua stack
2936 from the original function,
2937 in the same state it would be if the callee function had returned.
2938 (For instance,
2940 removed from the stack and replaced by the results from the call.)
2941 It also has the same upvalues.
2942 Whatever it returns is handled by Lua as if it were the return
2943 of the original function.
2951 <p>
2952 Here we list all functions and types from the C API in
2953 alphabetical order.
2954 Each function has an indicator like this:
2958 <p>
2960 is how many elements the function pops from the stack.
2962 is how many elements the function pushes onto the stack.
2963 (Any function always pushes its results after popping its arguments.)
2966 depending on the situation;
2968 we cannot know how many elements the function pops/pushes
2969 by looking only at its arguments
2970 (e.g., they may depend on what is on the stack).
2972 tells whether the function may raise errors:
2983 <p>
2985 into an equivalent absolute index
2986 (that is, one that does not depend on the stack top).
2993 <pre>typedef void * (*lua_Alloc) (void *ud,
2994 void *ptr,
2995 size_t osize,
2996 size_t nsize);</pre>
2998 <p>
2999 The type of the memory-allocation function used by Lua states.
3000 The allocator function must provide a
3002 but not exactly the same.
3003 Its arguments are
3004 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
3007 is being allocated;
3011 <p>
3014 that is, the size given when it was allocated or reallocated.
3017 <p>
3021 <a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
3022 <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when)
3023 Lua is creating a new object of that type.
3025 Lua is allocating memory for something else.
3028 <p>
3029 Lua assumes the following behavior from the allocator function:
3032 <p>
3038 <p>
3042 if and only if it cannot fulfill the request.
3043 Lua assumes that the allocator never fails when
3047 <p>
3048 Here is a simple implementation for the allocator function.
3049 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
3051 <pre>
3052 static void *l_alloc (void *ud, void *ptr, size_t osize,
3053 size_t nsize) {
3054 (void)ud; (void)osize; /* not used */
3055 if (nsize == 0) {
3056 free(ptr);
3057 return NULL;
3058 }
3059 else
3060 return realloc(ptr, nsize);
3061 }
3062 </pre><p>
3063 Note that Standard C ensures
3067 (Although Standard C does not ensure this behavior,
3068 it seems to be a safe assumption.)
3078 <p>
3079 Performs an arithmetic or bitwise operation over the two values
3080 (or one, in the case of negations)
3081 at the top of the stack,
3082 with the value at the top being the second operand,
3083 pops these values, and pushes the result of the operation.
3084 The function follows the semantics of the corresponding Lua operator
3085 (that is, it may call metamethods).
3088 <p>
3091 <ul>
3093 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
3094 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
3095 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
3096 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
3097 <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
3098 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
3099 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
3100 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
3101 <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise negation (<code>~</code>)</li>
3102 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&</code>)</li>
3103 <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise or (<code>|</code>)</li>
3104 <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive or (<code>~</code>)</li>
3105 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li>
3106 <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li>
3108 </ul>
3117 <p>
3128 <p>
3129 Calls a function.
3132 <p>
3133 To call a function you must use the following protocol:
3134 first, the function to be called is pushed onto the stack;
3135 then, the arguments to the function are pushed
3136 in direct order;
3137 that is, the first argument is pushed first.
3140 All arguments and the function value are popped from the stack
3141 when the function is called.
3142 The function results are pushed onto the stack when the function returns.
3145 In this case, all results from the function are pushed.
3146 Lua takes care that the returned values fit into the stack space.
3147 The function results are pushed onto the stack in direct order
3148 (the first result is pushed first),
3149 so that after the call the last result is on the top of the stack.
3152 <p>
3153 Any error inside the called function is propagated upwards
3157 <p>
3158 The following example shows how the host program can do the
3159 equivalent to this Lua code:
3161 <pre>
3163 </pre><p>
3164 Here it is in C:
3166 <pre>
3167 lua_getglobal(L, "f"); /* function to be called */
3169 lua_getglobal(L, "t"); /* table to be indexed */
3171 lua_remove(L, -2); /* remove 't' from the stack */
3174 lua_setglobal(L, "a"); /* set global 'a' */
3175 </pre><p>
3177 at its end, the stack is back to its original configuration.
3178 This is considered good programming practice.
3186 <pre>void lua_callk (lua_State *L,
3187 int nargs,
3188 int nresults,
3189 lua_KContext ctx,
3190 lua_KFunction k);</pre>
3192 <p>
3203 <p>
3204 Type for C functions.
3207 <p>
3208 In order to communicate properly with Lua,
3209 a C function must use the following protocol,
3210 which defines the way parameters and results are passed:
3211 a C function receives its arguments from Lua in its stack
3212 in direct order (the first argument is pushed first).
3213 So, when the function starts,
3215 The first argument (if any) is at index 1
3217 To return values to Lua, a C function just pushes them onto the stack,
3218 in direct order (the first result is pushed first),
3219 and returns the number of results.
3220 Any other value in the stack below the results will be properly
3221 discarded by Lua.
3222 Like a Lua function, a C function called by Lua can also return
3223 many results.
3226 <p>
3227 As an example, the following function receives a variable number
3228 of numeric arguments and returns their average and their sum:
3230 <pre>
3231 static int foo (lua_State *L) {
3232 int n = lua_gettop(L); /* number of arguments */
3233 lua_Number sum = 0.0;
3234 int i;
3236 if (!lua_isnumber(L, i)) {
3237 lua_pushliteral(L, "incorrect argument");
3238 lua_error(L);
3239 }
3240 sum += lua_tonumber(L, i);
3241 }
3242 lua_pushnumber(L, sum/n); /* first result */
3243 lua_pushnumber(L, sum); /* second result */
3244 return 2; /* number of results */
3245 }
3246 </pre>
3255 <p>
3257 It returns false if it cannot fulfill the request,
3258 either because it would cause the stack
3259 to be larger than a fixed maximum size
3260 (typically at least several thousand elements) or
3261 because it cannot allocate memory for the extra space.
3262 This function never shrinks the stack;
3263 if the stack is already larger than the new size,
3264 it is left unchanged.
3274 <p>
3275 Destroys all objects in the given Lua state
3276 (calling the corresponding garbage-collection metamethods, if any)
3277 and frees all dynamic memory used by this state.
3278 On several platforms, you may not need to call this function,
3279 because all resources are naturally released when the host program ends.
3280 On the other hand, long-running programs that create multiple states,
3281 such as daemons or web servers,
3282 will probably need to close states as soon as they are not needed.
3292 <p>
3293 Compares two Lua values.
3296 following the semantics of the corresponding Lua operator
3297 (that is, it may call metamethods).
3302 <p>
3305 <ul>
3307 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
3308 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li>
3309 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li>
3311 </ul>
3320 <p>
3322 pops them, and leaves the result at the top.
3324 (that is, the function does nothing);
3326 Concatenation is performed following the usual semantics of Lua
3337 <p>
3340 replacing the value at that position.
3341 Values at other positions are not affected.
3351 <p>
3352 Creates a new empty table and pushes it onto the stack.
3354 will have as a sequence;
3356 the table will have.
3357 Lua may use these hints to preallocate memory for the new table.
3358 This pre-allocation is useful for performance when you know in advance
3359 how many elements the table will have.
3368 <pre>int lua_dump (lua_State *L,
3369 lua_Writer writer,
3370 void *data,
3371 int strip);</pre>
3373 <p>
3374 Dumps a function as a binary chunk.
3375 Receives a Lua function on the top of the stack
3376 and produces a binary chunk that,
3377 if loaded again,
3378 results in a function equivalent to the one dumped.
3379 As it produces parts of the chunk,
3380 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
3382 to write them.
3385 <p>
3387 the binary representation may not include all debug information
3388 about the function,
3389 to save space.
3392 <p>
3393 The value returned is the error code returned by the last
3394 call to the writer;
3398 <p>
3399 This function does not pop the Lua function from the stack.
3409 <p>
3410 Generates a Lua error,
3411 using the value at the top of the stack as the error object.
3412 This function does a long jump,
3413 and therefore never returns
3424 <p>
3425 Controls the garbage collector.
3428 <p>
3429 This function performs several tasks,
3432 <ul>
3435 stops the garbage collector.
3436 </li>
3439 restarts the garbage collector.
3440 </li>
3443 performs a full garbage-collection cycle.
3444 </li>
3447 returns the current amount of memory (in Kbytes) in use by Lua.
3448 </li>
3451 returns the remainder of dividing the current amount of bytes of
3452 memory in use by Lua by 1024.
3453 </li>
3456 performs an incremental step of garbage collection.
3457 </li>
3462 and returns the previous value of the pause.
3463 </li>
3468 and returns the previous value of the step multiplier.
3469 </li>
3472 returns a boolean that tells whether the collector is running
3473 (i.e., not stopped).
3474 </li>
3476 </ul>
3478 <p>
3479 For more details about these options,
3490 <p>
3491 Returns the memory-allocation function of a given state.
3493 opaque pointer given when the memory-allocator function was set.
3503 <p>
3506 As in Lua, this function may trigger a metamethod
3510 <p>
3511 Returns the type of the pushed value.
3521 <p>
3522 Returns a pointer to a raw memory area associated with the
3523 given Lua state.
3524 The application can use this area for any purpose;
3525 Lua does not use it for anything.
3528 <p>
3529 Each new thread has this area initialized with a copy
3530 of the area of the main thread.
3533 <p>
3534 By default, this area has the size of a pointer to void,
3535 but you can recompile Lua with a different size for this area.
3546 <p>
3548 Returns the type of that value.
3558 <p>
3561 As in Lua, this function may trigger a metamethod
3565 <p>
3566 Returns the type of the pushed value.
3576 <p>
3577 If the value at the given index has a metatable,
3579 Otherwise,
3590 <p>
3596 <p>
3597 This function pops the key from the stack,
3598 pushing the resulting value in its place.
3599 As in Lua, this function may trigger a metamethod
3603 <p>
3604 Returns the type of the pushed value.
3614 <p>
3615 Returns the index of the top element in the stack.
3617 this result is equal to the number of elements in the stack;
3628 <p>
3629 Pushes onto the stack the Lua value associated with the userdata
3630 at the given index.
3633 <p>
3634 Returns the type of the pushed value.
3644 <p>
3645 Moves the top element into the given valid index,
3646 shifting up the elements above this index to open space.
3647 This function cannot be called with a pseudo-index,
3648 because a pseudo-index is not an actual stack position.
3657 <p>
3658 The type of integers in Lua.
3661 <p>
3663 (usually a 64-bit two-complement integer),
3665 (usually a 32-bit two-complement integer).
3669 <p>
3670 Lua also defines the constants
3671 <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
3672 with the minimum and the maximum values that fit in this type.
3682 <p>
3683 Returns 1 if the value at the given index is a boolean,
3694 <p>
3706 <p>
3707 Returns 1 if the value at the given index is a function
3718 <p>
3719 Returns 1 if the value at the given index is an integer
3720 (that is, the value is a number and is represented as an integer),
3731 <p>
3732 Returns 1 if the value at the given index is a light userdata,
3743 <p>
3755 <p>
3756 Returns 1 if the given index is not valid,
3767 <p>
3768 Returns 1 if the given index is not valid
3780 <p>
3781 Returns 1 if the value at the given index is a number
3782 or a string convertible to a number,
3793 <p>
3794 Returns 1 if the value at the given index is a string
3795 or a number (which is always convertible to a string),
3806 <p>
3807 Returns 1 if the value at the given index is a table,
3818 <p>
3819 Returns 1 if the value at the given index is a thread,
3830 <p>
3831 Returns 1 if the value at the given index is a userdata
3842 <p>
3843 Returns 1 if the given coroutine can yield,
3853 <p>
3854 The type for continuation-function contexts.
3855 It must be a numeric type.
3858 so that it can store pointers too.
3868 <p>
3879 <p>
3880 Returns the length of the value at the given index.
3881 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and
3883 The result is pushed on the stack.
3891 <pre>int lua_load (lua_State *L,
3892 lua_Reader reader,
3893 void *data,
3894 const char *chunkname,
3895 const char *mode);</pre>
3897 <p>
3898 Loads a Lua chunk without running it.
3899 If there are no errors,
3901 function on top of the stack.
3902 Otherwise, it pushes an error message.
3905 <p>
3908 <ul>
3913 syntax error during precompilation;</li>
3916 memory allocation error;</li>
3920 (This error has no relation with the chunk being loaded.
3921 It is generated by the garbage collector.)
3922 </li>
3924 </ul>
3926 <p>
3932 <p>
3937 <p>
3941 with the addition that
3945 <p>
3947 so the reader function must always leave the stack
3948 unmodified when returning.
3951 <p>
3952 If the resulting function has upvalues,
3953 its first upvalue is set to the value of the global environment
3954 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>).
3955 When loading main chunks,
3967 <p>
3968 Creates a new thread running in a new, independent state.
3970 (due to lack of memory).
3972 Lua does all memory allocation for this state through this function.
3974 passes to the allocator in every call.
3984 <p>
3985 Creates a new empty table and pushes it onto the stack.
3996 <p>
3997 Creates a new thread, pushes it on the stack,
3998 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
3999 The new thread returned by this function shares with the original thread
4000 its global environment,
4001 but has an independent execution stack.
4004 <p>
4005 There is no explicit function to close or to destroy a thread.
4006 Threads are subject to garbage collection,
4007 like any Lua object.
4017 <p>
4018 This function allocates a new block of memory with the given size,
4019 pushes onto the stack a new full userdata with the block address,
4020 and returns this address.
4021 The host program can freely use this memory.
4031 <p>
4032 Pops a key from the stack,
4033 and pushes a key–value pair from the table at the given index
4034 (the "next" pair after the given key).
4035 If there are no more elements in the table,
4039 <p>
4040 A typical traversal looks like this:
4042 <pre>
4043 /* table is in the stack at index 't' */
4044 lua_pushnil(L); /* first key */
4045 while (lua_next(L, t) != 0) {
4047 printf("%s - %s\n",
4048 lua_typename(L, lua_type(L, -2)),
4049 lua_typename(L, lua_type(L, -1)));
4050 /* removes 'value'; keeps 'key' for next iteration */
4051 lua_pop(L, 1);
4052 }
4053 </pre>
4055 <p>
4056 While traversing a table,
4058 unless you know that the key is actually a string.
4060 the value at the given index;
4064 <p>
4066 the table during its traversal.
4075 <p>
4076 The type of floats in Lua.
4079 <p>
4080 By default this type is double,
4081 but that can be changed to a single float or a long double.
4091 <p>
4092 Converts a Lua float to a Lua integer.
4094 If that value is within the range of Lua integers,
4096 The macro results in a boolean indicating whether the
4097 conversion was successful.
4098 (Note that this range test can be tricky to do
4099 correctly without this macro,
4100 due to roundings.)
4103 <p>
4104 This macro may evaluate its arguments more than once.
4114 <p>
4115 Calls a function in protected mode.
4118 <p>
4121 If there are no errors during the call,
4122 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
4123 However, if there is any error,
4125 pushes a single value on the stack (the error message),
4126 and returns an error code.
4129 and its arguments from the stack.
4132 <p>
4134 then the error message returned on the stack
4135 is exactly the original error message.
4138 (This index cannot be a pseudo-index.)
4139 In case of runtime errors,
4140 this function will be called with the error message
4141 and its return value will be the message
4145 <p>
4146 Typically, the message handler is used to add more debug
4147 information to the error message, such as a stack traceback.
4148 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
4149 since by then the stack has unwound.
4152 <p>
4153 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
4156 <ul>
4159 success.</li>
4162 a runtime error.
4163 </li>
4166 memory allocation error.
4167 For such errors, Lua does not call the message handler.
4168 </li>
4171 error while running the message handler.
4172 </li>
4176 (This error typically has no relation with the function being called.)
4177 </li>
4179 </ul>
4186 <pre>int lua_pcallk (lua_State *L,
4187 int nargs,
4188 int nresults,
4189 int msgh,
4190 lua_KContext ctx,
4191 lua_KFunction k);</pre>
4193 <p>
4205 <p>
4216 <p>
4227 <p>
4228 Pushes a new C closure onto the stack.
4231 <p>
4232 When a C function is created,
4233 it is possible to associate some values with it,
4235 these values are then accessible to the function whenever it is called.
4236 To associate values with a C function,
4237 first these values must be pushed onto the stack
4238 (when there are multiple values, the first value is pushed first).
4240 is called to create and push the C function onto the stack,
4242 associated with the function.
4243 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
4246 <p>
4250 <p>
4253 which is just a pointer to the C function.
4254 In that case, it never raises a memory error.
4264 <p>
4265 Pushes a C function onto the stack.
4266 This function receives a pointer to a C function
4268 when called, invokes the corresponding C function.
4271 <p>
4272 Any function to be callable by Lua must
4273 follow the correct protocol to receive its parameters
4284 <p>
4285 Pushes onto the stack a formatted string
4286 and returns a pointer to this string.
4288 but has some important differences:
4290 <ul>
4292 <li>
4293 You do not have to allocate space for the result:
4294 the result is a Lua string and Lua takes care of memory allocation
4295 (and deallocation, through garbage collection).
4296 </li>
4298 <li>
4299 The conversion specifiers are quite restricted.
4300 There are no flags, widths, or precisions.
4301 The conversion specifiers can only be
4310 </li>
4312 </ul>
4321 <p>
4322 Pushes the global environment onto the stack.
4332 <p>
4343 <p>
4344 Pushes a light userdata onto the stack.
4347 <p>
4348 Userdata represent C values in Lua.
4350 It is a value (like a number):
4351 you do not create it, it has no individual metatable,
4352 and it is not collected (as it was never created).
4353 A light userdata is equal to "any"
4354 light userdata with the same C address.
4364 <p>
4376 <p>
4378 onto the stack.
4379 Lua makes (or reuses) an internal copy of the given string,
4381 the function returns.
4382 The string can contain any binary data,
4383 including embedded zeros.
4386 <p>
4387 Returns a pointer to the internal copy of the string.
4397 <p>
4398 Pushes a nil value onto the stack.
4408 <p>
4419 <p>
4421 onto the stack.
4422 Lua makes (or reuses) an internal copy of the given string,
4424 the function returns.
4427 <p>
4428 Returns a pointer to the internal copy of the string.
4431 <p>
4442 <p>
4444 Returns 1 if this thread is the main thread of its state.
4454 <p>
4455 Pushes a copy of the element at the given index
4456 onto the stack.
4464 <pre>const char *lua_pushvfstring (lua_State *L,
4465 const char *fmt,
4466 va_list argp);</pre>
4468 <p>
4469 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
4470 instead of a variable number of arguments.
4480 <p>
4483 (that is, without calling metamethods).
4495 <p>
4497 (i.e., without metamethods).
4507 <p>
4510 The access is raw;
4511 that is, it does not invoke metamethods.
4514 <p>
4515 Returns the type of the pushed value.
4525 <p>
4529 The access is raw;
4530 that is, it does not invoke metamethods.
4533 <p>
4534 Returns the type of the pushed value.
4544 <p>
4545 Returns the raw "length" of the value at the given index:
4546 for strings, this is the string length;
4548 with no metamethods;
4549 for userdata, this is the size of the block of memory allocated
4550 for the userdata;
4561 <p>
4563 (i.e., without metamethods).
4573 <p>
4579 <p>
4580 This function pops the value from the stack.
4581 The assignment is raw;
4582 that is, it does not invoke metamethods.
4592 <p>
4599 <p>
4600 This function pops the value from the stack.
4601 The assignment is raw;
4602 that is, it does not invoke metamethods.
4609 <pre>typedef const char * (*lua_Reader) (lua_State *L,
4610 void *data,
4611 size_t *size);</pre>
4613 <p>
4615 Every time it needs another piece of the chunk,
4618 The reader must return a pointer to a block of memory
4619 with a new piece of the chunk
4621 The block must exist until the reader function is called again.
4622 To signal the end of the chunk,
4624 The reader function may return pieces of any size greater than zero.
4634 <p>
4636 It is defined as a macro:
4638 <pre>
4639 #define lua_register(L,n,f) \
4640 (lua_pushcfunction(L, f), lua_setglobal(L, n))
4641 </pre>
4650 <p>
4651 Removes the element at the given valid index,
4652 shifting down the elements above this index to fill the gap.
4653 This function cannot be called with a pseudo-index,
4654 because a pseudo-index is not an actual stack position.
4664 <p>
4665 Moves the top element into the given valid index
4666 without shifting any element
4667 (therefore replacing the value at that given index),
4668 and then pops the top element.
4678 <p>
4682 <p>
4683 To start a coroutine,
4684 you push onto the thread stack the main function plus any arguments;
4687 This call returns when the coroutine suspends or finishes its execution.
4688 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
4689 or all values returned by the body function.
4693 without errors,
4697 <p>
4698 In case of errors,
4699 the stack is not unwound,
4700 so you can use the debug API over it.
4701 The error message is on the top of the stack.
4704 <p>
4705 To resume a coroutine,
4707 put on its stack only the values to
4712 <p>
4714 If there is no such coroutine,
4725 <p>
4727 and the top of the stack.
4733 of the slice being rotated.
4734 This function cannot be called with a pseudo-index,
4735 because a pseudo-index is not an actual stack position.
4745 <p>
4757 <p>
4763 <p>
4764 This function pops the value from the stack.
4765 As in Lua, this function may trigger a metamethod
4776 <p>
4777 Pops a value from the stack and
4788 <p>
4794 <p>
4795 This function pops the value from the stack.
4796 As in Lua, this function may trigger a metamethod
4807 <p>
4808 Pops a table from the stack and
4809 sets it as the new metatable for the value at the given index.
4819 <p>
4826 <p>
4827 This function pops both the key and the value from the stack.
4828 As in Lua, this function may trigger a metamethod
4839 <p>
4841 and sets the stack top to this index.
4842 If the new top is larger than the old one,
4854 <p>
4855 Pops a value from the stack and sets it as
4856 the new value associated to the userdata at the given index.
4865 <p>
4866 An opaque structure that points to a thread and indirectly
4867 (through the thread) to the whole state of a Lua interpreter.
4868 The Lua library is fully reentrant:
4869 it has no global variables.
4870 All information about a state is accessible through this structure.
4873 <p>
4874 A pointer to this structure must be passed as the first argument to
4875 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4876 which creates a Lua state from scratch.
4886 <p>
4890 <p>
4892 an error code if the thread finished the execution
4897 <p>
4898 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
4901 (to resume a coroutine).
4911 <p>
4913 pushes that number into the stack,
4914 and returns the total size of the string,
4915 that is, its length plus one.
4916 The conversion can result in an integer or a float,
4918 The string may have leading and trailing spaces and a sign.
4919 If the string is not a valid numeral,
4920 returns 0 and pushes nothing.
4921 (Note that the result can be used as a boolean,
4922 true if the conversion succeeds.)
4932 <p>
4933 Converts the Lua value at the given index to a C boolean
4935 Like all tests in Lua,
4938 otherwise it returns false.
4939 (If you want to accept only actual boolean values,
4950 <p>
4951 Converts a value at the given index to a C function.
4952 That value must be a C function;
4963 <p>
4964 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
4974 <p>
4975 Converts the Lua value at the given index
4977 The Lua value must be an integer,
4982 <p>
4984 its referent is assigned a boolean value that
4985 indicates whether the operation succeeded.
4995 <p>
4996 Converts the Lua value at the given index to a C string.
4999 The Lua value must be a string or a number;
5001 If the value is a number,
5008 <p>
5010 to a string inside the Lua state.
5012 after its last character (as in C),
5013 but can contain other zeros in its body.
5016 <p>
5017 Because Lua has garbage collection,
5019 will be valid after the corresponding Lua value is removed from the stack.
5029 <p>
5030 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5040 <p>
5041 Converts the Lua value at the given index
5042 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
5043 The Lua value must be a number or a string convertible to a number
5048 <p>
5050 its referent is assigned a boolean value that
5051 indicates whether the operation succeeded.
5061 <p>
5062 Converts the value at the given index to a generic
5064 The value can be a userdata, a table, a thread, or a function;
5066 Different objects will give different pointers.
5067 There is no way to convert the pointer back to its original value.
5070 <p>
5071 Typically this function is used only for hashing and debug information.
5081 <p>
5082 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
5092 <p>
5093 Converts the value at the given index to a Lua thread
5095 This value must be a thread;
5106 <p>
5107 If the value at the given index is a full userdata,
5108 returns its block address.
5109 If the value is a light userdata,
5110 returns its pointer.
5121 <p>
5122 Returns the type of the value in the given valid index,
5124 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
5134 and
5145 <p>
5156 <p>
5167 <p>
5179 <p>
5180 Returns the address of the version number stored in the Lua core.
5182 returns the address of the version used to create that state.
5184 returns the address of the version running the call.
5191 <pre>typedef int (*lua_Writer) (lua_State *L,
5192 const void* p,
5193 size_t sz,
5194 void* ud);</pre>
5196 <p>
5198 Every time it produces another piece of chunk,
5205 <p>
5206 The writer returns an error code:
5209 calling the writer again.
5219 <p>
5220 Exchange values between different threads of the same state.
5223 <p>
5235 <p>
5238 Therefore, when the thread resumes,
5239 it continues the function that called
5248 <pre>int lua_yieldk (lua_State *L,
5249 int nresults,
5250 lua_KContext ctx,
5251 lua_KFunction k);</pre>
5253 <p>
5254 Yields a coroutine (thread).
5257 <p>
5259 the running coroutine suspends its execution,
5260 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
5265 <p>
5266 When the coroutine is resumed again,
5269 This continuation function receives the same stack
5270 from the previous function,
5273 Moreover,
5278 <p>
5279 Usually, this function does not return;
5280 when the coroutine eventually resumes,
5281 it continues executing the continuation function.
5282 However, there is one special case,
5283 which is when this function is called
5287 and the hook should return immediately after the call.
5288 Lua will yield and,
5289 when the coroutine resumes again,
5290 it will continue the normal execution
5291 of the (Lua) function that triggered the hook.
5294 <p>
5295 This function can raise an error if it is called from a thread
5296 with a pending C call with no continuation function,
5297 or it is called from a thread that is not running inside a resume
5298 (e.g., the main thread).
5308 <p>
5309 Lua has no built-in debugging facilities.
5310 Instead, it offers a special interface
5312 This interface allows the construction of different
5313 kinds of debuggers, profilers, and other tools
5314 that need "inside information" from the interpreter.
5319 <pre>typedef struct lua_Debug {
5320 int event;
5321 const char *name; /* (n) */
5322 const char *namewhat; /* (n) */
5323 const char *what; /* (S) */
5324 const char *source; /* (S) */
5325 int currentline; /* (l) */
5326 int linedefined; /* (S) */
5327 int lastlinedefined; /* (S) */
5328 unsigned char nups; /* (u) number of upvalues */
5329 unsigned char nparams; /* (u) number of parameters */
5330 char isvararg; /* (u) */
5331 char istailcall; /* (t) */
5332 char short_src[LUA_IDSIZE]; /* (S) */
5333 /* private part */
5335 } lua_Debug;</pre>
5337 <p>
5338 A structure used to carry different pieces of
5339 information about a function or an activation record.
5341 of this structure, for later use.
5342 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
5346 <p>
5349 <ul>
5352 the name of the chunk that created the function.
5354 it means that the function was defined in a file where
5357 the remainder of its contents describe the source in a user-dependent manner.
5358 Otherwise,
5359 the function was defined in a string where
5361 </li>
5365 </li>
5368 the line number where the definition of the function starts.
5369 </li>
5372 the line number where the definition of the function ends.
5373 </li>
5379 </li>
5382 the current line where the given function is executing.
5383 When no line information is available,
5385 </li>
5388 a reasonable name for the given function.
5389 Because functions in Lua are first-class values,
5390 they do not have a fixed name:
5391 some functions can be the value of multiple global variables,
5392 while others can be stored only in a table field.
5394 called to find a suitable name.
5395 If it cannot find a name,
5397 </li>
5404 according to how the function was called.
5405 (Lua uses the empty string when no other option seems to apply.)
5406 </li>
5409 true if this function invocation was called by a tail call.
5410 In this case, the caller of this level is not in the stack.
5411 </li>
5414 the number of upvalues of the function.
5415 </li>
5418 the number of fixed parameters of the function
5420 </li>
5423 true if the function is a vararg function
5424 (always true for C functions).
5425 </li>
5427 </ul>
5436 <p>
5437 Returns the current hook function.
5447 <p>
5448 Returns the current hook count.
5458 <p>
5459 Returns the current hook mask.
5469 <p>
5470 Gets information about a specific function or function invocation.
5473 <p>
5474 To get information about a function invocation,
5480 <p>
5481 To get information about a function you push it onto the stack
5483 (In that case,
5486 you can write the following code:
5488 <pre>
5489 lua_Debug ar;
5490 lua_getglobal(L, "f"); /* get global 'f' */
5492 printf("%d\n", ar.linedefined);
5493 </pre>
5495 <p>
5498 a value to be pushed on the stack:
5500 <ul>
5503 </li>
5508 </li>
5511 </li>
5514 </li>
5518 </li>
5521 pushes onto the stack the function that is
5522 running at the given level;
5523 </li>
5526 pushes onto the stack a table whose indices are the
5527 numbers of the lines that are valid on the function.
5529 that is, a line where you can put a break point.
5530 Non-valid lines include empty lines and comments.)
5533 <p>
5535 its table is pushed after the function.
5536 </li>
5538 </ul>
5540 <p>
5541 This function returns 0 on error
5552 <p>
5553 Gets information about a local variable of
5554 a given activation record or a given function.
5557 <p>
5558 In the first case,
5563 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
5564 and names.
5567 <p>
5568 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
5569 and returns its name.
5572 <p>
5574 to be inspected must be at the top of the stack.
5575 In this case, only parameters of Lua functions are visible
5576 (as there is no information about what variables are active)
5577 and no values are pushed onto the stack.
5580 <p>
5582 when the index is greater than
5583 the number of active local variables.
5593 <p>
5594 Gets information about the interpreter runtime stack.
5597 <p>
5600 of the function executing at a given level.
5603 (except for tail calls, which do not count on the stack).
5605 when called with a level greater than the stack depth,
5606 it returns 0.
5616 <p>
5619 It pushes the upvalue's value onto the stack
5620 and returns its name.
5625 <p>
5627 as a name for all upvalues.
5628 (For Lua functions,
5629 upvalues are the external local variables that the function uses,
5630 and that are consequently included in its closure.)
5633 <p>
5634 Upvalues have no particular order,
5635 as they are active through the whole function.
5636 They are numbered in an arbitrary order.
5645 <p>
5646 Type for debugging hook functions.
5649 <p>
5652 Lua identifies these events with the following constants:
5653 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
5654 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
5661 <p>
5664 in this case, there will be no corresponding return event.
5667 <p>
5668 While Lua is running a hook, it disables other calls to hooks.
5669 Therefore, if a hook calls back Lua to execute a function or a chunk,
5670 this execution occurs without any calls to hooks.
5673 <p>
5674 Hook functions cannot have continuations,
5676 <a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>.
5679 <p>
5680 Hook functions can yield under the following conditions:
5681 Only count and line events can yield;
5682 to yield, a hook function must finish its execution
5683 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
5684 (that is, with no values).
5694 <p>
5695 Sets the debugging hook function.
5698 <p>
5701 it is formed by a bitwise or of the constants
5708 For each event, the hook is called as explained below:
5710 <ul>
5713 The hook is called just after Lua enters the new function,
5714 before the function gets its arguments.
5715 </li>
5718 The hook is called just before Lua leaves the function.
5719 There is no standard way to access the values
5720 to be returned by the function.
5721 </li>
5724 start the execution of a new line of code,
5725 or when it jumps back in the code (even to the same line).
5726 (This event only happens while Lua is executing a Lua function.)
5727 </li>
5731 (This event only happens while Lua is executing a Lua function.)
5732 </li>
5734 </ul>
5736 <p>
5747 <p>
5748 Sets the value of a local variable of a given activation record.
5749 It assigns the value at the top of the stack
5750 to the variable and returns its name.
5751 It also pops the value from the stack.
5754 <p>
5756 when the index is greater than
5757 the number of active local variables.
5760 <p>
5761 Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
5771 <p>
5772 Sets the value of a closure's upvalue.
5773 It assigns the value at the top of the stack
5774 to the upvalue and returns its name.
5775 It also pops the value from the stack.
5778 <p>
5783 <p>
5784 Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
5794 <p>
5799 <p>
5800 These unique identifiers allow a program to check whether different
5801 closures share upvalues.
5802 Lua closures that share an upvalue
5803 (that is, that access a same external local variable)
5804 will return identical ids for those upvalue indices.
5807 <p>
5808 Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
5817 <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
5818 int funcindex2, int n2);</pre>
5820 <p>
5832 <p>
5835 to interface C with Lua.
5836 While the basic API provides the primitive functions for all
5837 interactions between C and Lua,
5838 the auxiliary library provides higher-level functions for some
5839 common tasks.
5842 <p>
5843 All functions and types from the auxiliary library
5848 <p>
5849 All functions in the auxiliary library are built on
5850 top of the basic API,
5851 and so they provide nothing that cannot be done with that API.
5852 Nevertheless, the use of the auxiliary library ensures
5853 more consistency to your code.
5856 <p>
5857 Several functions in the auxiliary library use internally some
5858 extra stack slots.
5859 When a function in the auxiliary library uses less than five slots,
5860 it does not check the stack size;
5861 it simply assumes that there are enough slots.
5864 <p>
5865 Several functions in the auxiliary library are used to
5866 check C function arguments.
5867 Because the error message is formatted for arguments
5868 (e.g., "<code>bad argument #1</code>"),
5869 you should not use these functions for other stack values.
5872 <p>
5874 always raise an error if the check is not satisfied.
5880 <p>
5881 Here we list all functions and types from the auxiliary library
5882 in alphabetical order.
5890 <p>
5902 <p>
5906 The string can contain embedded zeros.
5916 <p>
5929 <p>
5942 <p>
5943 Adds the value at the top of the stack
5946 Pops the value.
5949 <p>
5950 This is the only function on string buffers that can (and must)
5951 be called with an extra element on the stack,
5952 which is the value to be added to the buffer.
5960 <pre>void luaL_argcheck (lua_State *L,
5961 int cond,
5962 int arg,
5963 const char *extramsg);</pre>
5965 <p>
5967 If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
5977 <p>
5979 of the C function that called it,
5980 using a standard message
5983 <pre>
5985 </pre><p>
5986 This function never returns.
5995 <p>
5999 <p>
6000 A string buffer allows C code to build Lua strings piecemeal.
6001 Its pattern of use is as follows:
6003 <ul>
6005 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6009 <li>
6010 Then add string pieces to the buffer calling any of
6012 </li>
6014 <li>
6016 This call leaves the final string on the top of the stack.
6017 </li>
6019 </ul>
6021 <p>
6022 If you know beforehand the total size of the resulting string,
6023 you can use the buffer like this:
6025 <ul>
6027 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6029 <li>Then initialize it and preallocate a space of
6034 <li>
6037 copied into that space.
6038 </li>
6040 </ul>
6042 <p>
6043 During its normal operation,
6044 a string buffer uses a variable number of stack slots.
6045 So, while using a buffer, you cannot assume that you know where
6046 the top of the stack is.
6047 You can use the stack between successive calls to buffer operations
6048 as long as that use is balanced;
6049 that is,
6050 when you call a buffer operation,
6051 the stack is at the same level
6052 it was immediately after the previous buffer operation.
6054 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
6055 level when the buffer was initialized,
6056 plus the final string on its top.
6066 <p>
6068 This function does not allocate any space;
6069 the buffer must be declared as a variable
6080 <p>
6081 Equivalent to the sequence
6082 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
6092 <p>
6093 Calls a metamethod.
6096 <p>
6099 this function calls this field passing the object as its only argument.
6100 In this case this function returns true and pushes onto the
6101 stack the value returned by the call.
6102 If there is no metatable or no metamethod,
6103 this function returns false (without pushing any value on the stack).
6113 <p>
6114 Checks whether the function has an argument
6125 <p>
6127 (or can be converted to an integer)
6138 <p>
6140 and returns this string;
6142 with the string's length.
6145 <p>
6147 so all conversions and caveats of that function apply here.
6157 <p>
6159 and returns this number.
6167 <pre>int luaL_checkoption (lua_State *L,
6168 int arg,
6169 const char *def,
6170 const char *const lst[]);</pre>
6172 <p>
6175 (which must be NULL-terminated).
6176 Returns the index in the array where the string was found.
6177 Raises an error if the argument is not a string or
6178 if the string cannot be found.
6181 <p>
6187 <p>
6188 This is a useful function for mapping strings to C enums.
6189 (The usual convention in Lua libraries is
6190 to use strings instead of numbers to select options.)
6200 <p>
6202 raising an error if the stack cannot grow to that size.
6214 <p>
6216 and returns this string.
6219 <p>
6221 so all conversions and caveats of that function apply here.
6231 <p>
6233 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
6243 <p>
6245 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
6256 <p>
6257 Checks whether the core running the call,
6258 the core that created the Lua state,
6259 and the code making the call are all using the same version of Lua.
6260 Also checks whether the core running the call
6261 and the core that created the Lua state
6262 are using the same address space.
6272 <p>
6273 Loads and runs the given file.
6274 It is defined as the following macro:
6276 <pre>
6278 </pre><p>
6279 It returns false if there are no errors
6280 or true in case of errors.
6290 <p>
6291 Loads and runs the given string.
6292 It is defined as the following macro:
6294 <pre>
6296 </pre><p>
6297 It returns false if there are no errors
6298 or true in case of errors.
6308 <p>
6309 Raises an error.
6311 plus any extra arguments,
6313 It also adds at the beginning of the message the file name and
6314 the line number where the error occurred,
6315 if this information is available.
6318 <p>
6319 This function never returns,
6320 but it is an idiom to use it in C functions
6331 <p>
6332 This function produces the return values for
6333 process-related functions in the standard library
6334 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
6344 <p>
6345 This function produces the return values for
6346 file-related functions in the standard library
6347 (<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.).
6357 <p>
6360 If the object does not have a metatable,
6361 or if the metatable does not have this field,
6372 <p>
6376 Returns the type of the pushed value.
6386 <p>
6389 is a table,
6390 and pushes that table onto the stack.
6391 Returns true if it finds a previous table there
6392 and false if it creates a new table.
6400 <pre>const char *luaL_gsub (lua_State *L,
6401 const char *s,
6402 const char *p,
6403 const char *r);</pre>
6405 <p>
6409 Pushes the resulting string on the stack and returns it.
6419 <p>
6420 Returns the "length" of the value at the given index
6421 as a number;
6422 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>).
6423 Raises an error if the result of the operation is not an integer.
6424 (This case only can happen through metamethods.)
6432 <pre>int luaL_loadbuffer (lua_State *L,
6433 const char *buff,
6434 size_t sz,
6435 const char *name);</pre>
6437 <p>
6438 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
6446 <pre>int luaL_loadbufferx (lua_State *L,
6447 const char *buff,
6448 size_t sz,
6449 const char *name,
6450 const char *mode);</pre>
6452 <p>
6453 Loads a buffer as a Lua chunk.
6458 <p>
6461 used for debug information and error messages.
6462 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6472 <p>
6473 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
6481 <pre>int luaL_loadfilex (lua_State *L, const char *filename,
6482 const char *mode);</pre>
6484 <p>
6485 Loads a file as a Lua chunk.
6489 then it loads from the standard input.
6493 <p>
6494 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6497 <p>
6500 if it cannot open/read the file or the file has a wrong mode.
6503 <p>
6505 it does not run it.
6515 <p>
6516 Loads a string as a Lua chunk.
6521 <p>
6525 <p>
6527 it does not run it.
6537 <p>
6538 Creates a new table and registers there
6542 <p>
6543 It is implemented as the following macro:
6545 <pre>
6546 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
6547 </pre><p>
6549 not a pointer to it.
6559 <p>
6560 Creates a new table with a size optimized
6562 (but does not actually store them).
6563 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
6567 <p>
6568 It is implemented as a macro.
6570 not a pointer to it.
6580 <p>
6582 returns 0.
6583 Otherwise,
6584 creates a new table to be used as a metatable for userdata,
6587 and returns 1.
6591 <p>
6592 In both cases pushes onto the stack the final value associated
6603 <p>
6604 Creates a new Lua state.
6608 an error message to the standard error output in case of fatal
6609 errors.
6612 <p>
6613 Returns the new state,
6624 <p>
6625 Opens all standard Lua libraries into the given state.
6633 <pre>lua_Integer luaL_optinteger (lua_State *L,
6634 int arg,
6635 lua_Integer d);</pre>
6637 <p>
6639 (or convertible to an integer),
6640 returns this integer.
6643 Otherwise, raises an error.
6651 <pre>const char *luaL_optlstring (lua_State *L,
6652 int arg,
6653 const char *d,
6654 size_t *l);</pre>
6656 <p>
6658 returns this string.
6661 Otherwise, raises an error.
6664 <p>
6676 <p>
6678 returns this number.
6681 Otherwise, raises an error.
6689 <pre>const char *luaL_optstring (lua_State *L,
6690 int arg,
6691 const char *d);</pre>
6693 <p>
6695 returns this string.
6698 Otherwise, raises an error.
6708 <p>
6720 <p>
6724 After copying the string into this space you must call
6725 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
6726 it to the buffer.
6736 <p>
6738 the top of the stack.
6748 <p>
6749 Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
6759 <p>
6762 for the object at the top of the stack (and pops the object).
6765 <p>
6766 A reference is a unique integer key.
6771 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
6774 <p>
6776 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
6785 <pre>typedef struct luaL_Reg {
6786 const char *name;
6787 lua_CFunction func;
6788 } luaL_Reg;</pre>
6790 <p>
6791 Type for arrays of functions to be registered by
6794 the function.
6804 <pre>void luaL_requiref (lua_State *L, const char *modname,
6805 lua_CFunction openf, int glb);</pre>
6807 <p>
6808 If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
6814 <p>
6819 <p>
6820 Leaves a copy of the module on the stack.
6830 <p>
6833 (below optional upvalues, see next).
6836 <p>
6839 which must be previously pushed on the stack
6840 on top of the library table.
6841 These values are popped from the stack after the registration.
6851 <p>
6852 Sets the metatable of the object at the top of the stack
6861 <pre>typedef struct luaL_Stream {
6862 FILE *f;
6863 lua_CFunction closef;
6864 } luaL_Stream;</pre>
6866 <p>
6867 The standard representation for file handles,
6868 which is used by the standard I/O library.
6871 <p>
6872 A file handle is implemented as a full userdata,
6875 The metatable is created by the I/O library
6879 <p>
6881 it can contain other data after this initial structure.
6885 that will be called to close the stream
6886 when the handle is closed or collected;
6887 this function receives the file handle as its sole argument and
6890 Once Lua calls this field,
6892 to signal that the handle is closed.
6902 <p>
6904 except that, when the test fails,
6915 <p>
6916 Converts any Lua value at the given index to a C string
6917 in a reasonable format.
6918 The resulting string is pushed onto the stack and also
6919 returned by the function.
6924 <p>
6927 with the value as argument,
6928 and uses the result of the call as its result.
6936 <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
6937 int level);</pre>
6939 <p>
6942 at the beginning of the traceback.
6944 to start the traceback.
6954 <p>
6955 Returns the name of the type of the value at the given index.
6965 <p>
6968 The entry is removed from the table,
6969 so that the referred object can be collected.
6973 <p>
6974 If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
6985 <p>
6986 Pushes onto the stack a string identifying the current position
6988 Typically this string has the following format:
6990 <pre>
6992 </pre><p>
6995 etc.
6998 <p>
6999 This function is used to build a prefix for error messages.
7009 <p>
7010 The standard Lua libraries provide useful functions
7011 that are implemented directly through the C API.
7012 Some of these functions provide essential services to the language
7013 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
7014 others provide access to "outside" services (e.g., I/O);
7015 and others could be implemented in Lua itself,
7016 but are quite useful or have critical performance requirements that
7020 <p>
7021 All libraries are implemented through the official C API
7022 and are provided as separate C modules.
7023 Currently, Lua has the following standard libraries:
7025 <ul>
7047 </ul><p>
7048 Except for the basic and the package libraries,
7049 each library provides all its functions as fields of a global table
7050 or as methods of its objects.
7053 <p>
7054 To have access to these libraries,
7055 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
7056 which opens all standard libraries.
7057 Alternatively,
7058 the host program can open them individually by using
7062 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
7076 <p>
7077 The basic library provides core functions to Lua.
7078 If you do not include this library in your application,
7079 you should check carefully whether you need to provide
7080 implementations for some of its facilities.
7083 <p>
7087 <p>
7090 otherwise, returns all its arguments.
7091 In case of error,
7093 when absent, it defaults to "<code>assertion failed!</code>"
7098 <p>
7102 <p>
7103 This function is a generic interface to the garbage collector.
7106 <ul>
7109 performs a full garbage-collection cycle.
7110 This is the default option.
7111 </li>
7114 stops automatic execution of the garbage collector.
7115 The collector will run only when explicitly invoked,
7116 until a call to restart it.
7117 </li>
7120 restarts automatic execution of the garbage collector.
7121 </li>
7124 returns the total memory in use by Lua in Kbytes.
7125 The value has a fractional part,
7126 so that it multiplied by 1024
7127 gives the exact number of bytes in use by Lua
7128 (except for overflows).
7129 </li>
7132 performs a garbage-collection step.
7134 With a zero value,
7135 the collector will perform one basic (indivisible) step.
7136 For non-zero values,
7137 the collector will perform as if that amount of memory
7138 (in KBytes) had been allocated by Lua.
7140 </li>
7146 </li>
7152 </li>
7155 returns a boolean that tells whether the collector is running
7156 (i.e., not stopped).
7157 </li>
7159 </ul>
7163 <p>
7165 Opens the named file and executes its contents as a Lua chunk.
7166 When called without arguments,
7168 Returns all values returned by the chunk.
7175 <p>
7177 Terminates the last protected function called
7182 <p>
7184 at the beginning of the message, if the message is a string.
7191 to the message.
7196 <p>
7198 A global variable (not a function) that
7200 Lua itself does not use this variable;
7201 changing its value does not affect any environment,
7202 nor vice versa.
7207 <p>
7211 <p>
7213 Otherwise,
7215 returns the associated value.
7216 Otherwise, returns the metatable of the given object.
7221 <p>
7225 <p>
7227 so that the construction
7229 <pre>
7231 </pre><p>
7232 will iterate over the key–value pairs
7234 up to the first nil value.
7239 <p>
7243 <p>
7244 Loads a chunk.
7247 <p>
7252 with previous results.
7256 <p>
7257 If there are no syntactic errors,
7258 returns the compiled chunk as a function;
7262 <p>
7263 If the resulting function has upvalues,
7265 if that parameter is given,
7266 or to the value of the global environment.
7268 (When you load a main chunk,
7269 the resulting function will always have exactly one upvalue,
7271 However,
7272 when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
7273 the resulting function can have an arbitrary number of upvalues.)
7274 All upvalues are fresh, that is,
7275 they are not shared with any other function.
7278 <p>
7281 When absent,
7283 or to "<code>=(load)</code>" otherwise.
7286 <p>
7288 (that is, a precompiled chunk).
7289 It may be the string "<code>b</code>" (only binary chunks),
7290 "<code>t</code>" (only text chunks),
7291 or "<code>bt</code>" (both binary and text).
7292 The default is "<code>bt</code>".
7295 <p>
7296 Lua does not check the consistency of binary chunks.
7297 Maliciously crafted binary chunks can crash
7298 the interpreter.
7303 <p>
7307 <p>
7310 or from the standard input,
7311 if no file name is given.
7316 <p>
7320 <p>
7321 Allows a program to traverse all fields of a table.
7322 Its first argument is a table and its second argument
7323 is an index in this table.
7325 and its associated value.
7328 and its associated value.
7329 When called with the last index,
7333 In particular,
7337 <p>
7338 The order in which the indices are enumerated is not specified,
7340 (To traverse a table in numerical order,
7344 <p>
7346 during the traversal,
7347 you assign any value to a non-existent field in the table.
7348 You may however modify existing fields.
7349 In particular, you may clear existing fields.
7354 <p>
7358 <p>
7361 results from the call.
7364 <p>
7365 Otherwise,
7366 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
7367 so that the construction
7369 <pre>
7371 </pre><p>
7375 <p>
7377 the table during its traversal.
7382 <p>
7386 <p>
7391 and returns a status code.
7392 Its first result is the status code (a boolean),
7393 which is true if the call succeeds without errors.
7395 after this first result.
7401 <p>
7403 Receives any number of arguments
7405 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
7407 but only as a quick way to show a value,
7408 for instance for debugging.
7409 For complete control over the output,
7410 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
7415 <p>
7418 without invoking any metamethod.
7419 Returns a boolean.
7424 <p>
7427 without invoking any metamethod.
7434 <p>
7437 which must be a table or a string,
7438 without invoking any metamethod.
7439 Returns an integer.
7444 <p>
7447 without invoking any metamethod.
7453 <p>
7459 <p>
7463 <p>
7466 a negative number indexes from the end (-1 is the last argument).
7473 <p>
7477 <p>
7478 Sets the metatable for the given table.
7479 (You cannot change the metatable of other types from Lua, only from C.)
7481 removes the metatable of the given table.
7483 raises an error.
7486 <p>
7492 <p>
7496 <p>
7499 If the argument is already a number or
7500 a string convertible to a number,
7505 <p>
7506 The conversion of strings can result in integers or floats,
7508 (The string may have leading and trailing spaces and a sign.)
7511 <p>
7514 an integer numeral in that base.
7525 <p>
7527 Receives a value of any type and
7528 converts it to a string in a human-readable format.
7529 (For complete control of how numbers are converted,
7533 <p>
7537 and uses the result of the call as its result.
7542 <p>
7544 Returns the type of its only argument, coded as a string.
7545 The possible results of this function are
7547 "<code>number</code>",
7548 "<code>string</code>",
7549 "<code>boolean</code>",
7550 "<code>table</code>",
7551 "<code>function</code>",
7552 "<code>thread</code>",
7553 and "<code>userdata</code>".
7558 <p>
7560 A global variable (not a function) that
7561 holds a string containing the current interpreter version.
7562 The current value of this variable is "<code>Lua 5.3</code>".
7567 <p>
7568 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3>
7571 <p>
7583 <p>
7584 This library comprises the operations to manipulate coroutines,
7589 <p>
7593 <p>
7596 Returns this new coroutine,
7602 <p>
7606 <p>
7607 Returns true when the running coroutine can yield.
7610 <p>
7611 A running coroutine is yieldable if it is not the main thread and
7612 it is not inside a non-yieldable C function.
7617 <p>
7618 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
7621 <p>
7623 The first time you resume a coroutine,
7624 it starts running its body.
7626 as the arguments to the body function.
7627 If the coroutine has yielded,
7630 as the results from the yield.
7633 <p>
7634 If the coroutine runs without any errors,
7636 (when the coroutine yields) or any values returned by the body function
7637 (when the coroutine terminates).
7638 If there is any error,
7644 <p>
7648 <p>
7649 Returns the running coroutine plus a boolean,
7650 true when the running coroutine is the main one.
7655 <p>
7659 <p>
7664 or if it has not started running yet;
7666 (that is, it has resumed another coroutine);
7668 or if it has stopped with an error.
7673 <p>
7677 <p>
7680 Returns a function that resumes the coroutine each time it is called.
7681 Any arguments passed to the function behave as the
7684 except the first boolean.
7685 In case of error, propagates the error.
7690 <p>
7691 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
7694 <p>
7695 Suspends the execution of the calling coroutine.
7706 <p>
7707 The package library provides basic
7708 facilities for loading modules in Lua.
7709 It exports one function directly in the global environment:
7714 <p>
7718 <p>
7719 Loads the given module.
7720 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
7727 <p>
7728 To find a loader,
7729 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
7730 By changing this sequence,
7732 The following explanation is based on the default configuration
7736 <p>
7738 If it has a value,
7739 this value (which must be a function) is the loader.
7742 If that also fails, it searches for a C loader using the
7744 If that also fails,
7745 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
7748 <p>
7749 Once a loader is found,
7752 (If the loader came from a file,
7753 this extra value is the file name.)
7754 If the loader returns any non-nil value,
7756 If the loader does not return a non-nil value and
7763 <p>
7764 If there is any error loading or running the module,
7765 or if it cannot find any loader for the module,
7771 <p>
7775 <p>
7776 A string describing some compile-time configurations for packages.
7777 This string is a sequence of lines:
7779 <ul>
7781 <li>The first line is the directory separator string.
7784 <li>The second line is the character that separates templates in a path.
7787 <li>The third line is the string that marks the
7788 substitution points in a template.
7791 <li>The fourth line is a string that, in a path in Windows,
7792 is replaced by the executable's directory.
7795 <li>The fifth line is a mark to ignore all text after it
7799 </ul>
7803 <p>
7807 <p>
7808 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
7811 <p>
7812 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
7821 <p>
7825 <p>
7827 modules are already loaded.
7833 <p>
7834 This variable is only a reference to the real table;
7835 assignments to this variable do not change the
7841 <p>
7842 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
7845 <p>
7849 <p>
7851 then it only links with the library,
7852 making the symbols exported by the library
7853 available to other dynamically linked libraries.
7854 Otherwise,
7856 and returns this function as a C function.
7857 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
7861 <p>
7862 This is a low-level function.
7863 It completely bypasses the package and module system.
7865 it does not perform any path searching and
7866 does not automatically adds extensions.
7868 including if necessary a path and an extension.
7870 (which may depend on the C compiler and linker used).
7873 <p>
7874 This function is not supported by Standard C.
7875 As such, it is only available on some platforms
7876 (Windows, Linux, Mac OS X, Solaris, BSD,
7882 <p>
7886 <p>
7890 <p>
7891 At start-up, Lua initializes this variable with
7892 the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
7895 if those environment variables are not defined.
7896 Any "<code>;;</code>" in the value of the environment variable
7897 is replaced by the default path.
7902 <p>
7906 <p>
7907 A table to store loaders for specific modules
7911 <p>
7912 This variable is only a reference to the real table;
7913 assignments to this variable do not change the
7919 <p>
7923 <p>
7924 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
7927 <p>
7929 When looking for a module,
7930 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
7931 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
7932 sole parameter.
7934 plus an extra value that will be passed to that loader,
7935 or a string explaining why it did not find that module
7939 <p>
7940 Lua initializes this table with four searcher functions.
7943 <p>
7944 The first searcher simply looks for a loader in the
7948 <p>
7949 The second searcher looks for a loader as a Lua library,
7951 The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
7954 <p>
7955 The third searcher looks for a loader as a C library,
7956 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7957 Again,
7958 the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
7959 For instance,
7960 if the C path is the string
7962 <pre>
7963 "./?.so;./?.dll;/usr/local/?/init.so"
7964 </pre><p>
7968 Once it finds a C library,
7969 this searcher first uses a dynamic link facility to link the
7970 application with the library.
7971 Then it tries to find a C function inside the library to
7972 be used as the loader.
7974 concatenated with a copy of the module name where each dot
7975 is replaced by an underscore.
7976 Moreover, if the module name has a hyphen,
7977 its suffix after (and including) the first hyphen is removed.
7982 <p>
7984 It searches the C path for a library for
7985 the root name of the given module.
7988 If found, it looks into it for an open function for
7989 the submodule;
7991 With this facility, a package can pack several C submodules
7992 into one single library,
7993 with each submodule keeping its original open function.
7996 <p>
7997 All searchers except the first one (preload) return as the extra value
7998 the file name where the module was found,
8000 The first searcher returns no extra value.
8005 <p>
8006 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
8009 <p>
8013 <p>
8014 A path is a string containing a sequence of
8016 For each template,
8017 the function replaces each interrogation mark (if any)
8020 (a dot, by default)
8022 (the system's directory separator, by default),
8023 and then tries to open the resulting file name.
8026 <p>
8027 For instance, if the path is the string
8029 <pre>
8030 "./?.lua;./?.lc;/usr/local/?/init.lua"
8031 </pre><p>
8033 will try to open the files
8038 <p>
8039 Returns the resulting name of the first file that it can
8040 open in read mode (after closing the file),
8042 (This error message lists all file names it tried to open.)
8052 <p>
8053 This library provides generic functions for string manipulation,
8054 such as finding and extracting substrings, and pattern matching.
8057 Indices are allowed to be negative and are interpreted as indexing backwards,
8058 from the end of the string.
8059 Thus, the last character is at position -1, and so on.
8062 <p>
8063 The string library provides all its functions inside the table
8065 It also sets a metatable for strings
8067 Therefore, you can use the string functions in object-oriented style.
8072 <p>
8073 The string library assumes one-byte character encodings.
8076 <p>
8082 These indices are corrected
8086 <p>
8087 Numeric codes are not necessarily portable across platforms.
8092 <p>
8094 Receives zero or more integers.
8095 Returns a string with length equal to the number of arguments,
8096 in which each character has the internal numeric code equal
8097 to its corresponding argument.
8100 <p>
8101 Numeric codes are not necessarily portable across platforms.
8106 <p>
8110 <p>
8111 Returns a string containing a binary representation
8113 of the given function,
8115 a copy of the function (but with new upvalues).
8117 the binary representation may not include all debug information
8118 about the function,
8119 to save space.
8122 <p>
8123 Functions with upvalues have only their number of upvalues saved.
8124 When (re)loaded,
8126 (You can use the debug library to serialize
8127 and reload the upvalues of a function
8128 in a way adequate to your needs.)
8133 <p>
8134 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
8137 <p>
8138 Looks for the first match of
8141 where this occurrence starts and ends;
8144 where to start the search;
8147 turns off the pattern matching facilities,
8148 so the function does a plain "find substring" operation,
8153 <p>
8154 If the pattern has captures,
8155 then in a successful match
8156 the captured values are also returned,
8157 after the two indices.
8162 <p>
8163 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
8166 <p>
8167 Returns a formatted version of its variable number of arguments
8168 following the description given in its first argument (which must be a string).
8170 The only differences are that the options/modifiers
8175 using escape sequences when necessary to ensure that
8176 it can safely be read back by the Lua interpreter.
8177 For instance, the call
8179 <pre>
8180 string.format('%q', 'a string with "quotes" and \n new line')
8181 </pre><p>
8182 may produce the string:
8184 <pre>
8186 new line"
8187 </pre>
8189 <p>
8190 Options
8195 expect an integer.
8198 if its argument is not a string,
8199 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
8202 <p>
8203 When Lua is compiled with a non-C99 compiler,
8205 do not support any modifier (flags, width, length).
8210 <p>
8212 Returns an iterator function that,
8213 each time it is called,
8217 then the whole match is produced in each call.
8220 <p>
8221 As an example, the following loop
8223 printing one per line:
8225 <pre>
8226 s = "hello world from Lua"
8227 for w in string.gmatch(s, "%a+") do
8228 print(w)
8229 end
8230 </pre><p>
8232 given string into a table:
8234 <pre>
8235 t = {}
8236 s = "from=world, to=Lua"
8237 for k, v in string.gmatch(s, "(%w+)=(%w+)") do
8238 t[k] = v
8239 end
8240 </pre>
8242 <p>
8244 work as an anchor, as this would prevent the iteration.
8249 <p>
8255 which can be a string, a table, or a function.
8257 the total number of matches that occurred.
8261 <p>
8271 <p>
8273 using the first capture as the key.
8276 <p>
8278 match occurs, with all captured substrings passed as arguments,
8279 in order.
8282 <p>
8283 In any case,
8284 if the pattern specifies no captures,
8285 then it behaves as if the whole pattern was inside a capture.
8288 <p>
8289 If the value returned by the table query or by the function call
8290 is a string or a number,
8291 then it is used as the replacement string;
8293 then there is no replacement
8294 (that is, the original match is kept in the string).
8297 <p>
8298 Here are some examples:
8300 <pre>
8314 return load(s)()
8315 end)
8321 </pre>
8325 <p>
8327 Receives a string and returns its length.
8329 Embedded zeros are counted,
8335 <p>
8337 Receives a string and returns a copy of this string with all
8338 uppercase letters changed to lowercase.
8339 All other characters are left unchanged.
8340 The definition of what an uppercase letter is depends on the current locale.
8345 <p>
8350 the captures from the pattern;
8353 then the whole match is returned.
8355 where to start the search;
8361 <p>
8362 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3>
8365 <p>
8367 packed (that is, serialized in binary form)
8373 <p>
8377 <p>
8378 Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
8379 with the given format.
8380 The format string cannot have the variable-length options
8386 <p>
8391 (that is, no separator).
8397 <p>
8404 <p>
8410 (which is the same as the string length).
8411 In particular,
8418 <p>
8419 If, after the translation of negative indices,
8421 it is corrected to 1.
8423 it is corrected to that length.
8424 If, after these corrections,
8426 the function returns the empty string.
8431 <p>
8435 <p>
8436 Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
8440 After the read values,
8446 <p>
8448 Receives a string and returns a copy of this string with all
8449 lowercase letters changed to uppercase.
8450 All other characters are left unchanged.
8451 The definition of what a lowercase letter is depends on the current locale.
8459 <p>
8460 Patterns in Lua are described by regular strings,
8461 which are interpreted as patterns by the pattern-matching functions
8466 This section describes the syntax and the meaning
8467 (that is, what they match) of these strings.
8473 The following combinations are allowed in describing a character class:
8475 <ul>
8481 </li>
8507 This is the standard way to escape the magic characters.
8508 Any non-alphanumeric character
8509 (including all punctuation characters, even the non-magical)
8511 when used to represent itself in a pattern.
8512 </li>
8515 represents the class which is the union of all
8517 A range of characters can be specified by
8518 separating the end characters of the range,
8524 represents all alphanumeric characters plus the underscore,
8530 <p>
8531 The interaction between ranges and classes is not defined.
8533 have no meaning.
8534 </li>
8539 </li>
8541 </ul><p>
8543 the corresponding uppercase letter represents the complement of the class.
8547 <p>
8548 The definitions of letter, space, and other character groups
8549 depend on the current locale.
8559 <ul>
8561 <li>
8562 a single character class,
8563 which matches any single character in the class;
8564 </li>
8566 <li>
8568 which matches zero or more repetitions of characters in the class.
8569 These repetition items will always match the longest possible sequence;
8570 </li>
8572 <li>
8574 which matches one or more repetitions of characters in the class.
8575 These repetition items will always match the longest possible sequence;
8576 </li>
8578 <li>
8580 which also matches zero or more repetitions of characters in the class.
8582 these repetition items will always match the shortest possible sequence;
8583 </li>
8585 <li>
8587 which matches zero or one occurrence of a character in the class.
8588 It always matches one occurrence if possible;
8589 </li>
8591 <li>
8594 (see below);
8595 </li>
8597 <li>
8601 This means that, if one reads the string from left to right,
8605 balanced parentheses.
8606 </li>
8608 <li>
8610 such item matches an empty string at any position such that
8614 The beginning and the end of the subject are handled as if
8616 </li>
8618 </ul>
8626 beginning of the subject string.
8628 end of the subject string.
8629 At other positions,
8637 A pattern can contain sub-patterns enclosed in parentheses;
8639 When a match succeeds, the substrings of the subject string
8641 Captures are numbered according to their left parentheses.
8649 <p>
8651 the current string position (a number).
8663 <p>
8665 <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
8666 is a format string,
8667 which describes the layout of the structure being created or read.
8670 <p>
8671 A format string is a sequence of conversion options.
8672 The conversion options are as follows:
8674 <ul>
8679 (default is native alignment)</li>
8690 (default is native size)</li>
8692 (default is native size)</li>
8704 (which is otherwise ignored)</li>
8706 </ul><p>
8707 (A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
8708 Except for padding, spaces, and configurations
8709 (options "<code>xX <=>!</code>"),
8710 each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
8714 <p>
8715 For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
8717 All integral options check overflows;
8718 <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
8719 <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
8722 <p>
8723 Any format string starts as if prefixed by "<code>!1=</code>",
8724 that is,
8725 with maximum alignment of 1 (no alignment)
8726 and native endianness.
8729 <p>
8730 Alignment works as follows:
8731 For each option,
8732 the format gets extra padding until the data starts
8733 at an offset that is a multiple of the minimum between the
8734 option size and the maximum alignment;
8735 this minimum must be a power of 2.
8737 option "<code>s</code>" follows the alignment of its starting integer.
8740 <p>
8752 <p>
8753 This library provides basic support for UTF-8 encoding.
8755 This library does not provide any support for Unicode other
8756 than the handling of the encoding.
8757 Any operation that needs the meaning of a character,
8758 such as character classification, is outside its scope.
8761 <p>
8762 Unless stated otherwise,
8763 all functions that expect a byte position as a parameter
8764 assume that the given position is either the start of a byte sequence
8765 or one plus the length of the subject string.
8766 As in the string library,
8767 negative indices count from the end of the string.
8770 <p>
8772 Receives zero or more integers,
8773 converts each one to its corresponding UTF-8 byte sequence
8774 and returns a string with the concatenation of all these sequences.
8779 <p>
8781 The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
8783 which matches exactly one UTF-8 byte sequence,
8784 assuming that the subject is a valid UTF-8 string.
8789 <p>
8793 <p>
8794 Returns values so that the construction
8796 <pre>
8798 </pre><p>
8801 of each character.
8802 It raises an error if it meets any invalid byte sequence.
8807 <p>
8812 It raises an error if it meets any invalid byte sequence.
8817 <p>
8822 If it finds any invalid byte sequence,
8823 returns a false value plus the position of the first invalid byte.
8828 <p>
8830 Returns the position (in bytes) where the encoding of the
8838 If the specified character is neither in the subject
8839 nor right after its end,
8843 <p>
8844 As a special case,
8849 <p>
8860 <p>
8861 This library provides generic functions for table manipulation.
8865 <p>
8866 Remember that, whenever an operation needs the length of a table,
8867 the table must be a proper sequence
8869 All functions ignore non-numeric keys
8870 in the tables given as arguments.
8873 <p>
8874 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
8877 <p>
8878 Given a list where all elements are strings or numbers,
8888 <p>
8892 <p>
8894 shifting up the elements
8903 <p>
8907 <p>
8909 This function performs the equivalent to the following
8910 multiple assignment:
8913 The destination range can overlap with the source range.
8914 The number of elements to be moved must fit in a Lua integer.
8919 <p>
8923 <p>
8925 and with a field "<code>n</code>" with the total number of parameters.
8926 Note that the resulting table may not be a sequence.
8931 <p>
8935 <p>
8937 returning the value of the removed element.
8939 it shifts down the elements
8947 <p>
8955 <p>
8959 <p>
8963 then it must be a function that receives two list elements
8964 and returns true when the first element must come
8965 before the second in the final order
8971 <p>
8972 The sort algorithm is not stable;
8973 that is, elements considered equal by the given order
8974 may have their relative positions changed by the sort.
8979 <p>
8983 <p>
8984 Returns the elements from the given list.
8985 This function is equivalent to
8987 <pre>
8989 </pre><p>
9000 <p>
9001 This library provides basic mathematical functions.
9002 It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
9003 Functions with the annotation "<code>integer/float</code>" give
9004 integer results for integer arguments
9005 and float results for float (or mixed) arguments.
9006 Rounding functions
9007 (<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>)
9008 return an integer when the result fits in the range of an integer,
9009 or a float otherwise.
9012 <p>
9016 <p>
9022 <p>
9026 <p>
9032 <p>
9036 <p>
9042 <p>
9046 <p>
9049 but uses the signs of both parameters to find the
9050 quadrant of the result.
9054 <p>
9062 <p>
9066 <p>
9072 <p>
9076 <p>
9082 <p>
9086 <p>
9092 <p>
9096 <p>
9103 <p>
9107 <p>
9113 <p>
9117 <p>
9119 that rounds the quotient towards zero. (integer/float)
9124 <p>
9128 <p>
9130 a value larger than any other numeric value.
9135 <p>
9139 <p>
9147 <p>
9151 <p>
9152 Returns the argument with the maximum value,
9158 <p>
9160 An integer with the maximum value for an integer.
9165 <p>
9169 <p>
9170 Returns the argument with the minimum value,
9176 <p>
9178 An integer with the minimum value for an integer.
9183 <p>
9187 <p>
9189 Its second result is always a float.
9194 <p>
9198 <p>
9204 <p>
9208 <p>
9214 <p>
9218 <p>
9219 When called without arguments,
9220 returns a pseudo-random float with uniform distribution
9229 <p>
9230 This function is an interface to the underling
9231 pseudo-random generator function provided by C.
9232 No guarantees can be given for its statistical properties.
9237 <p>
9241 <p>
9243 for the pseudo-random generator:
9244 equal seeds produce equal sequences of numbers.
9249 <p>
9253 <p>
9259 <p>
9263 <p>
9270 <p>
9274 <p>
9280 <p>
9284 <p>
9286 returns that integer.
9292 <p>
9296 <p>
9298 "<code>float</code>" if it is a float,
9304 <p>
9308 <p>
9309 Returns a boolean,
9311 they are compared as unsigned integers.
9321 <p>
9322 The I/O library provides two different styles for file manipulation.
9323 The first one uses implicit file handles;
9324 that is, there are operations to set a default input file and a
9325 default output file,
9326 and all input/output operations are over these default files.
9327 The second style uses explicit file handles.
9330 <p>
9331 When using implicit file handles,
9333 When using explicit file handles,
9335 and then all operations are supplied as methods of the file handle.
9338 <p>
9340 three predefined file handles with their usual meanings from C:
9341 <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>.
9342 The I/O library never closes these files.
9345 <p>
9346 Unless otherwise stated,
9348 (plus an error message as a second result and
9349 a system-dependent error code as a third result)
9351 On non-POSIX systems,
9352 the computation of the error message and error code
9353 in case of errors
9354 may be not thread safe,
9358 <p>
9362 <p>
9369 <p>
9373 <p>
9379 <p>
9383 <p>
9384 When called with a file name, it opens the named file (in text mode),
9385 and sets its handle as the default input file.
9386 When called with a file handle,
9387 it simply sets this file handle as the default input file.
9388 When called without parameters,
9389 it returns the current default input file.
9392 <p>
9393 In case of errors this function raises the error,
9394 instead of returning an error code.
9399 <p>
9400 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3>
9403 <p>
9404 Opens the given file name in read mode
9405 and returns an iterator function that
9407 When the iterator function detects the end of file,
9408 it returns no values (to finish the loop) and automatically closes the file.
9411 <p>
9414 that is, it iterates over the lines of the default input file.
9415 In this case it does not close the file when the loop ends.
9418 <p>
9419 In case of errors this function raises the error,
9420 instead of returning an error code.
9425 <p>
9429 <p>
9430 This function opens a file,
9432 It returns a new file handle,
9436 <p>
9439 <ul>
9446 writing is only allowed at the end of file.</li>
9447 </ul><p>
9449 which is needed in some systems to open the file in binary mode.
9454 <p>
9458 <p>
9459 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
9464 <p>
9468 <p>
9469 This function is system dependent and is not available
9470 on all platforms.
9473 <p>
9475 a file handle that you can use to read data from this program
9477 or to write data to this program
9483 <p>
9487 <p>
9493 <p>
9497 <p>
9498 Returns a handle for a temporary file.
9499 This file is opened in update mode
9500 and it is automatically removed when the program ends.
9505 <p>
9509 <p>
9518 <p>
9522 <p>
9528 <p>
9532 <p>
9534 Note that files are automatically closed when
9535 their handles are garbage collected,
9536 but that takes an unpredictable amount of time to happen.
9539 <p>
9547 <p>
9551 <p>
9557 <p>
9561 <p>
9562 Returns an iterator function that,
9563 each time it is called,
9564 reads the file according to the given formats.
9565 When no format is given,
9566 uses "<code>l</code>" as a default.
9567 As an example, the construction
9569 <pre>
9571 </pre><p>
9572 will iterate over all characters of the file,
9573 starting at the current position.
9574 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
9575 when the loop ends.
9578 <p>
9579 In case of errors this function raises the error,
9580 instead of returning an error code.
9585 <p>
9589 <p>
9591 according to the given formats, which specify what to read.
9592 For each format,
9593 the function returns a string or a number with the characters read,
9595 (In this latter case,
9596 the function does not read subsequent formats.)
9597 When called without formats,
9598 it uses a default format that reads the next line
9599 (see below).
9602 <p>
9603 The available formats are
9605 <ul>
9608 reads a numeral and returns it as a float or an integer,
9609 following the lexical conventions of Lua.
9610 (The numeral may have leading spaces and a sign.)
9611 This format always reads the longest input sequence that
9612 is a valid prefix for a numeral;
9613 if that prefix does not form a valid numeral
9616 </li>
9619 reads the whole file, starting at the current position.
9620 On end of file, it returns the empty string.
9621 </li>
9624 reads the next line skipping the end of line,
9626 This is the default format.
9627 </li>
9630 reads the next line keeping the end-of-line character (if present),
9632 </li>
9635 reads a string with up to this number of bytes,
9638 it reads nothing and returns an empty string,
9640 </li>
9642 </ul><p>
9648 <p>
9652 <p>
9653 Sets and gets the file position,
9654 measured from the beginning of the file,
9658 <ul>
9662 </ul><p>
9664 measured in bytes from the beginning of the file.
9666 plus a string describing the error.
9669 <p>
9673 file position, without changing it;
9675 beginning of the file (and returns 0);
9677 end of the file, and returns its size.
9682 <p>
9686 <p>
9687 Sets the buffering mode for an output file.
9688 There are three available modes:
9690 <ul>
9693 no buffering; the result of any output operation appears immediately.
9694 </li>
9697 full buffering; output operation is performed only
9698 when the buffer is full or when
9699 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
9700 </li>
9703 line buffering; output is buffered until a newline is output
9704 or there is any input from some special files
9705 (such as a terminal device).
9706 </li>
9708 </ul><p>
9710 specifies the size of the buffer, in bytes.
9711 The default is an appropriate size.
9716 <p>
9720 <p>
9722 The arguments must be strings or numbers.
9725 <p>
9737 <p>
9741 <p>
9745 <p>
9746 Returns an approximation of the amount in seconds of CPU time
9747 used by the program.
9752 <p>
9756 <p>
9757 Returns a string or a table containing date and time,
9761 <p>
9763 this is the time to be formatted
9764 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
9768 <p>
9770 then the date is formatted in Coordinated Universal Time.
9771 After this optional character,
9774 <code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31),
9779 This last field may be absent
9780 if the information is not available.
9783 <p>
9789 <p>
9790 When called without arguments,
9792 the host system and on the current locale
9796 <p>
9797 On non-POSIX systems,
9798 this function may be not thread safe
9799 because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>.
9804 <p>
9808 <p>
9809 Returns the difference, in seconds,
9812 In POSIX, Windows, and some other systems,
9818 <p>
9822 <p>
9826 if the command terminated successfully,
9828 After this first result
9829 the function returns a string plus a number,
9830 as follows:
9832 <ul>
9835 the command terminated normally;
9836 the following number is the exit status of the command.
9837 </li>
9840 the command was terminated by a signal;
9841 the following number is the signal that terminated the command.
9842 </li>
9844 </ul>
9846 <p>
9853 <p>
9857 <p>
9864 the returned status is this number.
9868 <p>
9870 closes the Lua state before exiting.
9875 <p>
9879 <p>
9886 <p>
9890 <p>
9891 Deletes the file (or empty directory, on POSIX systems)
9892 with the given name.
9894 plus a string describing the error and the error code.
9899 <p>
9903 <p>
9906 plus a string describing the error and the error code.
9911 <p>
9915 <p>
9916 Sets the current locale of the program.
9922 The function returns the name of the new locale,
9926 <p>
9928 the current locale is set to an implementation-defined native locale.
9930 the current locale is set to the standard C locale.
9933 <p>
9935 this function only returns the name of the current locale
9936 for the given category.
9939 <p>
9940 This function may be not thread safe
9946 <p>
9950 <p>
9951 Returns the current time when called without arguments,
9952 or a time representing the local date and time specified by the given table.
9954 and may have fields
9959 Other fields are ignored.
9960 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
9963 <p>
9964 The values in these fields do not need to be inside their valid ranges.
9966 it means -10 seconds from the time specified by the other fields;
9968 it means +1000 hours from the time specified by the other fields.
9971 <p>
9972 The returned value is a number, whose meaning depends on your system.
9973 In POSIX, Windows, and some other systems,
9974 this number counts the number
9975 of seconds since some given start time (the "epoch").
9976 In other systems, the meaning is not specified,
9978 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
9983 <p>
9987 <p>
9988 Returns a string with a file name that can
9989 be used for a temporary file.
9990 The file must be explicitly opened before its use
9991 and explicitly removed when no longer needed.
9994 <p>
9995 On POSIX systems,
9996 this function also creates a file with that name,
9997 to avoid security risks.
9998 (Someone else might create the file with wrong permissions
9999 in the time between getting the name and creating the file.)
10000 You still have to open the file to use it
10001 and to remove it (even if you do not use it).
10004 <p>
10005 When possible,
10007 which automatically removes the file when the program ends.
10017 <p>
10018 This library provides
10020 You should exert care when using this library.
10021 Several of its functions
10022 violate basic assumptions about Lua code
10023 (e.g., that variables local to a function
10024 cannot be accessed from outside;
10025 that userdata metatables cannot be changed by Lua code;
10026 that Lua programs do not crash)
10027 and therefore can compromise otherwise secure code.
10028 Moreover, some functions in this library may be slow.
10031 <p>
10032 All functions in this library are provided
10034 All functions that operate over a thread
10035 have an optional first argument which is the
10036 thread to operate over.
10037 The default is always the current thread.
10040 <p>
10044 <p>
10045 Enters an interactive mode with the user,
10046 running each string that the user enters.
10047 Using simple commands and other debug facilities,
10048 the user can inspect global and local variables,
10049 change their values, evaluate expressions, and so on.
10051 so that the caller continues its execution.
10054 <p>
10056 within any function and so have no direct access to local variables.
10061 <p>
10065 <p>
10066 Returns the current hook settings of the thread, as three values:
10067 the current hook function, the current hook mask,
10068 and the current hook count
10074 <p>
10075 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
10078 <p>
10079 Returns a table with information about a function.
10080 You can give the function directly
10083 of the given thread:
10086 (except for tail calls, which do not count on the stack);
10087 and so on.
10092 <p>
10093 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
10096 except the table of valid lines.
10097 If present,
10100 If present,
10103 valid lines.
10106 <p>
10108 a name for the current function,
10109 if a reasonable name can be found,
10111 returns a table with all available information
10117 <p>
10118 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
10121 <p>
10122 This function returns the name and the value of the local variable
10124 This function accesses not only explicit local variables,
10125 but also parameters, temporaries, etc.
10128 <p>
10130 following the order that they are declared in the code,
10131 counting only the variables that are active
10132 in the current scope of the function.
10133 Negative indices refer to vararg parameters;
10134 -1 is the first vararg parameter.
10136 and raises an error when called with a level out of range.
10137 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
10140 <p>
10142 represent variables with no known names
10143 (internal variables such as loop control variables,
10144 and variables from chunks saved without debug information).
10147 <p>
10154 <p>
10158 <p>
10165 <p>
10169 <p>
10175 <p>
10179 <p>
10180 This function returns the name and the value of the upvalue
10185 <p>
10187 represent variables with no known names
10188 (variables from chunks saved without debug information).
10193 <p>
10197 <p>
10205 <p>
10206 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
10209 <p>
10210 Sets the given function as a hook.
10212 when the hook will be called.
10213 The string mask may have any combination of the following characters,
10214 with the given meaning:
10216 <ul>
10219 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
10220 </ul><p>
10221 Moreover,
10226 <p>
10227 When called without arguments,
10231 <p>
10232 When the hook is called, its first parameter is a string
10233 describing the event that has triggered its call:
10237 For line events,
10238 the hook also gets the new line number as its second parameter.
10239 Inside a hook,
10241 the running function
10248 <p>
10249 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
10252 <p>
10256 variable with the given index,
10259 Otherwise, it returns the name of the local variable.
10262 <p>
10264 variable indices and names.
10269 <p>
10270 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
10273 <p>
10281 <p>
10285 <p>
10289 with the given index.
10290 Otherwise, it returns the name of the upvalue.
10295 <p>
10296 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
10299 <p>
10305 <p>
10311 <p>
10312 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
10315 <p>
10318 Otherwise,
10319 it returns a string with a traceback of the call stack.
10321 at the beginning of the traceback.
10323 to start the traceback
10329 <p>
10333 <p>
10334 Returns a unique identifier (as a light userdata)
10336 from the given function.
10339 <p>
10340 These unique identifiers allow a program to check whether different
10341 closures share upvalues.
10342 Lua closures that share an upvalue
10343 (that is, that access a same external local variable)
10344 will return identical ids for those upvalue indices.
10349 <p>
10350 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
10353 <p>
10365 <p>
10366 Although Lua has been designed as an extension language,
10367 to be embedded in a host C program,
10368 it is also frequently used as a standalone language.
10369 An interpreter for Lua as a standalone language,
10371 is provided with the standard distribution.
10372 The standalone interpreter includes
10373 all standard libraries, including the debug library.
10374 Its usage is:
10376 <pre>
10377 lua [options] [script [args]]
10378 </pre><p>
10379 The options are:
10381 <ul>
10388 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
10389 </ul><p>
10391 When called without arguments,
10397 <p>
10399 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
10401 before running any argument.
10407 <p>
10410 Lua also ignores
10412 setting the values of
10413 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
10417 <p>
10419 For instance, an invocation like
10421 <pre>
10422 $ lua -e'a=1' -e 'print(a)' script.lua
10423 </pre><p>
10429 <p>
10430 Before running any code,
10433 The script name goes to index 0,
10434 the first argument after the script name goes to index 1,
10435 and so on.
10436 Any arguments before the script name
10437 (that is, the interpreter name plus its options)
10438 go to negative indices.
10439 For instance, in the call
10441 <pre>
10442 $ lua -la b.lua t1 t2
10443 </pre><p>
10444 the table is like this:
10446 <pre>
10450 </pre><p>
10451 If there is no script in the call,
10452 the interpreter name goes to index 0,
10453 followed by the other arguments.
10454 For instance, the call
10456 <pre>
10457 $ lua -e "print(arg[1])"
10458 </pre><p>
10459 will print "<code>-e</code>".
10460 If there is a script,
10461 the script is called with parameters
10463 (Like all chunks in Lua,
10464 the script is compiled as a vararg function.)
10467 <p>
10468 In interactive mode,
10469 Lua repeatedly prompts and waits for a line.
10470 After reading a line,
10471 Lua first try to interpret the line as an expression.
10472 If it succeeds, it prints its value.
10473 Otherwise, it interprets the line as a statement.
10474 If you write an incomplete statement,
10475 the interpreter waits for its completion
10476 by issuing a different prompt.
10479 <p>
10480 In case of unprotected errors in the script,
10481 the interpreter reports the error to the standard error stream.
10482 If the error object is not a string but
10484 the interpreter calls this metamethod to produce the final message.
10485 Otherwise, the interpreter converts the error object to a string
10486 and adds a stack traceback to it.
10489 <p>
10490 When finishing normally,
10491 the interpreter closes its main Lua state
10493 The script can avoid this step by
10497 <p>
10498 To allow the use of Lua as a
10499 script interpreter in Unix systems,
10500 the standalone interpreter skips
10502 Therefore, Lua scripts can be made into executable programs
10504 as in
10506 <pre>
10507 #!/usr/local/bin/lua
10508 </pre><p>
10509 (Of course,
10510 the location of the Lua interpreter may be different in your machine.
10512 then
10514 <pre>
10515 #!/usr/bin/env lua
10516 </pre><p>
10517 is a more portable solution.)
10523 <p>
10524 Here we list the incompatibilities that you may find when moving a program
10526 You can avoid some incompatibilities by compiling Lua with
10528 However,
10529 all these compatibility options will be removed in the future.
10532 <p>
10533 Lua versions can always change the C API in ways that
10534 do not imply source-code changes in a program,
10535 such as the numeric values for constants
10536 or the implementation of functions as macros.
10537 Therefore,
10538 you should not assume that binaries are compatible between
10539 different Lua versions.
10540 Always recompile clients of the Lua API when
10541 using a new version.
10544 <p>
10545 Similarly, Lua versions can always change the internal representation
10546 of precompiled chunks;
10547 precompiled chunks are not compatible between different Lua versions.
10550 <p>
10551 The standard paths in the official distribution may
10552 change between versions.
10557 <ul>
10559 <li>
10561 introduction of an integer subtype for numbers.
10562 Although this change should not affect "normal" computations,
10563 some computations
10564 (mainly those that involve some kind of overflow)
10565 can give different results.
10568 <p>
10569 You can fix these differences by forcing a number to be a float
10573 (This recommendation is only for a quick fix
10574 for an occasional incompatibility;
10575 it is not a general guideline for good programming.
10576 For good programming,
10577 use floats where you need floats
10578 and integers where you need integers.)
10579 </li>
10581 <li>
10583 to the result if it looks like an integer.
10586 You should always use an explicit format
10587 when you need a specific format for numbers.
10590 <p>
10591 (Formally this is not an incompatibility,
10592 because Lua does not specify how numbers are formatted as strings,
10593 but some programs assumed a specific format.)
10594 </li>
10596 <li>
10597 The generational mode for the garbage collector was removed.
10599 </li>
10601 </ul>
10607 <ul>
10609 <li>
10611 It is easy to require a compatible external library or,
10612 better yet, to replace its functions with appropriate bitwise operations.
10616 </li>
10618 <li>
10619 The Table library now respects metamethods
10620 for setting and getting elements.
10621 </li>
10623 <li>
10626 </li>
10628 <li>
10629 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
10630 For compatibility, Lua will continue to accept (and ignore) this character.
10631 </li>
10633 <li>
10634 The following functions were deprecated in the mathematical library:
10635 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
10639 which now accepts one or two parameters;
10641 For the other operations,
10642 you can either use an external library or
10643 implement them in Lua.
10644 </li>
10646 <li>
10648 changed the way it handles versioned names.
10649 Now, the version should come after the module name
10650 (as is usual in most other tools).
10651 For compatibility, that searcher still tries the old format
10652 if it cannot find an open function according to the new style.
10654 but it did not document the change.)
10655 </li>
10657 <li>
10659 (You can compute that second result from the fractional part
10660 of the first result.)
10661 </li>
10663 </ul>
10671 <ul>
10673 <li>
10674 Continuation functions now receive as parameters what they needed
10677 Adapt your code accordingly.
10678 </li>
10680 <li>
10681 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
10682 Use 0 as the value of this parameter to get the old behavior.
10683 </li>
10685 <li>
10686 Functions to inject/project unsigned integers
10689 were deprecated.
10690 Use their signed equivalents with a type cast.
10691 </li>
10693 <li>
10694 Macros to project non-default integer types
10695 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
10696 were deprecated.
10697 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
10699 </li>
10701 </ul>
10708 <p>
10709 Here is the complete syntax of Lua in extended BNF.
10710 As usual in extended BNF,
10711 {A} means 0 or more As,
10712 and [A] means an optional A.
10714 for a description of the terminals
10715 Name, Numeral,
10721 <pre>
10723 chunk ::= block
10725 block ::= {stat} [retstat]
10729 functioncall |
10730 label |
10736 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
10737 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> |
10751 var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name
10757 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef |
10758 prefixexp | tableconstructor | exp binop exp | unop exp
10764 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString
10770 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’
10774 fieldlist ::= field {fieldsep field} [fieldsep]
10776 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp
10780 binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ |
10781 ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ |
10782 ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ |
10785 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’
10787 </pre>
10789 <p>
10799 Last update:
10801 </P>
10802 <!--
10803 Last change: revised for Lua 5.3.1
10804 -->
10806 </body></html>