~ubuntu-branches/ubuntu/precise/lua5.2/precise-security : revision 3

16

Lua 5.2 Reference Manual

17

</h1>

18

19

20

<EM>This is a beta version of Lua 5.2.

21

Some details may change in the final version.</EM>

22

<P>

23

24

19

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

25

20

<p>

26

21

<small>

38

33

39

34

<p>

40

35

41

36

42

37

43

38

44

39

51

46

facilities.

52

47

It also offers good support for object-oriented programming,

53

48

functional programming, and data-driven programming.

54

Lua is intended to be used as a powerful, light-weight

55

scripting language for any program that needs one.

49

Lua is intended to be used as a powerful, lightweight,

50

embeddable scripting language for any program that needs one.

56

51

Lua is implemented as a library, written in <em>clean C</em>,

57

52

the common subset of Standard C and C++.

58

53

86

81

For a discussion of the decisions behind the design of Lua,

87

82

see the technical papers available at Lua's web site.

88

83

For a detailed introduction to programming in Lua,

89

see Roberto's book, <em>Programming in Lua</em> (second edition).

84

see Roberto's book, <em>Programming in Lua</em>.

90

85

91

86

92

87

93

88

<h1>2 – <a name="2">Basic Concepts</a></h1>

94

89

95

90

<p>

96

This section describes some basic concepts of the language.

91

This section describes the basic concepts of the language.

97

92

98

93

99

94

148

143

<p>

149

144

The type <em>userdata</em> is provided to allow arbitrary C data to

150

145

be stored in Lua variables.

151

This type corresponds to a block of raw memory

152

and has no pre-defined operations in Lua,

146

A userdata value is a pointer to a block of raw memory.

147

There are two kinds of userdata:

148

full userdata, where the block of memory is managed by Lua,

149

and light userdata, where the block of memory is managed by the host.

150

Userdata has no predefined operations in Lua,

153

151

except assignment and identity test.

154

However, by using <em>metatables</em>,

155

the programmer can define operations for userdata values

152

By using <em>metatables</em>,

153

the programmer can define operations for full userdata values

156

154

(see <a href="#2.4">§2.4</a>).

157

155

Userdata values cannot be created or modified in Lua,

158

156

only through the C API.

200

198

201

199

<p>

202

200

Like indices,

203

the value of a table field can be of any type.

201

the values of table fields can be of any type.

204

202

In particular,

205

203

because functions are first-class values,

206

204

table fields can contain functions.

227

225

228

226

<p>

229

227

The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type

230

of a given value.

228

of a given value (see <a href="#6.1">§6.1</a>).

231

229

232

230

233

231

239

237

As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>,

240

238

any reference to a global name <code>var</code> is syntactically translated

241

239

to <code>_ENV.var</code>.

242

Moreover, every chunk is compiled in the scope of an external

243

variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>),

240

Moreover, every chunk is compiled in the scope of

241

an external local variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>),

244

242

so <code>_ENV</code> itself is never a global name in a chunk.

245

243

246

244

252

250

you can define new variables and parameters with that name.

253

251

Each reference to a global name uses the <code>_ENV</code> that is

254

252

visible at that point in the program,

255

following the usual visibility rules of Lua.

253

following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>).

256

254

257

255

258

256

<p>

259

Any table used as the value of <code>_ENV</code> is usually called

260

an <em>environment</em>.

257

Any table used as the value of <code>_ENV</code> is called an <em>environment</em>.

261

258

262

259

263

260

<p>

268

265

269

266

<p>

270

267

When Lua compiles a chunk,

271

it initializes the value of its <code>_ENV</code> variable

268

it initializes the value of its <code>_ENV</code> upvalue

272

269

with the global environment (see <a href="#pdf-load"><code>load</code></a>).

273

270

Therefore, by default,

274

271

global variables in Lua code refer to entries in the global environment.

275

Moreover, all standard libraries are loaded in the global environment,

272

Moreover, all standard libraries are loaded in the global environment

276

273

and several functions there operate on that environment.

277

You can use <a href="#pdf-load"><code>load</code></a> to load a chunk with a different environment.

274

You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>)

275

to load a chunk with a different environment.

278

276

(In C, you have to load the chunk and then change the value

279

277

of its first upvalue.)

280

278

325

323

326

324

<p>

327

325

When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>,

328

you may give an <em>message handler</em>

326

you may give a <em>message handler</em>

329

327

to be called in case of errors.

330

328

This function is called with the original error message

331

329

and returns a new error message.

389

387

<p>

390

388

A metatable controls how an object behaves in arithmetic operations,

391

389

order comparisons, concatenation, length operation, and indexing.

392

A metatable also can define a function to be called when a userdata

393

is garbage collected.

390

A metatable also can define a function to be called

391

when a userdata or a table is garbage collected.

394

392

When Lua performs one of these operations over a value,

395

393

it checks whether this value has a metatable with the corresponding event.

396

394

If so, the value associated with that key (the metamethod)

427

425

rawget(getmetatable(obj) or {}, event)

428

426

</pre><p>

429

427

430

That is, the access to a metamethod does not invoke other metamethods,

431

and the access to objects with no metatables does not fail

428

This means that the access to a metamethod does not invoke other metamethods,

429

and access to objects with no metatables does not fail

432

430

(it simply results in <b>nil</b>).

433

431

434

432

590

588

for equality.

591

589

A metamethod is selected only when both values

592

590

being compared have the same type

593

and the same metamethod for the selected operation.

591

and the same metamethod for the selected operation,

592

and the values are either tables or full userdata.

594

593

595

594

<pre>

596

function getequalhandler (op1, op2, event)

597

if type(op1) ~= type(op2) then return nil end

598

local mm1 = metatable(op1)[event]

599

local mm2 = metatable(op2)[event]

595

function getequalhandler (op1, op2)

596

if type(op1) ~= type(op2) or

597

(type(op1) ~= "table" and type(op1) ~= "userdata") then

598

return nil -- different values

599

end

600

local mm1 = metatable(op1).__eq

601

local mm2 = metatable(op2).__eq

600

602

if mm1 == mm2 then return mm1 else return nil end

601

603

end

602

604

</pre><p>

604

606

605

607

<pre>

606

608

function eq_event (op1, op2)

607

if type(op1) ~= type(op2) then -- different types?

608

return false -- different values

609

end

610

609

if op1 == op2 then -- primitive equal?

611

610

return true -- values are equal

612

611

end

613

612

-- try metamethod

614

local h = getequalhandler(op1, op2, "__eq")

613

local h = getequalhandler(op1, op2)

615

614

if h then

616

return (h(op1, op2))

615

return not not h(op1, op2)

617

616

else

618

617

return false

619

618

end

620

619

end

621

620

</pre><p>

621

Note that the result is always a boolean.

622

</li>

623

624

634

else

635

local h = getbinhandler(op1, op2, "__lt")

636

if h then

637

return (h(op1, op2))

637

return not not h(op1, op2)

638

else

639

error(···)

640

end

641

end

642

end

643

</pre><p>

644

Note that the result is always a boolean.

644

645

</li>

645

646

647

656

657

else

657

658

local h = getbinhandler(op1, op2, "__le")

658

659

if h then

659

return (h(op1, op2))

660

return not not h(op1, op2)

660

661

else

661

662

h = getbinhandler(op1, op2, "__lt")

662

663

if h then

671

672

Note that, in the absence of a "le" metamethod,

672

673

Lua tries the "lt", assuming that <code>a <= b</code> is

673

674

equivalent to <code>not (b < a)</code>.

675

676

677

<p>

678

As with the other comparison operators,

679

the result is always a boolean.

674

680

</li>

675

681

676

682

<li><b>"index": </b>

770

776

a <em>garbage collector</em> to collect all <em>dead objects</em>

771

777

(that is, objects that are no longer accessible from Lua).

772

778

All memory used by Lua is subject to automatic management:

773

tables, userdata, functions, threads, strings, etc.

779

strings, tables, userdata, functions, threads, internal structures, etc.

774

780

775

781

776

782

<p>

819

825

<p>

820

826

You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C

821

827

or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.

822

With these functions you can also control

828

You can also use these functions to control

823

829

the collector directly (e.g., stop and restart it).

824

830

825

831

832

<p>

833

As an experimental feature in Lua 5.2,

834

you can change the collector's operation mode

835

from incremental to <em>generational</em>.

836

A <em>generational collector</em> assumes that most objects die young,

837

and therefore it traverses only young (recently created) objects.

838

This behavior can reduce the time used by the collector,

839

but also increases memory usage (as old dead objects may accumulate).

840

To mitigate this second problem,

841

from time to time the generational collector performs a full collection.

842

Remember that this is an experimental feature;

843

you are welcome to try it,

844

but check your gains.

845

846

826

847

827

848

<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3>

828

849

879

900

880

901

881

902

<p>

882

Because the object being collected must still be used by the finalizer

883

and even <em>resurrected</em>

884

(e.g., stored by the finalizer in a global variable),

885

the object memory is freed only when it becomes completely inaccessible

886

(that is, in the next garbage-collection cycle unless it was resurrected).

903

Because the object being collected must still be used by the finalizer,

904

it (and other objects accessible only through it)

905

must be <em>resurrected</em> by Lua.

906

Usually, this resurrection is transient,

907

and the object memory is freed in the next garbage-collection cycle.

908

However, if the finalizer stores the object in some global place

909

(e.g., a global variable),

910

then there is a permanent resurrection.

911

In any case,

912

the object memory is freed only when it becomes completely inaccessible;

913

its finalizer will never be called twice.

887

914

888

915

889

916

927

954

928

955

929

956

<p>

930

After you use a table as a metatable,

931

you should not change the value of its <code>__mode</code> field.

932

Otherwise, the weak behavior of the tables controlled by this

933

metatable is undefined.

957

Any change in the weakness of a table may take effect only

958

at the next collect cycle.

959

In particular, if you change the weakness to a stronger mode,

960

Lua may still collect some items from that table

961

before the change takes effect.

934

962

935

963

936

964

<p>

937

965

Only objects that have an explicit construction

938

can be removed from weak tables.

939

Values, such as numbers and booleans,

966

are removed from weak tables.

967

Values, such as numbers and light C functions,

940

968

are not subject to garbage collection,

941

969

and therefore are not removed from weak tables

942

970

(unless its associated value is collected).

943

Lua treats strings and light C functions as non-object values.

971

Although strings are subject to garbage collection,

972

they do not have an explicit construction,

973

and therefore are not removed from weak tables.

944

974

945

975

946

976

<p>

947

Objects marked for finalization have a special behavior in weak tables.

948

When a marked object is a value in a weak table,

949

it is removed from the table before running its finalizer.

950

However, when it is a key,

951

it is removed from the table only after running its finalizer.

977

Resurrected objects

978

(that is, objects being finalized

979

and objects accessible only through objects being finalized)

980

have a special behavior in weak tables.

981

They are removed from weak values before running their finalizers,

982

but are removed from weak keys only in the next collection

983

after running their finalizers, when such objects are actually freed.

952

984

This behavior allows the finalizer to access properties

953

985

associated with the object through weak tables.

954

986

955

987

988

<p>

989

If a weak table is among the resurrected objects in a collection cycle,

990

it may not be properly cleared until the next cycle.

991

992

956

993

957

994

958

995

1060

1097

<pre>

1061

1098

co-body 1 10

1062

1099

foo 2

1063

1064

1100

main true 4

1065

1101

co-body r

1066

1102

main true 11 -9

1090

1126

1091

1127

1092

1128

<p>

1093

The language constructs will be explained using the usual extended BNF notation,

1129

Language constructs will be explained using the usual extended BNF notation,

1094

1130

in which

1095

1131

{<em>a</em>} means 0 or more <em>a</em>'s, and

1096

1132

[<em>a</em>] means an optional <em>a</em>.

1176

1212

1177

1213

1178

1214

<p>

1179

A character in a literal string can also be specified by its numerical value.

1215

A byte in a literal string can also be specified by its numerical value.

1180

1216

This can be done with the escape sequence <code>\x<em>XX</em></code>,

1181

1217

where <em>XX</em> is a sequence of exactly two hexadecimal digits,

1182

1218

or with the escape sequence <code>\<em>ddd</em></code>,

1407

1443

<p>

1408

1444

A chunk can be stored in a file or in a string inside the host program.

1409

1445

To execute a chunk,

1410

Lua first pre-compiles the chunk into instructions for a virtual machine,

1446

Lua first precompiles the chunk into instructions for a virtual machine,

1411

1447

and then it executes the compiled code

1412

1448

with an interpreter for the virtual machine.

1413

1449

1414

1450

1415

1451

<p>

1416

Chunks can also be pre-compiled into binary form;

1452

Chunks can also be precompiled into binary form;

1417

1453

see program <code>luac</code> for details.

1418

1454

Programs in source and compiled forms are interchangeable;

1419

1455

Lua automatically detects the file type and acts accordingly.

1555

1591

1556

1592

1557

1593

<p>

1558

Both labels and empty statements are called <em>void statements</em>,

1594

Labels and empty statements are called <em>void statements</em>,

1559

1595

as they perform no actions.

1560

1596

1561

1597

1806

1842

1807

1843

<p>

1808

1844

Both function calls and vararg expressions can result in multiple values.

1809

If an expression is used as a statement

1810

(only possible for function calls (see <a href="#3.3.6">§3.3.6</a>)),

1845

If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>),

1811

1846

then its return list is adjusted to zero elements,

1812

1847

thus discarding all returned values.

1813

1848

If an expression is used as the last (or the only) element

1814

1849

of a list of expressions,

1815

1850

then no adjustment is made

1816

(unless the call is enclosed in parentheses).

1851

(unless the expression is enclosed in parentheses).

1817

1852

In all other contexts,

1818

1853

Lua adjusts the result list to one element,

1819

1854

discarding all values except the first one.

1881

1916

string and number values at run time.

1882

1917

Any arithmetic operation applied to a string tries to convert

1883

1918

this string to a number, following the rules of the Lua lexer.

1884

(The string may have leading and trailing spaces,

1885

plus an optional sign.)

1919

(The string may have leading and trailing spaces and a sign.)

1886

1920

Conversely, whenever a number is used where a string is expected,

1887

1921

the number is converted to a string, in a reasonable format.

1888

1922

For complete control over how numbers are converted to strings,

1992

2026

denoted by two dots ('<code>..</code>').

1993

2027

If both operands are strings or numbers, then they are converted to

1994

2028

strings according to the rules mentioned in <a href="#3.4.2">§3.4.2</a>.

1995

Otherwise, the "concat" metamethod is called (see <a href="#2.4">§2.4</a>).

2029

Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>).

1996

2030

1997

2031

1998

2032

2254

2288

<p>

2255

2289

A function definition is an executable expression,

2256

2290

whose value has type <em>function</em>.

2257

When Lua pre-compiles a chunk,

2258

all its function bodies are pre-compiled too.

2291

When Lua precompiles a chunk,

2292

all its function bodies are precompiled too.

2259

2293

Then, whenever Lua executes the function definition,

2260

2294

the function is <em>instantiated</em> (or <em>closed</em>).

2261

2295

This function instance (or <em>closure</em>)

2272

2306

When a function is called,

2273

2307

the list of arguments is adjusted to

2274

2308

the length of the list of parameters,

2275

unless the function is a variadic or <em>vararg function</em>,

2276

which is

2277

indicated by three dots ('<code>...</code>') at the end of its parameter list.

2309

unless the function is a <em>vararg function</em>,

2310

which is indicated by three dots ('<code>...</code>')

2311

at the end of its parameter list.

2278

2312

A vararg function does not adjust its argument list;

2279

2313

instead, it collects all extra arguments and supplies them

2280

2314

to the function through a <em>vararg expression</em>,

2425

2459

<p>

2426

2460

Even when we use the term "function",

2427

2461

any facility in the API may be provided as a macro instead.

2428

All such macros use each of their arguments exactly once

2462

Except where stated otherwise,

2463

all such macros use each of their arguments exactly once

2429

2464

(except for the first argument, which is always a Lua state),

2430

2465

and so do not generate any hidden side-effects.

2431

2466

2434

2469

As in most C libraries,

2435

2470

the Lua API functions do not check their arguments for validity or consistency.

2436

2471

However, you can change this behavior by compiling Lua

2437

with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>,

2438

in file <code>luaconf.h</code>.

2472

with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.

2439

2473

2440

2474

2441

2475

2472

2506

index -1 also represents the last element

2473

2507

(that is, the element at the top)

2474

2508

and index <em>-n</em> represents the first element.

2475

We say that an index is <em>valid</em>

2476

if it lies between 1 and the stack top

2477

(that is, if <code>1 ≤ abs(index) ≤ top</code>).

2478

2479

2509

2480

2510

2481

2511

2494

2524

2495

2525

<p>

2496

2526

Whenever Lua calls C,

2497

it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available.

2527

it ensures that the stack has at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.

2498

2528

<code>LUA_MINSTACK</code> is defined as 20,

2499

2529

so that usually you do not have to worry about stack space

2500

2530

unless your code has loops pushing elements onto the stack.

2509

2539

you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.

2510

2540

2511

2541

2512

<p>

2513

Most query functions accept as indices any value inside the

2514

available stack space, that is, indices up to the maximum stack size

2515

that you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>.

2516

Such indices are called <em>acceptable indices</em>.

2517

More formally, we define an <em>acceptable index</em>

2542

2543

2544

2545

<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2>

2546

2547

<p>

2548

Any function in the API that receives stack indices

2549

works only with <em>valid indices</em> or <em>acceptable indices</em>.

2550

2551

2552

<p>

2553

A <em>valid index</em> is an index that refers to a

2554

valid position within the stack, that is,

2555

it lies between 1 and the stack top

2556

(<code>1 ≤ abs(index) ≤ top</code>).

2557

2558

Usually, functions that need a specific stack position

2559

(e.g., <a href="#lua_remove"><code>lua_remove</code></a>) require valid indices.

2560

2561

2562

<p>

2563

Functions that do not need a specific stack position,

2564

but only a value in the stack (e.g., query functions),

2565

can be called with acceptable indices.

2566

An <em>acceptable index</em> refers to a position within

2567

the space allocated for the stack,

2568

that is, indices up to the stack size.

2569

More formally, we define an acceptable index

2518

2570

as follows:

2519

2571

2520

2572

<pre>

2521

2573

(index < 0 && abs(index) <= top) ||

2522

(index > 0 && index <= stackspace)

2574

(index > 0 && index <= stack size)

2523

2575

</pre><p>

2524

Note that 0 is never an acceptable index.

2525

2526

2527

2528

2529

2530

<h2>4.3 – <a name="4.3">Pseudo-Indices</a></h2>

2576

(Note that 0 is never an acceptable index.)

2577

When a function is called,

2578

its stack size is <code>top + LUA_MINSTACK</code>.

2579

You can change its stack size through function <a href="#lua_checkstack"><code>lua_checkstack</code></a>.

2580

2581

2582

<p>

2583

Acceptable indices serve to avoid extra tests

2584

against the stack top when querying the stack.

2585

For instance, a C function can query its third argument

2586

without the need to first check whether there is a third argument,

2587

that is, without the need to check whether 3 is a valid index.

2588

2589

2590

<p>

2591

For functions that can be called with acceptable indices,

2592

any non-valid index is treated as if it

2593

contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>.

2594

2531

2595

2532

2596

<p>

2533

2597

Unless otherwise noted,

2534

2598

any function that accepts valid indices also accepts <em>pseudo-indices</em>,

2535

2599

which represent some Lua values that are accessible to C code

2536

2600

but which are not in the stack.

2537

Pseudo-indices are used to access

2538

the registry

2601

Pseudo-indices are used to access the registry

2539

2602

and the upvalues of a C function (see <a href="#4.4">§4.4</a>).

2540

2603

2541

2604

2547

2610

<p>

2548

2611

When a C function is created,

2549

2612

it is possible to associate some values with it,

2550

thus creating a <em>C closure</em>;

2613

thus creating a <em>C closure</em>

2614

(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);

2551

2615

these values are called <em>upvalues</em> and are

2552

accessible to the function whenever it is called

2553

(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>).

2616

accessible to the function whenever it is called.

2554

2617

2555

2618

2556

2619

<p>

2573

2636

2574

2637

<p>

2575

2638

Lua provides a <em>registry</em>,

2576

a pre-defined table that can be used by any C code to

2577

store whatever Lua value it needs to store.

2578

This table is always located at pseudo-index

2639

a predefined table that can be used by any C code to

2640

store whatever Lua values it needs to store.

2641

The registry table is always located at pseudo-index

2579

2642

<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.

2580

2643

Any C library can store data into this table,

2581

but it should take care to choose keys different from those used

2644

but it should take care to choose keys

2645

that are different from those used

2582

2646

by other libraries, to avoid collisions.

2583

2647

Typically, you should use as key a string containing your library name,

2584

2648

or a light userdata with the address of a C object in your code,

2610

2674

2611

2675

<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has

2612

2676

the global environment.

2613

This is the C equivalent to the <a href="#pdf-_G"><code>_G</code></a> global variable.

2614

2677

</li>

2615

2678

</ul>

2616

2679

2629

2692

it <em>raises</em> an error;

2630

2693

that is, it does a long jump.

2631

2694

A <em>protected environment</em> uses <code>setjmp</code>

2632

to set a recover point;

2633

any error jumps to the most recent active recover point.

2695

to set a recovery point;

2696

any error jumps to the most recent active recovery point.

2634

2697

2635

2698

2636

2699

<p>

2639

2702

and then calls <code>abort</code>,

2640

2703

thus exiting the host application.

2641

2704

Your panic function can avoid this exit by

2642

never returning (e.g., doing a long jump).

2705

never returning

2706

(e.g., doing a long jump to your own recovery point outside Lua).

2643

2707

2644

2708

2645

2709

<p>

2677

2741

2678

2742

2679

2743

<p>

2680

To explain continuations,

2681

let us set some terminology.

2744

We need to set some terminology to explain continuations.

2682

2745

We have a C function called from Lua which we will call

2683

2746

the <em>original function</em>.

2684

2747

This original function then calls one of those three functions in the C API,

2704

2767

2705

2768

2706

2769

<p>

2707

Lua treats the continuation function as if it was the original function.

2770

Lua treats the continuation function as if it were the original function.

2708

2771

The continuation function receives the same Lua stack

2709

2772

from the original function,

2710

2773

in the same state it would be if the callee function had returned.

2712

2775

after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are

2713

2776

removed from the stack and replaced by the results from the call.)

2714

2777

It also has the same upvalues.

2715

Whatever it returns is handled by Lua as if it was the return

2778

Whatever it returns is handled by Lua as if it were the return

2716

2779

of the original function.

2717

2780

2718

2781

2749

2812

The third field, <code>x</code>,

2750

2813

tells whether the function may throw errors:

2751

2814

'<code>-</code>' means the function never throws any error;

2752

'<code>m</code>' means the function may throw an error

2753

only due to not enough memory;

2815

'<code>m</code>' means the function may throw only memory allocation errors;

2754

2816

'<code>e</code>' means the function may throw other kinds of errors;

2755

2817

'<code>v</code>' means the function may throw an error on purpose.

2756

2818

2757

2819

2758

2820

2759

2821

<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>

2760

2822

2761

2823

<pre>int lua_absindex (lua_State *L, int idx);</pre>

2762

2824

2763

2825

<p>

2795

2857

2796

2858

<p>

2797

2859

When <code>ptr</code> is <code>NULL</code>,

2798

<code>osize</code> codes the kind of object that Lua is allocating.

2860

<code>osize</code> encodes the kind of object that Lua is allocating.

2799

2861

<code>osize</code> is any of

2800

2862

<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>,

2801

2863

<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)

2818

2880

When <code>nsize</code> is not zero,

2819

2881

the allocator should behave like <code>realloc</code>.

2820

2882

The allocator returns <code>NULL</code>

2821

if and only if it cannot fill the request.

2883

if and only if it cannot fulfill the request.

2822

2884

Lua assumes that the allocator never fails when

2823

2885

<code>osize >= nsize</code>.

2824

2886

2843

2905

that <code>free(NULL)</code> has no effect and that

2844

2906

<code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>.

2845

2907

This code assumes that <code>realloc</code> does not fail when shrinking a block.

2846

Standard C does not ensure this behavior,

2847

but it seems a safe assumption.

2908

(Although Standard C does not ensure this behavior,

2909

it seems to be a safe assumption.)

2848

2910

2849

2911

2850

2912

2883

2945

2884

2946

2885

2947

<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>

2886

2948

2887

2949

<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>

2888

2950

2889

2951

<p>

2901

2963

2902

2964

2903

2965

2904

<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>

2966

<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>

2905

2967

<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>

2906

2968

2907

2969

<p>

3025

3087

3026

3088

3027

3089

<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>

3028

3090

3029

3091

<pre>int lua_checkstack (lua_State *L, int extra);</pre>

3030

3092

3031

3093

<p>

3032

3094

Ensures that there are at least <code>extra</code> free stack slots in the stack.

3033

It returns false if it cannot grant the request,

3095

It returns false if it cannot fulfill the request,

3034

3096

because it would cause the stack to be larger than a fixed maximum size

3035

3097

(typically at least a few thousand elements) or

3036

3098

because it cannot allocate memory for the new stack size.

3043

3105

3044

3106

3045

3107

<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>

3046

3108

3047

3109

<pre>void lua_close (lua_State *L);</pre>

3048

3110

3049

3111

<p>

3052

3114

and frees all dynamic memory used by this state.

3053

3115

On several platforms, you may not need to call this function,

3054

3116

because all resources are naturally released when the host program ends.

3055

On the other hand, long-running programs,

3056

such as a daemon or a web server,

3057

might need to release states as soon as they are not needed,

3058

to avoid growing too large.

3117

On the other hand, long-running programs that create multiple states,

3118

such as daemons or web servers,

3119

might need to close states as soon as they are not needed.

3059

3120

3060

3121

3061

3122

3066

3127

<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>

3067

3128

3068

3129

<p>

3130

Compares two Lua values.

3069

3131

Returns 1 if the value at acceptable index <code>index1</code> satisfies <code>op</code>

3070

3132

when compared with the value at acceptable index <code>index2</code>,

3071

3133

following the semantics of the corresponding Lua operator

3106

3168

3107

3169

3108

3170

3109

3171

3110

3172

<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>

3111

3173

3112

3174

<p>

3176

3238

The error message (which can actually be a Lua value of any type)

3177

3239

must be on the stack top.

3178

3240

This function does a long jump,

3179

and therefore never returns.

3241

and therefore never returns

3180

3242

(see <a href="#luaL_error"><code>luaL_error</code></a>).

3181

3243

3182

3244

3245

3307

(i.e., not stopped).

3246

3308

</li>

3247

3309

3310

<li><b><code>LUA_GCGEN</code>: </b>

3311

changes the collector to generational mode

3312

(see <a href="#2.5">§2.5</a>).

3313

</li>

3314

3315

<li><b><code>LUA_GCINC</code>: </b>

3316

changes the collector to incremental mode.

3317

This is the default mode.

3318

</li>

3319

3248

3320

</ul>

3249

3321

3250

3322

<p>

3251

For more details about some options,

3323

For more details about these options,

3252

3324

see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.

3253

3325

3254

3326

3256

3328

3257

3329

3258

3330

<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>

3259

3331

3260

3332

<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>

3261

3333

3262

3334

<p>

3269

3341

3270

3342

3271

3343

<hr><h3><a name="lua_getctx"><code>lua_getctx</code></a></h3><p>

3272

3344

3273

3345

<pre>int lua_getctx (lua_State *L, int *ctx);</pre>

3274

3346

3275

3347

<p>

3293

3365

Lua may also call its continuation function

3294

3366

to handle errors during the call.

3295

3367

That is, upon an error in the function called by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,

3296

Lua may not return <a href="#lua_pcallk"><code>lua_pcallk</code></a>

3368

Lua may not return to the original function

3297

3369

but instead may call the continuation function.

3298

3370

In that case, a call to <a href="#lua_getctx"><code>lua_getctx</code></a> will return the error code

3299

3371

(the value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>);

3324

3396

3325

3397

<p>

3326

3398

Pushes onto the stack the value of the global <code>name</code>.

3327

It is defined as a macro.

3328

3399

3329

3400

3330

3401

3331

3402

3332

3403

3333

3404

<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>

3334

3405

3335

3406

<pre>int lua_getmetatable (lua_State *L, int index);</pre>

3336

3407

3337

3408

<p>

3338

3409

Pushes onto the stack the metatable of the value at the given

3339

3410

acceptable index.

3340

If the index is not valid,

3341

or if the value does not have a metatable,

3411

If the value does not have a metatable,

3342

3412

the function returns 0 and pushes nothing on the stack.

3343

3413

3344

3414

3366

3436

3367

3437

3368

3438

<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>

3369

3439

3370

3440

<pre>int lua_gettop (lua_State *L);</pre>

3371

3441

3372

3442

<p>

3380

3450

3381

3451

3382

3452

<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>

3383

3453

3384

3454

<pre>void lua_getuservalue (lua_State *L, int index);</pre>

3385

3455

3386

3456

<p>

3393

3463

3394

3464

3395

3465

<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>

3396

3466

3397

3467

<pre>void lua_insert (lua_State *L, int index);</pre>

3398

3468

3399

3469

<p>

3423

3493

3424

3494

3425

3495

<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>

3426

3496

3427

3497

<pre>int lua_isboolean (lua_State *L, int index);</pre>

3428

3498

3429

3499

<p>

3430

Returns 1 if the value at the given acceptable index has type boolean,

3500

Returns 1 if the value at the given acceptable index is a boolean,

3431

3501

and 0 otherwise.

3432

3502

3433

3503

3435

3505

3436

3506

3437

3507

<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>

3438

3508

3439

3509

<pre>int lua_iscfunction (lua_State *L, int index);</pre>

3440

3510

3441

3511

<p>

3447

3517

3448

3518

3449

3519

<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>

3450

3520

3451

3521

<pre>int lua_isfunction (lua_State *L, int index);</pre>

3452

3522

3453

3523

<p>

3459

3529

3460

3530

3461

3531

<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>

3462

3532

3463

3533

<pre>int lua_islightuserdata (lua_State *L, int index);</pre>

3464

3534

3465

3535

<p>

3471

3541

3472

3542

3473

3543

<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>

3474

3544

3475

3545

<pre>int lua_isnil (lua_State *L, int index);</pre>

3476

3546

3477

3547

<p>

3483

3553

3484

3554

3485

3555

<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>

3486

3556

3487

3557

<pre>int lua_isnone (lua_State *L, int index);</pre>

3488

3558

3489

3559

<p>

3496

3566

3497

3567

3498

3568

<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>

3499

3569

3500

3570

<pre>int lua_isnoneornil (lua_State *L, int index);</pre>

3501

3571

3502

3572

<p>

3510

3580

3511

3581

3512

3582

<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>

3513

3583

3514

3584

<pre>int lua_isnumber (lua_State *L, int index);</pre>

3515

3585

3516

3586

<p>

3523

3593

3524

3594

3525

3595

<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>

3526

3596

3527

3597

<pre>int lua_isstring (lua_State *L, int index);</pre>

3528

3598

3529

3599

<p>

3536

3606

3537

3607

3538

3608

<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>

3539

3609

3540

3610

<pre>int lua_istable (lua_State *L, int index);</pre>

3541

3611

3542

3612

<p>

3548

3618

3549

3619

3550

3620

<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>

3551

3621

3552

3622

<pre>int lua_isthread (lua_State *L, int index);</pre>

3553

3623

3554

3624

<p>

3560

3630

3561

3631

3562

3632

<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>

3563

3633

3564

3634

<pre>int lua_isuserdata (lua_State *L, int index);</pre>

3565

3635

3566

3636

<p>

3585

3655

3586

3656

3587

3657

3588

3658

3589

3659

<pre>int lua_load (lua_State *L,

3590

3660

lua_Reader reader,

3591

3661

void *data,

3592

const char *source);</pre>

3662

const char *source,

3663

const char *mode);</pre>

3593

3664

3594

3665

<p>

3595

Loads a Lua chunk.

3666

Loads a Lua chunk (without running it).

3596

3667

If there are no errors,

3597

<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua

3668

<code>lua_load</code> pushes the compiled chunk as a Lua

3598

3669

function on top of the stack.

3599

3670

Otherwise, it pushes an error message.

3600

The return values of <a href="#lua_load"><code>lua_load</code></a> are:

3671

3672

3673

<p>

3674

The return values of <code>lua_load</code> are:

3601

3675

3602

3676

<ul>

3603

3677

3604

<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors;</li>

3678

<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>

3605

3679

3606

3680

<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>

3607

syntax error during pre-compilation;</li>

3681

syntax error during precompilation;</li>

3608

3682

3609

3683

<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>

3610

memory allocation error.</li>

3684

memory allocation error;</li>

3611

3685

3612

3686

<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>

3613

3687

error while running a <code>__gc</code> metamethod.

3618

3692

</ul>

3619

3693

3620

3694

<p>

3621

This function only loads a chunk;

3622

it does not run it.

3623

3624

3625

<p>

3626

<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary,

3627

and loads it accordingly (see program <code>luac</code>).

3628

3629

3630

<p>

3631

The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function

3695

The <code>lua_load</code> function uses a user-supplied <code>reader</code> function

3632

3696

to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).

3633

3697

The <code>data</code> argument is an opaque value passed to the reader function.

3634

3698

3639

3703

3640

3704

3641

3705

<p>

3706

<code>lua_load</code> automatically detects whether the chunk is text or binary

3707

and loads it accordingly (see program <code>luac</code>).

3708

The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,

3709

with the addition that

3710

a <code>NULL</code> value is equivalent to the string "<code>bt</code>".

3711

3712

3713

<p>

3642

3714

If the resulting function has one upvalue,

3643

3715

this upvalue is set to the value of the global environment

3644

3716

stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>).

3645

(When loading main chunks,

3646

this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).)

3717

When loading main chunks,

3718

this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).

3647

3719

3648

3720

3649

3721

3650

3722

3651

3723

3652

3724

<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>

3653

3725

3654

3726

<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>

3655

3727

3656

3728

<p>

3657

3729

Creates a new thread running in a new, independent state.

3658

Returns <code>NULL</code> if cannot create the thread/state

3730

Returns <code>NULL</code> if cannot create the thread or the state

3659

3731

(due to lack of memory).

3660

3732

The argument <code>f</code> is the allocator function;

3661

3733

Lua does all memory allocation for this state through this function.

3662

3734

The second argument, <code>ud</code>, is an opaque pointer that Lua

3663

simply passes to the allocator in every call.

3735

passes to the allocator in every call.

3664

3736

3665

3737

3666

3738

3686

3758

Creates a new thread, pushes it on the stack,

3687

3759

and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.

3688

3760

The new thread returned by this function shares with the original thread

3689

all global objects (such as tables),

3761

its global environment,

3690

3762

but has an independent execution stack.

3691

3763

3692

3764

3707

3779

This function allocates a new block of memory with the given size,

3708

3780

pushes onto the stack a new full userdata with the block address,

3709

3781

and returns this address.

3710

3711

3712

<p>

3713

Userdata represent C values in Lua.

3714

A <em>full userdata</em> represents a block of memory.

3715

It is an object (like a table):

3716

you must create it, it can have its own metatable,

3717

and you can detect when it is being collected.

3718

A full userdata is only equal to itself (under raw equality).

3782

The host program can freely use this memory.

3719

3783

3720

3784

3721

3785

3780

3844

3781

3845

3782

3846

<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>

3783

<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span>

3847

<span class="apii">[-(nargs + 1), +(nresults|1), –]</span>

3784

3848

<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>

3785

3849

3786

3850

<p>

3855

3919

3856

3920

3857

3921

<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>

3858

<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span>

3859

<pre>int lua_pcallk (lua_State *L, int nargs, int nresults, int errfunc,

3860

int ctx, lua_CFunction k);</pre>

3922

<span class="apii">[-(nargs + 1), +(nresults|1), –]</span>

3923

<pre>int lua_pcallk (lua_State *L,

3924

int nargs,

3925

int nresults,

3926

int errfunc,

3927

int ctx,

3928

lua_CFunction k);</pre>

3861

3929

3862

3930

<p>

3863

3931

This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,

3868

3936

3869

3937

3870

3938

3871

3939

3872

3940

<pre>void lua_pop (lua_State *L, int n);</pre>

3873

3941

3874

3942

<p>

3879

3947

3880

3948

3881

3949

<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>

3882

3950

3883

3951

<pre>void lua_pushboolean (lua_State *L, int b);</pre>

3884

3952

3885

3953

<p>

3920

3988

When <code>n</code> is zero,

3921

3989

this function creates a <em>light C function</em>,

3922

3990

which is just a pointer to the C function.

3923

In that case, it cannot throw a memory error.

3991

In that case, it never throws a memory error.

3924

3992

3925

3993

3926

3994

3927

3995

3928

3996

3929

3997

<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>

3930

3998

3931

3999

<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>

3932

4000

3933

4001

<p>

3948

4016

3949

4017

<pre>

3950

4018

#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)

3951

</pre>

4019

</pre><p>

4020

Note that <code>f</code> is used twice.

4021

3952

4022

3953

4023

3954

4024

3980

4050

'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),

3981

4051

'<code>%p</code>' (inserts a pointer as a hexadecimal numeral),

3982

4052

'<code>%d</code>' (inserts an <code>int</code>), and

3983

'<code>%c</code>' (inserts an <code>int</code> as a character).

4053

'<code>%c</code>' (inserts an <code>int</code> as a byte).

3984

4054

</li>

3985

4055

3986

4056

</ul>

3989

4059

3990

4060

3991

4061

<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>

3992

4062

3993

4063

<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>

3994

4064

3995

4065

<p>

4000

4070

4001

4071

4002

4072

<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>

4003

4073

4004

4074

<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>

4005

4075

4006

4076

<p>

4027

4097

<p>

4028

4098

This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,

4029

4099

but can be used only when <code>s</code> is a literal string.

4030

In these cases, it automatically provides the string length.

4100

It automatically provides the string length.

4031

4101

4032

4102

4033

4103

4055

4125

4056

4126

4057

4127

<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>

4058

4128

4059

4129

<pre>void lua_pushnil (lua_State *L);</pre>

4060

4130

4061

4131

<p>

4066

4136

4067

4137

4068

4138

<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>

4069

4139

4070

4140

<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>

4071

4141

4072

4142

<p>

4100

4170

4101

4171

4102

4172

<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>

4103

4173

4104

4174

<pre>int lua_pushthread (lua_State *L);</pre>

4105

4175

4106

4176

<p>

4112

4182

4113

4183

4114

4184

<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>

4115

4185

4116

4186

<pre>void lua_pushvalue (lua_State *L, int index);</pre>

4117

4187

4118

4188

<p>

4138

4208

4139

4209

4140

4210

<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>

4141

4211

4142

4212

<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>

4143

4213

4144

4214

<p>

4153

4223

4154

4224

4155

4225

<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>

4156

4226

4157

4227

<pre>void lua_rawget (lua_State *L, int index);</pre>

4158

4228

4159

4229

<p>

4165

4235

4166

4236

4167

4237

<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>

4168

4238

4169

4239

<pre>void lua_rawgeti (lua_State *L, int index, int n);</pre>

4170

4240

4171

4241

<p>

4178

4248

4179

4249

4180

4250

4251

<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>

4252

4253

<pre>void lua_rawgetp (lua_State *L, int index, const void *p);</pre>

4254

4255

<p>

4256

Pushes onto the stack the value <code>t[k]</code>,

4257

where <code>t</code> is the table at the given valid index and

4258

<code>k</code> is the pointer <code>p</code> represented as a light userdata.

4259

The access is raw;

4260

that is, it does not invoke metamethods.

4261

4262

4263

4264

4265

4181

4266

<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>

4182

4267

4183

4268

<pre>size_t lua_rawlen (lua_State *L, int index);</pre>

4184

4269

4185

4270

<p>

4226

4311

4227

4312

4228

4313

4314

<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>

4315

4316

<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>

4317

4318

<p>

4319

Does the equivalent of <code>t[k] = v</code>,

4320

where <code>t</code> is the table at the given valid index,

4321

<code>k</code> is the pointer <code>p</code> represented as a light userdata,

4322

and <code>v</code> is the value at the top of the stack.

4323

4324

4325

<p>

4326

This function pops the value from the stack.

4327

The assignment is raw;

4328

that is, it does not invoke metamethods.

4329

4330

4331

4332

4333

4229

4334

<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>

4230

4335

<pre>typedef const char * (*lua_Reader) (lua_State *L,

4231

4336

void *data,

4250

4355

4251

4356

<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>

4252

4357

4253

<pre>void lua_register (lua_State *L,

4254

const char *name,

4255

lua_CFunction f);</pre>

4358

<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>

4256

4359

4257

4360

<p>

4258

4361

Sets the C function <code>f</code> as the new value of global <code>name</code>.

4267

4370

4268

4371

4269

4372

<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>

4270

4373

4271

4374

<pre>void lua_remove (lua_State *L, int index);</pre>

4272

4375

4273

4376

<p>

4281

4384

4282

4385

4283

4386

<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>

4284

4387

4285

4388

<pre>void lua_replace (lua_State *L, int index);</pre>

4286

4389

4287

4390

<p>

4295

4398

4296

4399

4297

4400

<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>

4298

4299

<pre>int lua_resume (lua_State *L, int narg);</pre>

4401

4402

<pre>int lua_resume (lua_State *L, lua_State *from, int narg);</pre>

4300

4403

4301

4404

<p>

4302

4405

Starts and resumes a coroutine in a given thread.

4330

4433

and then call <a href="#lua_resume"><code>lua_resume</code></a>.

4331

4434

4332

4435

4436

<p>

4437

The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.

4438

If there is no such coroutine,

4439

this parameter can be <code>NULL</code>.

4440

4441

4333

4442

4334

4443

4335

4444

4336

4445

<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>

4337

4446

4338

4447

<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>

4339

4448

4340

4449

<p>

4371

4480

<p>

4372

4481

Pops a value from the stack and

4373

4482

sets it as the new value of global <code>name</code>.

4374

It is defined as a macro.

4375

4483

4376

4484

4377

4485

4378

4486

4379

4487

4380

4488

<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>

4381

4489

4382

4490

<pre>void lua_setmetatable (lua_State *L, int index);</pre>

4383

4491

4384

4492

<p>

4411

4519

4412

4520

4413

4521

<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>

4414

4522

4415

4523

<pre>void lua_settop (lua_State *L, int index);</pre>

4416

4524

4417

4525

<p>

4426

4534

4427

4535

4428

4536

<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>

4429

4537

4430

4538

<pre>void lua_setuservalue (lua_State *L, int index);</pre>

4431

4539

4432

4540

<p>

4457

4565

4458

4566

4459

4567

<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>

4460

4568

4461

4569

<pre>int lua_status (lua_State *L);</pre>

4462

4570

4463

4571

<p>

4482

4590

4483

4591

4484

4592

<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>

4485

4593

4486

4594

<pre>int lua_toboolean (lua_State *L, int index);</pre>

4487

4595

4488

4596

<p>

4501

4609

4502

4610

4503

4611

<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>

4504

4612

4505

4613

<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>

4506

4614

4507

4615

<p>

4514

4622

4515

4623

4516

4624

<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>

4517

4625

4518

4626

<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>

4519

4627

4520

4628

<p>

4521

A macro equivalent to <code>lua_tointegerx(L, index, NULL)</code>.

4629

Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.

4522

4630

4523

4631

4524

4632

4525

4633

4526

4634

4527

4635

<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>

4528

4636

4529

4637

<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>

4530

4638

4531

4639

<p>

4533

4641

to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.

4534

4642

The Lua value must be a number or a string convertible to a number

4535

4643

(see <a href="#3.4.2">§3.4.2</a>);

4536

otherwise, <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> returns 0.

4644

otherwise, <code>lua_tointegerx</code> returns 0.

4537

4645

4538

4646

4539

4647

<p>

4542

4650

4543

4651

4544

4652

<p>

4545

If <code>isnum</code> is different from <code>NULL</code>,

4653

If <code>isnum</code> is not <code>NULL</code>,

4546

4654

its referent is assigned a boolean value that

4547

4655

indicates whether the operation succeeded.

4548

4656

4561

4669

The Lua value must be a string or a number;

4562

4670

otherwise, the function returns <code>NULL</code>.

4563

4671

If the value is a number,

4564

then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also

4672

then <code>lua_tolstring</code> also

4565

4673

<em>changes the actual value in the stack to a string</em>.

4566

4674

(This change confuses <a href="#lua_next"><code>lua_next</code></a>

4567

when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.)

4675

when <code>lua_tolstring</code> is applied to keys during a table traversal.)

4568

4676

4569

4677

4570

4678

<p>

4571

<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer

4679

<code>lua_tolstring</code> returns a fully aligned pointer

4572

4680

to a string inside the Lua state.

4573

4681

This string always has a zero ('<code>\0</code>')

4574

4682

after its last character (as in C),

4575

4683

but can contain other zeros in its body.

4576

4684

Because Lua has garbage collection,

4577

there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a>

4685

there is no guarantee that the pointer returned by <code>lua_tolstring</code>

4578

4686

will be valid after the corresponding value is removed from the stack.

4579

4687

4580

4688

4582

4690

4583

4691

4584

4692

<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>

4585

4693

4586

4694

<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>

4587

4695

4588

4696

<p>

4589

A macro equivalent to <code>lua_tonumberx(L, index, NULL)</code>.

4697

Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.

4590

4698

4591

4699

4592

4700

4593

4701

4594

4702

4595

4703

<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>

4596

4704

4597

4705

<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>

4598

4706

4599

4707

<p>

4605

4713

4606

4714

4607

4715

<p>

4608

If <code>isnum</code> is different from <code>NULL</code>,

4716

If <code>isnum</code> is not <code>NULL</code>,

4609

4717

its referent is assigned a boolean value that

4610

4718

indicates whether the operation succeeded.

4611

4719

4614

4722

4615

4723

4616

4724

<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>

4617

4725

4618

4726

<pre>const void *lua_topointer (lua_State *L, int index);</pre>

4619

4727

4620

4728

<p>

4621

4729

Converts the value at the given acceptable index to a generic

4622

4730

C pointer (<code>void*</code>).

4623

4731

The value can be a userdata, a table, a thread, or a function;

4624

otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>.

4732

otherwise, <code>lua_topointer</code> returns <code>NULL</code>.

4625

4733

Different objects will give different pointers.

4626

4734

There is no way to convert the pointer back to its original value.

4627

4735

4645

4753

4646

4754

4647

4755

<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>

4648

4756

4649

4757

<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>

4650

4758

4651

4759

<p>

4659

4767

4660

4768

4661

4769

<hr><h3><a name="lua_tounsigned"><code>lua_tounsigned</code></a></h3><p>

4662

4770

4663

4771

<pre>lua_Unsigned lua_tounsigned (lua_State *L, int index);</pre>

4664

4772

4665

4773

<p>

4666

A macro equivalent to <code>lua_tounsignedx(L, index, NULL)</code>.

4774

Equivalent to <a href="#lua_tounsignedx"><code>lua_tounsignedx</code></a> with <code>isnum</code> equal to <code>NULL</code>.

4667

4775

4668

4776

4669

4777

4670

4778

4671

4779

4672

4780

<hr><h3><a name="lua_tounsignedx"><code>lua_tounsignedx</code></a></h3><p>

4673

4781

4674

4782

<pre>lua_Unsigned lua_tounsignedx (lua_State *L, int index, int *isnum);</pre>

4675

4783

4676

4784

<p>

4678

4786

to the unsigned integral type <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>.

4679

4787

The Lua value must be a number or a string convertible to a number

4680

4788

(see <a href="#3.4.2">§3.4.2</a>);

4681

otherwise, <a href="#lua_tounsignedx"><code>lua_tounsignedx</code></a> returns 0.

4789

otherwise, <code>lua_tounsignedx</code> returns 0.

4682

4790

4683

4791

4684

4792

<p>

4690

4798

4691

4799

4692

4800

<p>

4693

If <code>isnum</code> is different from <code>NULL</code>,

4801

If <code>isnum</code> is not <code>NULL</code>,

4694

4802

its referent is assigned a boolean value that

4695

4803

indicates whether the operation succeeded.

4696

4804

4699

4807

4700

4808

4701

4809

<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>

4702

4810

4703

4811

<pre>void *lua_touserdata (lua_State *L, int index);</pre>

4704

4812

4705

4813

<p>

4714

4822

4715

4823

4716

4824

4717

4825

4718

4826

<pre>int lua_type (lua_State *L, int index);</pre>

4719

4827

4720

4828

<p>

4721

4829

Returns the type of the value in the given acceptable index,

4722

or <code>LUA_TNONE</code> for a non-valid index

4723

(that is, an index to an "empty" stack position).

4830

or <code>LUA_TNONE</code> for a non-valid index.

4724

4831

The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants

4725

4832

defined in <code>lua.h</code>:

4726

4833

<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,

4739

4846

4740

4847

4741

4848

<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>

4742

4849

4743

4850

<pre>const char *lua_typename (lua_State *L, int tp);</pre>

4744

4851

4745

4852

<p>

4807

4914

4808

4915

4809

4916

<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>

4810

4917

4811

4918

<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>

4812

4919

4813

4920

<p>

4814

Exchange values between different threads of the same global state.

4921

Exchange values between different threads of the same state.

4815

4922

4816

4923

4817

4924

<p>

4823

4930

4824

4931

4825

4932

<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>

4826

4933

4827

4934

<pre>int lua_yield (lua_State *L, int nresults);</pre>

4828

4935

4829

4936

<p>

4838

4945

4839

4946

4840

4947

<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>

4841

4948

4842

4949

<pre>int lua_yieldk (lua_State *L, int nresults, int ctx, lua_CFunction k);</pre>

4843

4950

4844

4951

<p>

4850

4957

return expression of a C function, as follows:

4851

4958

4852

4959

<pre>

4853

return lua_yield (L, nresults, i, k);

4960

return lua_yieldk (L, n, i, k);

4854

4961

</pre><p>

4855

4962

When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a> in that way,

4856

4963

the running coroutine suspends its execution,

4928

5035

it means that the function was defined in a file where

4929

5036

the file name follows the '<code>@</code>'.

4930

5037

If <code>source</code> starts with a '<code>=</code>',

4931

the rest of it should describe the source in a user-dependent manner.

5038

the remainder of its contents describe the source in a user-dependent manner.

4932

5039

Otherwise,

4933

5040

the function was defined in a string where

4934

5041

<code>source</code> is that string.

4994

5101

</li>

4995

5102

4996

5103

<li><b><code>isvararg</code>: </b>

4997

whether the function is a vararg function

5104

true if the function is a vararg function

4998

5105

(always true for C functions).

4999

5106

</li>

5000

5107

5004

5111

5005

5112

5006

5113

<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>

5007

5114

5008

5115

<pre>lua_Hook lua_gethook (lua_State *L);</pre>

5009

5116

5010

5117

<p>

5015

5122

5016

5123

5017

5124

<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>

5018

5125

5019

5126

<pre>int lua_gethookcount (lua_State *L);</pre>

5020

5127

5021

5128

<p>

5026

5133

5027

5134

5028

5135

<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>

5029

5136

5030

5137

<pre>int lua_gethookmask (lua_State *L);</pre>

5031

5138

5032

5139

<p>

5115

5222

5116

5223

5117

5224

<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>

5118

5225

5119

5226

<pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre>

5120

5227

5121

5228

<p>

5156

5263

5157

5264

5158

5265

<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>

5159

5266

5160

5267

<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>

5161

5268

5162

5269

<p>

5179

5286

5180

5287

5181

5288

<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>

5182

5289

5183

5290

<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>

5184

5291

5185

5292

<p>

5241

5348

5242

5349

5243

5350

<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>

5244

5351

5245

5352

<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>

5246

5353

5247

5354

<p>

5294

5401

5295

5402

5296

5403

<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>

5297

5404

5298

5405

<pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre>

5299

5406

5300

5407

<p>

5316

5423

5317

5424

5318

5425

<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>

5319

5426

5320

5427

<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>

5321

5428

5322

5429

<p>

5337

5444

5338

5445

5339

5446

<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>

5340

5447

5341

5448

<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>

5342

5449

5343

5450

<p>

5386

5493

5387

5494

5388

5495

<p>

5389

All functions from the auxiliary library

5496

All functions and types from the auxiliary library

5390

5497

are defined in header file <code>lauxlib.h</code> and

5391

5498

have a prefix <code>luaL_</code>.

5392

5499

5395

5502

All functions in the auxiliary library are built on

5396

5503

top of the basic API,

5397

5504

and so they provide nothing that cannot be done with that API.

5505

Nevertheless, the use of the auxiliary library ensures

5506

more consistency to your code.

5398

5507

5399

5508

5400

5509

<p>

5432

5541

<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>

5433

5542

5434

5543

<p>

5435

Adds the character <code>c</code> to the buffer <code>B</code>

5544

Adds the byte <code>c</code> to the buffer <code>B</code>

5436

5545

(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).

5437

5546

5438

5547

5474

5583

Adds the zero-terminated string pointed to by <code>s</code>

5475

5584

to the buffer <code>B</code>

5476

5585

(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).

5477

The string should not contain embedded zeros.

5586

The string cannot contain embedded zeros.

5478

5587

5479

5588

5480

5589

5509

5618

5510

5619

<p>

5511

5620

Checks whether <code>cond</code> is true.

5512

If not, raises an error with the following message,

5513

where <code>func</code> is retrieved from the call stack:

5621

If not, raises an error with a standard message.

5514

5622

5515

<pre>

5516

bad argument #<narg> to <func> (<extramsg>)

5517

</pre>

5518

5623

5519

5624

5520

5625

5524

5629

<pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre>

5525

5630

5526

5631

<p>

5527

Raises an error with the following message,

5528

where <code>func</code> is retrieved from the call stack:

5632

Raises an error with a standard message

5633

that includes <code>extramsg</code> as a comment.

5529

5634

5530

<pre>

5531

bad argument #<narg> to <func> (<extramsg>)

5532

</pre>

5533

5635

5534

5636

<p>

5535

5637

This function never returns,

5553

5655

5554

5656

<ul>

5555

5657

5556

<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>

5658

<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>

5557

5659

5558

<li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>

5660

<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>

5559

5661

5560

5662

<li>

5561

Then you add string pieces to the buffer calling any of

5663

Then add string pieces to the buffer calling any of

5562

5664

the <code>luaL_add*</code> functions.

5563

5665

</li>

5564

5666

5565

5667

<li>

5566

You finish by calling <code>luaL_pushresult(&b)</code>.

5668

Finish by calling <code>luaL_pushresult(&b)</code>.

5567

5669

This call leaves the final string on the top of the stack.

5568

5670

</li>

5569

5671

5575

5677

5576

5678

<ul>

5577

5679

5578

<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>

5680

<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>

5579

5681

5580

<li>Then you initialize it and preallocate a space of

5682

<li>Then initialize it and preallocate a space of

5581

5683

size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li>

5582

5684

5583

<li>Then you copy the string into that space.</li>

5685

<li>Then copy the string into that space.</li>

5584

5686

5585

5687

<li>

5586

You finish by calling <code>luaL_pushresult(&b, sz)</code>,

5688

Finish by calling <code>luaL_pushresult(&b, sz)</code>,

5587

5689

where <code>sz</code> is the total size of the resulting string

5588

5690

copied into that space.

5589

5691

</li>

5611

5713

5612

5714

5613

5715

<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>

5614

5716

5615

5717

<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>

5616

5718

5617

5719

<p>

5647

5749

<p>

5648

5750

If the object at index <code>obj</code> has a metatable and this

5649

5751

metatable has a field <code>e</code>,

5650

this function calls this field and passes the object as its only argument.

5752

this function calls this field passing the object as its only argument.

5651

5753

In this case this function returns true and pushes onto the

5652

5754

stack the value returned by the call.

5653

5755

If there is no metatable or no metamethod,

5755

5857

<p>

5756

5858

If <code>def</code> is not <code>NULL</code>,

5757

5859

the function uses <code>def</code> as a default value when

5758

there is no argument <code>narg</code> or if this argument is <b>nil</b>.

5860

there is no argument <code>narg</code> or when this argument is <b>nil</b>.

5759

5861

5760

5862

5761

5863

<p>

5836

5938

5837

5939

5838

5940

<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>

5839

5941

5840

5942

<pre>void luaL_checkversion (lua_State *L);</pre>

5841

5943

5842

5944

<p>

5870

5972

5871

5973

5872

5974

<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>

5873

5975

5874

5976

<pre>int luaL_dostring (lua_State *L, const char *str);</pre>

5875

5977

5876

5978

<p>

5952

6054

5953

6055

5954

6056

<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>

5955

6057

5956

6058

<pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre>

5957

6059

5958

6060

<p>

6012

6114

6013

6115

6014

6116

<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>

6015

6117

6016

6118

<pre>int luaL_loadbuffer (lua_State *L,

6017

6119

const char *buff,

6018

6120

size_t sz,

6019

6121

const char *name);</pre>

6020

6122

6021

6123

<p>

6124

Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.

6125

6126

6127

6128

6129

6130

<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>

6131

6132

<pre>int luaL_loadbufferx (lua_State *L,

6133

const char *buff,

6134

size_t sz,

6135

const char *name,

6136

const char *mode);</pre>

6137

6138

<p>

6022

6139

Loads a buffer as a Lua chunk.

6023

6140

This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the

6024

6141

buffer pointed to by <code>buff</code> with size <code>sz</code>.

6028

6145

This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.

6029

6146

<code>name</code> is the chunk name,

6030

6147

used for debug information and error messages.

6148

The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.

6031

6149

6032

6150

6033

6151

6038

6156

<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>

6039

6157

6040

6158

<p>

6159

Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.

6160

6161

6162

6163

6164

6165

<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>

6166

6167

<pre>int luaL_loadfilex (lua_State *L, const char *filename,

6168

const char *mode);</pre>

6169

6170

<p>

6041

6171

Loads a file as a Lua chunk.

6042

6172

This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file

6043

6173

named <code>filename</code>.

6047

6177

6048

6178

6049

6179

<p>

6180

The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.

6181

6182

6183

<p>

6050

6184

This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,

6051

6185

but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>

6052

if it cannot open/read the file.

6186

if it cannot open/read the file or the file has a wrong mode.

6053

6187

6054

6188

6055

6189

<p>

6061

6195

6062

6196

6063

6197

<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>

6064

6198

6065

6199

<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>

6066

6200

6067

6201

<p>

6141

6275

6142

6276

6143

6277

<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>

6144

6278

6145

6279

<pre>lua_State *luaL_newstate (void);</pre>

6146

6280

6147

6281

<p>

6434

6568

6435

6569

6436

6570

<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>

6437

6571

6438

6572

<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>

6439

6573

6440

6574

<p>

6499

6633

6500

6634

6501

6635

<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>

6502

6636

6503

6637

<pre>const char *luaL_typename (lua_State *L, int index);</pre>

6504

6638

6505

6639

<p>

6510

6644

6511

6645

6512

6646

<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>

6513

6647

6514

6648

<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>

6515

6649

6516

6650

<p>

6575

6709

6576

6710

<ul>

6577

6711

6578

<li>basic library;</li>

6579

6580

<li>package library;</li>

6581

6582

<li>coroutine library;</li>

6583

6584

<li>string manipulation;</li>

6585

6586

<li>table manipulation;</li>

6587

6588

<li>mathematical functions (sin, log, etc.);</li>

6589

6590

<li>bitwise operations;</li>

6591

6592

<li>input and output;</li>

6593

6594

<li>operating system facilities;</li>

6595

6596

<li>debug facilities.</li>

6712

<li>basic library (<a href="#6.1">§6.1</a>);</li>

6713

6714

<li>coroutine library (<a href="#6.2">§6.2</a>);</li>

6715

6716

<li>package library (<a href="#6.3">§6.3</a>);</li>

6717

6718

<li>string manipulation (<a href="#6.4">§6.4</a>);</li>

6719

6720

<li>table manipulation (<a href="#6.5">§6.5</a>);</li>

6721

6722

<li>mathematical functions (<a href="#6.6">§6.6</a>) (sin, log, etc.);</li>

6723

6724

<li>bitwise operations (<a href="#6.7">§6.7</a>);</li>

6725

6726

<li>input and output (<a href="#6.8">§6.8</a>);</li>

6727

6728

<li>operating system facilities (<a href="#6.9">§6.9</a>);</li>

6729

6730

<li>debug facilities (<a href="#6.10">§6.10</a>).</li>

6597

6731

6598

6732

</ul><p>

6599

Except for the basic and package libraries,

6733

Except for the basic and the package libraries,

6600

6734

each library provides all its functions as fields of a global table

6601

6735

or as methods of its objects.

6602

6736

6627

6761

<h2>6.1 – <a name="6.1">Basic Functions</a></h2>

6628

6762

6629

6763

<p>

6630

The basic library provides some core functions to Lua.

6764

The basic library provides core functions to Lua.

6631

6765

If you do not include this library in your application,

6632

6766

you should check carefully whether you need to provide

6633

6767

implementations for some of its facilities.

6660

6794

</li>

6661

6795

6662

6796

6663

stops automatic invocation of the garbage collector.

6664

The collector will run only when explcitly invoked,

6797

stops automatic execution of the garbage collector.

6798

The collector will run only when explicitly invoked,

6665

6799

until a call to restart it.

6666

6800

</li>

6667

6801

6668

6802

<li><b>"<code>restart</code>": </b>

6669

restarts automatic invocation the garbage collector.

6803

restarts automatic execution of the garbage collector.

6670

6804

</li>

6671

6805

6672

6806

<li><b>"<code>count</code>": </b>

6709

6843

(i.e., not stopped).

6710

6844

</li>

6711

6845

6846

<li><b>"<code>generational</code>": </b>

6847

changes the collector to generational mode.

6848

This is an experimental feature (see <a href="#2.5">§2.5</a>).

6849

</li>

6850

6851

<li><b>"<code>incremental</code>": </b>

6852

changes the collector to incremental mode.

6853

This is the default mode.

6854

</li>

6855

6712

6856

</ul>

6713

6857

6714

6858

6789

6933

<pre>

6790

6934

for i,v in ipairs(t) do <em>body</em> end

6791

6935

</pre><p>

6792

will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···,

6936

will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,

6793

6937

up to the first integer key absent from the table.

6794

6938

6795

6939

6813

6957

6814

6958

6815

6959

<p>

6816

If there are no errors,

6960

If there are no syntactic errors,

6817

6961

returns the compiled chunk as a function;

6818

6962

otherwise, returns <b>nil</b> plus the error message.

6819

6963

6823

6967

the first upvalue is set to the value of the

6824

6968

global environment or to <code>env</code>,

6825

6969

if that parameter is given.

6826

(When loading main chunks,

6827

the first upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).)

6970

When loading main chunks,

6971

the first upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).

6828

6972

6829

6973

6830

6974

<p>

6832

6976

and debug information (see <a href="#4.9">§4.9</a>).

6833

6977

When absent,

6834

6978

it defaults to <code>ld</code>, if <code>ld</code> is a string,

6835

or to "<code>=(load)</code>".

6979

or to "<code>=(load)</code>" otherwise.

6836

6980

6837

6981

6838

6982

<p>

6839

6983

The string <code>mode</code> controls whether the chunk can be text or binary

6840

6984

(that is, a precompiled chunk).

6841

A letter '<code>t</code>' in <code>mode</code> allows a text chunk;

6842

a letter '<code>b</code>' allows a binary chunk.

6985

It may be the string "<code>b</code>" (only binary chunks),

6986

"<code>t</code>" (only text chunks),

6987

or "<code>bt</code>" (both binary and text).

6843

6988

The default is "<code>bt</code>".

6844

6989

6845

6990

6846

6991

6847

6992

6848

6993

<p>

6849

<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3>

6994

<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>

6850

6995

6851

6996

6852

6997

<p>

6945

7090

6946

7091

<p>

6947

7092

<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>

6948

Receives any number of arguments,

7093

Receives any number of arguments

6949

7094

and prints their values to <code>stdout</code>,

6950

using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.

7095

using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.

6951

7096

<code>print</code> is not intended for formatted output,

6952

7097

but only as a quick way to show a value,

6953

typically for debugging.

6954

For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>.

7098

for instance for debugging.

7099

For complete control over the output,

7100

use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.

6955

7101

6956

7102

6957

7103

6990

7136

Sets the real value of <code>table[index]</code> to <code>value</code>,

6991

7137

without invoking any metamethod.

6992

7138

<code>table</code> must be a table,

6993

<code>index</code> any value different from <b>nil</b>,

7139

<code>index</code> any value different from <b>nil</b> and NaN,

6994

7140

and <code>value</code> any Lua value.

6995

7141

6996

7142

7035

7181

7036

7182

<p>

7037

7183

<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>

7038

Tries to convert its argument to a number.

7039

If the argument is already a number or a string convertible

7040

to a number, then <code>tonumber</code> returns this number;

7184

7185

7186

<p>

7187

When called with no <code>base</code>,

7188

<code>tonumber</code> tries to convert its argument to a number.

7189

If the argument is already a number or

7190

a string convertible to a number (see <a href="#3.4.2">§3.4.2</a>),

7191

then <code>tonumber</code> returns this number;

7041

7192

otherwise, it returns <b>nil</b>.

7042

7193

7043

7194

7044

7195

<p>

7045

An optional argument specifies the base to interpret the numeral.

7196

When called with <code>base</code>,

7197

then <code>e</code> should be a string to be interpreted as

7198

an integer numeral in that base.

7046

7199

The base may be any integer between 2 and 36, inclusive.

7047

7200

In bases above 10, the letter '<code>A</code>' (in either upper or lower case)

7048

7201

represents 10, '<code>B</code>' represents 11, and so forth,

7049

7202

with '<code>Z</code>' representing 35.

7050

In base 10 (the default),

7051

the numeral is converted following the coercion rules (see <a href="#3.4.2">§3.4.2</a>).

7052

In other bases, only integers are accepted.

7203

If the string <code>e</code> is not a valid numeral in the given base,

7204

the function returns <b>nil</b>.

7053

7205

7054

7206

7055

7207

7056

7208

7057

7209

<p>

7058

<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3>

7059

Receives an argument of any type and

7210

<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>

7211

Receives a value of any type and

7060

7212

converts it to a string in a reasonable format.

7061

For complete control of how numbers are converted,

7062

use <a href="#pdf-string.format"><code>string.format</code></a>.

7213

(For complete control of how numbers are converted,

7214

use <a href="#pdf-string.format"><code>string.format</code></a>.)

7063

7215

7064

7216

7065

7217

<p>

7066

If the metatable of <code>e</code> has a <code>"__tostring"</code> field,

7218

If the metatable of <code>v</code> has a <code>"__tostring"</code> field,

7067

7219

then <code>tostring</code> calls the corresponding value

7068

with <code>e</code> as argument,

7220

with <code>v</code> as argument,

7069

7221

and uses the result of the call as its result.

7070

7222

7071

7223

7139

7291

Starts or continues the execution of coroutine <code>co</code>.

7140

7292

The first time you resume a coroutine,

7141

7293

it starts running its body.

7142

The values <code>val1</code>, ··· are passed

7294

The values <code>val1</code>, ... are passed

7143

7295

as the arguments to the body function.

7144

7296

If the coroutine has yielded,

7145

7297

<code>resume</code> restarts it;

7146

the values <code>val1</code>, ··· are passed

7298

the values <code>val1</code>, ... are passed

7147

7299

as the results from the yield.

7148

7300

7149

7301

7280

7432

<p>

7281

7433

If there is any error loading or running the module,

7282

7434

or if it cannot find any loader for the module,

7283

then <code>require</code> signals an error.

7435

then <code>require</code> raises an error.

7284

7436

7285

7437

7286

7438

7309

7461

is replaced by the executable's directory.

7310

7462

Default is '<code>!</code>'.</li>

7311

7463

7312

<li>The fifth line is a mark to ignore all before it when building the

7313

<code>luaopen_</code> function name.

7464

<li>The fifth line is a mark to ignore all text before it

7465

when building the <code>luaopen_</code> function name.

7314

7466

Default is '<code>-</code>'.</li>

7315

7467

7316

7468

</ul>

7372

7524

Otherwise,

7373

7525

it looks for a function <code>funcname</code> inside the library

7374

7526

and returns this function as a C function.

7375

(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)).

7527

(So, <code>funcname</code> must follow the prototype <a href="#lua_CFunction"><code>lua_CFunction</code></a>).

7376

7528

7377

7529

7378

7530

<p>

7409

7561

the value of the environment variable <a name="pdf-LUA_PATH_5_2"><code>LUA_PATH_5_2</code></a> or

7410

7562

the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or

7411

7563

with a default path defined in <code>luaconf.h</code>,

7412

if the environment variable is not defined.

7564

if those environment variables are not defined.

7413

7565

Any "<code>;;</code>" in the value of the environment variable

7414

7566

is replaced by the default path.

7415

7567

7511

7663

7512

7664

7513

7665

<p>

7514

All searchers except the first (preload) return as the extra value

7666

All searchers except the first one (preload) return as the extra value

7515

7667

the file name where the module was found,

7516

7668

as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.

7517

7669

The first searcher returns no extra value.

7520

7672

7521

7673

7522

7674

<p>

7523

<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep])</code></a></h3>

7675

<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>

7524

7676

7525

7677

7526

7678

<p>

7528

7680

7529

7681

7530

7682

<p>

7531

A path is string containing a sequence of

7683

A path is a string containing a sequence of

7532

7684

<em>templates</em> separated by semicolons.

7533

7685

For each template,

7534

the function changes each interrogation

7535

mark in the template by a copy of <code>name</code>

7686

the function replaces each interrogation mark (if any)

7687

in the template with a copy of <code>name</code>

7536

7688

wherein all occurrences of <code>sep</code>

7537

7689

(a dot, by default)

7538

were replaced by the system's directory separator,

7690

were replaced by <code>rep</code>

7691

(the system's directory separator, by default),

7539

7692

and then tries to open the resulting file name.

7540

If <code>sep</code> is the empty string,

7541

the replacement is not done.

7542

7693

7543

7694

7544

7695

<p>

7583

7734

It also sets a metatable for strings

7584

7735

where the <code>__index</code> field points to the <code>string</code> table.

7585

7736

Therefore, you can use the string functions in object-oriented style.

7586

For instance, <code>string.byte(s, i)</code>

7737

For instance, <code>string.byte(s,i)</code>

7587

7738

can be written as <code>s:byte(i)</code>.

7588

7739

7589

7740

7594

7745

<p>

7595

7746

<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>

7596

7747

Returns the internal numerical codes of the characters <code>s[i]</code>,

7597

<code>s[i+1]</code>, ···, <code>s[j]</code>.

7748

<code>s[i+1]</code>, ..., <code>s[j]</code>.

7598

7749

The default value for <code>i</code> is 1;

7599

7750

the default value for <code>j</code> is <code>i</code>.

7751

These indices are corrected

7752

following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.

7600

7753

7601

7754

7602

7755

<p>

7603

Note that numerical codes are not necessarily portable across platforms.

7756

Numerical codes are not necessarily portable across platforms.

7604

7757

7605

7758

7606

7759

7614

7767

7615

7768

7616

7769

<p>

7617

Note that numerical codes are not necessarily portable across platforms.

7770

Numerical codes are not necessarily portable across platforms.

7618

7771

7619

7772

7620

7773

7694

7847

<code>G</code>, and <code>g</code> all expect a number as argument.

7695

7848

Options <code>c</code>, <code>d</code>,

7696

7849

7697

expect an integer as argument;

7698

the range of that integer may be limited by

7850

also expect a number,

7851

but the range of that number may be limited by

7699

7852

the underlying C implementation.

7853

For options <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>,

7854

the number cannot be negative.

7700

7855

Option <code>q</code> expects a string;

7701

7856

option <code>s</code> expects a string without embedded zeros.

7702

7857

If the argument to option <code>s</code> is not a string,

7709

7864

<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>

7710

7865

Returns an iterator function that,

7711

7866

each time it is called,

7712

returns the next captures from <code>pattern</code> over string <code>s</code>.

7867

returns the next captures from <code>pattern</code> over the string <code>s</code>.

7713

7868

If <code>pattern</code> specifies no captures,

7714

7869

then the whole match is produced in each call.

7715

7870

7737

7892

</pre>

7738

7893

7739

7894

<p>

7740

For this function, a '<code>^</code>' at the start of a pattern does not

7895

For this function, a caret '<code>^</code>' at the start of a pattern does not

7741

7896

work as an anchor, as this would prevent the iteration.

7742

7897

7743

7898

7884

8039

with length <code>i</code>.

7885

8040

7886

8041

8042

<p>

8043

If, after the translation of negative indices,

8044

<code>i</code> is less than 1,

8045

it is corrected to 1.

8046

If <code>j</code> is greater than the string length,

8047

it is corrected to that length.

8048

If, after these corrections,

8049

<code>i</code> is greater than <code>j</code>,

8050

the function returns the empty string.

8051

8052

7887

8053

7888

8054

7889

8055

<p>

8050

8216

8051

8217

<h4>Pattern:</h4><p>

8052

8218

A <em>pattern</em> is a sequence of pattern items.

8053

A '<code>^</code>' at the beginning of a pattern anchors the match at the

8219

A caret '<code>^</code>' at the beginning of a pattern anchors the match at the

8054

8220

beginning of the subject string.

8055

8221

A '<code>$</code>' at the end of a pattern anchors the match at the

8056

8222

end of the subject string.

8147

8313

<p>

8148

8314

Returns a new table with all parameters stored into keys 1, 2, etc.

8149

8315

and with a field "<code>n</code>" with the total number of parameters.

8150

Also returns, as a second result, the total number of parameters.

8151

8316

Note that the resulting table may not be a sequence.

8152

8317

8153

8318

8589

8754

8590

8755

8591

8756

<p>

8592

Returns the bitwise and of its operands.

8757

Returns the bitwise <em>and</em> of its operands.

8593

8758

8594

8759

8595

8760

8614

8779

8615

8780

8616

8781

<p>

8617

Returns the bitwise or of its operands.

8782

Returns the bitwise <em>or</em> of its operands.

8618

8783

8619

8784

8620

8785

8625

8790

8626

8791

<p>

8627

8792

Returns a boolean signaling

8628

whether the bitwise and of its operands is different from zero.

8793

whether the bitwise <em>and</em> of its operands is different from zero.

8629

8794

8630

8795

8631

8796

8635

8800

8636

8801

8637

8802

<p>

8638

Returns the bitwise exclusive or of its operands.

8803

Returns the bitwise <em>exclusive or</em> of its operands.

8639

8804

8640

8805

8641

8806

8845

9010

8846

9011

8847

9012

<p>

8848

<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename] ···)</code></a></h3>

9013

<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3>

8849

9014

8850

9015

8851

9016

<p>

8863

9028

In this case it does not close the file when the loop ends.

8864

9029

8865

9030

9031

<p>

9032

In case of errors this function raises the error,

9033

instead of returning an error code.

9034

9035

8866

9036

8867

9037

8868

9038

<p>

9007

9177

reads the file according to the given formats.

9008

9178

When no format is given,

9009

9179

uses "*l" as a default.

9010

Therefore, the construction

9180

As an example, the construction

9011

9181

9012

9182

<pre>

9013

9183

for c in file:lines(1) do <em>body</em> end

9014

9184

</pre><p>

9015

9185

will iterate over all characters of the file,

9016

9186

starting at the current position.

9017

(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file

9018

when the loop ends.)

9187

Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file

9188

when the loop ends.

9189

9190

9191

<p>

9192

In case of errors this function raises the error,

9193

instead of returning an error code.

9019

9194

9020

9195

9021

9196

9062

9237

</li>

9063

9238

9064

9239

<li><b><em>number</em>: </b>

9065

reads a string with up to this number of characters,

9240

reads a string with up to this number of bytes,

9066

9241

returning <b>nil</b> on end of file.

9067

9242

If number is zero,

9068

9243

it reads nothing and returns an empty string,

9074

9249

9075

9250

9076

9251

<p>

9077

<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3>

9252

<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>

9078

9253

9079

9254

9080

9255

<p>

9088

9263

<li><b>"<code>cur</code>": </b> base is current position;</li>

9089

9264

9090

9265

</ul><p>

9091

In case of success, function <code>seek</code> returns the final file position,

9266

In case of success, <code>seek</code> returns the final file position,

9092

9267

measured in bytes from the beginning of the file.

9093

If this function fails, it returns <b>nil</b>,

9268

If <code>seek</code> fails, it returns <b>nil</b>,

9094

9269

plus a string describing the error.

9095

9270

9096

9271

9123

9298

9124

9299

9125

9300

full buffering; output operation is performed only

9126

when the buffer is full (or when you explicitly <code>flush</code> the file

9127

(see <a href="#pdf-io.flush"><code>io.flush</code></a>)).

9301

when the buffer is full or when

9302

you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).

9128

9303

</li>

9129

9304

9130

9305

9146

9321

9147

9322

9148

9323

<p>

9149

Writes the value of each of its arguments to

9150

the <code>file</code>.

9324

Writes the value of each of its arguments to <code>file</code>.

9151

9325

The arguments must be strings or numbers.

9152

To write other values,

9153

use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>.

9154

9326

9155

9327

9156

9328

<p>

9202

9374

After this optional character,

9203

9375

if <code>format</code> is the string "<code>*t</code>",

9204

9376

then <code>date</code> returns a table with the following fields:

9205

<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31),

9206

<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61),

9377

<code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31),

9378

<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61),

9207

9379

<code>wday</code> (weekday, Sunday is 1),

9208

9380

<code>yday</code> (day of the year),

9209

9381

and <code>isdst</code> (daylight saving flag, a boolean).

9224

9396

(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).

9225

9397

9226

9398

9399

<p>

9400

On some systems,

9401

this function may be not thread safe.

9402

9403

9227

9404

9228

9405

9229

9406

<p>

9314

9491

Deletes the file (or empty directory, on POSIX systems)

9315

9492

with the given name.

9316

9493

If this function fails, it returns <b>nil</b>,

9317

plus a string describing the error.

9494

plus a string describing the error and the error code.

9318

9495

9319

9496

9320

9497

9326

9503

<p>

9327

9504

Renames file or directory named <code>oldname</code> to <code>newname</code>.

9328

9505

If this function fails, it returns <b>nil</b>,

9329

plus a string describing the error.

9506

plus a string describing the error and the error code.

9330

9507

9331

9508

9332

9509

9337

9514

9338

9515

<p>

9339

9516

Sets the current locale of the program.

9340

<code>locale</code> is a string specifying a locale;

9517

<code>locale</code> is a system-dependent string specifying a locale;

9341

9518

<code>category</code> is an optional string describing which category to change:

9342

9519

<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,

9343

9520

<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;

9369

9546

Returns the current time when called without arguments,

9370

9547

or a time representing the date and time specified by the given table.

9371

9548

This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,

9372

and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code>

9373

(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function).

9549

and may have fields

9550

<code>hour</code> (default is 12),

9551

<code>min</code> (default is 0),

9552

<code>sec</code> (default is 0),

9553

and <code>isdst</code> (default is <b>nil</b>).

9554

For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.

9374

9555

9375

9556

9376

9557

<p>

9380

9561

of seconds since some given start time (the "epoch").

9381

9562

In other systems, the meaning is not specified,

9382

9563

and the number returned by <code>time</code> can be used only as an argument to

9383

<code>date</code> and <code>difftime</code>.

9564

<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.

9384

9565

9385

9566

9386

9567

9421

9602

9422

9603

<p>

9423

9604

This library provides

9424

the functionality of the debug interface to Lua programs.

9605

the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs.

9425

9606

You should exert care when using this library.

9426

Several of these functions

9607

Several of its functions

9427

9608

violate basic assumptions about Lua code

9428

9609

(e.g., that variables local to a function

9429

9610

cannot be accessed from outside;

9458

9639

9459

9640

<p>

9460

9641

Note that commands for <code>debug.debug</code> are not lexically nested

9461

within any function, and so have no direct access to local variables.

9642

within any function and so have no direct access to local variables.

9462

9643

9463

9644

9464

9645

9477

9658

9478

9659

9479

9660

<p>

9480

<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3>

9661

<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>

9481

9662

9482

9663

9483

9664

<p>

9484

9665

Returns a table with information about a function.

9485

You can give the function directly,

9486

or you can give a number as the value of <code>function</code>,

9487

which means the function running at level <code>function</code> of the call stack

9666

You can give the function directly

9667

or you can give a number as the value of <code>f</code>,

9668

which means the function running at level <code>f</code> of the call stack

9488

9669

of the given thread:

9489

9670

level 0 is the current function (<code>getinfo</code> itself);

9490

9671

level 1 is the function that called <code>getinfo</code>

9491

9672

(except for tail calls, which do not count on the stack);

9492

9673

and so on.

9493

If <code>function</code> is a number larger than the number of active functions,

9674

If <code>f</code> is a number larger than the number of active functions,

9494

9675

then <code>getinfo</code> returns <b>nil</b>.

9495

9676

9496

9677

9554

9735

9555

9736

9556

9737

<p>

9557

<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3>

9738

<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>

9558

9739

9559

9740

9560

9741

<p>

9561

Returns the metatable of the given <code>object</code>

9742

Returns the metatable of the given <code>value</code>

9562

9743

or <b>nil</b> if it does not have a metatable.

9563

9744

9564

9745

9575

9756

9576

9757

9577

9758

<p>

9578

<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3>

9759

<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>

9579

9760

9580

9761

9581

9762

<p>

9582

9763

This function returns the name and the value of the upvalue

9583

with index <code>up</code> of the function <code>func</code>.

9764

with index <code>up</code> of the function <code>f</code>.

9584

9765

The function returns <b>nil</b> if there is no upvalue with the given index.

9585

9766

9586

9767

9662

9843

9663

9844

9664

9845

<p>

9665

<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3>

9846

<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>

9666

9847

9667

9848

9668

9849

<p>

9669

Sets the metatable for the given <code>object</code> to the given <code>table</code>

9850

Sets the metatable for the given <code>value</code> to the given <code>table</code>

9670

9851

(which can be <b>nil</b>).

9671

Returns <code>object</code>.

9852

Returns <code>value</code>.

9672

9853

9673

9854

9674

9855

9675

9856

9676

9857

<p>

9677

<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3>

9858

<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>

9678

9859

9679

9860

9680

9861

<p>

9681

9862

This function assigns the value <code>value</code> to the upvalue

9682

with index <code>up</code> of the function <code>func</code>.

9863

with index <code>up</code> of the function <code>f</code>.

9683

9864

The function returns <b>nil</b> if there is no upvalue

9684

9865

with the given index.

9685

9866

Otherwise, it returns the name of the upvalue.

9723

9904

9724

9905

9725

9906

<p>

9726

<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (function, n)</code></a></h3>

9907

<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>

9727

9908

9728

9909

9729

9910

<p>

9743

9924

9744

9925

9745

9926

<p>

9746

<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (func1, n1, func2, n2)</code></a></h3>

9927

<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>

9747

9928

9748

9929

9749

9930

<p>

9750

Make the <code>n1</code>-th upvalue of the Lua closure <code>func1</code>

9751

refer to the <code>n2</code>-th upvalue of the Lua closure <code>func2</code>.

9931

Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>

9932

refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.

9752

9933

9753

9934

9754

9935

9779

9960

<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>

9780

9961

<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>

9781

9962

<li><b><code>-v</code>: </b> prints version information;</li>

9963

<li><b><code>-E</code>: </b> ignores environment variables;</li>

9782

9964

<li><b><code>--</code>: </b> stops handling options;</li>

9783

9965

<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>

9784

9966

</ul><p>

9791

9973

9792

9974

9793

9975

<p>

9794

Before running any argument,

9976

When called without option <code>-E</code>,

9795

9977

the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_2"><code>LUA_INIT_5_2</code></a>

9796

(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined).

9797

If its format is <code>@<em>filename</em></code>,

9978

(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined)

9979

before running any argument.

9980

If the variable content has the format <code>@<em>filename</em></code>,

9798

9981

then <code>lua</code> executes the file.

9799

9982

Otherwise, <code>lua</code> executes the string itself.

9800

9983

9801

9984

9802

9985

<p>

9803

All options are handled in order, except <code>-i</code>.

9986

When called with option <code>-E</code>,

9987

besides ignoring <code>LUA_INIT</code>,

9988

the interpreter also resets the values of

9989

<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>

9990

with the default paths defined in <code>luaconf.h</code>,

9991

in effect ignoring the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>.

9992

9993

9994

<p>

9995

All options are handled in order, except <code>-i</code> and <code>-E</code>.

9804

9996

For instance, an invocation like

9805

9997

9806

9998

<pre>

9807

9999

$ lua -e'a=1' -e 'print(a)' script.lua

9808

10000

</pre><p>

9809

will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'),

10001

will first set <code>a</code> to 1, then print the value of <code>a</code>,

9810

10002

and finally run the file <code>script.lua</code> with no arguments.

9811

(Here <code>$</code> is the shell prompt. Your prompt can be different.)

10003

(Here <code>$</code> is the shell prompt. Your prompt may be different.)

9812

10004

9813

10005

9814

10006

<p>

9835

10027

[1] = "t1", [2] = "t2" }

9836

10028

</pre><p>

9837

10029

and finally runs the file <code>b.lua</code>.

9838

The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ···

10030

The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ...

9839

10031

as arguments;

9840

10032

it can also access these arguments with the vararg expression '<code>...</code>'.

9841

10033

9862

10054

When finishing normally,

9863

10055

the interpreter closes its main Lua state

9864

10056

(see <a href="#lua_close"><code>lua_close</code></a>).

9865

The script can avoid this step by terminating

9866

through <a href="#pdf-os.exit"><code>os.exit</code></a>.

9867

9868

9869

<p>

9870

If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,

9871

then its value is used as the prompt.

9872

Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,

9873

its value is used as the secondary prompt

9874

(issued during incomplete statements).

9875

Therefore, both prompts can be changed directly on the command line

9876

or in any Lua programs by assigning to <code>_PROMPT</code>.

9877

See the next example:

9878

9879

<pre>

9880

$ lua -e"_PROMPT='myprompt> '" -i

9881

</pre><p>

9882

(The outer pair of quotes is for the shell,

9883

the inner pair is for Lua.)

9884

Note the use of <code>-i</code> to enter interactive mode;

9885

otherwise,

9886

the program would just end silently

9887

right after the assignment to <code>_PROMPT</code>.

10057

The script can avoid this step by

10058

calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.

9888

10059

9889

10060

9890

10061

<p>

9900

10071

#!/usr/local/bin/lua

9901

10072

</pre><p>

9902

10073

(Of course,

9903

the location of the Lua interpreter can be different in your machine.

10074

the location of the Lua interpreter may be different in your machine.

9904

10075

If <code>lua</code> is in your <code>PATH</code>,

9905

10076

then

9906

10077

9914

10085

<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1>

9915

10086

9916

10087

<p>

9917

Here we list the incompatibilities that you can find when moving a program

10088

Here we list the incompatibilities that you may find when moving a program

9918

10089

from Lua 5.1 to Lua 5.2.

9919

You can avoid some incompatibilities compiling Lua with

10090

You can avoid some incompatibilities by compiling Lua with

9920

10091

appropriate options (see file <code>luaconf.h</code>).

9921

10092

However,

9922

10093

all these compatibility options will be removed in the next version of Lua.

9934

10105

9935

10106

9936

10107

<p>

9937

C functions do not have environments any more.

10108

C functions no longer have environments.

9938

10109

Use an upvalue with a shared table if you need to keep

9939

10110

shared state among several C functions.

9940

10111

(You may use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> to open a C library

9964

10135

<li>

9965

10136

The event <em>tail return</em> in debug hooks was removed.

9966

10137

Instead, tail calls generate a special new event,

9967

<em>tail call</em>, so that the debugger can know there will

9968

not be a corresponding return event.

10138

<em>tail call</em>, so that the debugger can know that

10139

there will not be a corresponding return event.

9969

10140

</li>

9970

10141

9971

10142

<li>

9985

10156

9986

10157

<li>

9987

10158

Function <code>module</code> is deprecated.

9988

Modules are not expected to set global variables anymore,

9989

and it is easy to set up a module with regular Lua code.

10159

It is easy to set up a module with regular Lua code.

10160

Modules are not expected to set global variables.

9990

10161

</li>

9991

10162

9992

10163

<li>

10036

10207

(<a href="#pdf-load"><code>load</code></a> and <a href="#pdf-loadfile"><code>loadfile</code></a>)

10037

10208

are potentially insecure when loading untrusted binary data.

10038

10209

(Actually, those functions were already insecure because

10039

of bugs in the verification algorithm.)

10210

of flaws in the verification algorithm.)

10040

10211

When in doubt,

10041

use the <code>mode</code> argument in function <a href="#pdf-load"><code>load</code></a>

10042

to restrict it to loading textual chunks.

10212

use the <code>mode</code> argument of those functions

10213

to restrict them to loading textual chunks.

10214

</li>

10215

10216

<li>

10217

The standard paths in the official distribution may

10218

change between versions.

10043

10219

</li>

10044

10220

10045

10221

</ul>

10060

10236

Pseudoindex <code>LUA_ENVIRONINDEX</code>

10061

10237

and functions <code>lua_getfenv</code>/<code>lua_setfenv</code>

10062

10238

were removed,

10063

as C functions do not have environments any more.

10239

as C functions no longer have environments.

10064

10240

</li>

10065

10241

10066

10242

<li>

10067

10243

Function <code>luaL_register</code> is deprecated.

10068

Use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> so that your module does not

10069

create globals anymore.

10244

Use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> so that your module does not create globals.

10070

10245

(Modules are not expected to set global variables anymore.)

10071

10246

</li>

10072

10247

10081

10256

10082

10257

<li>

10083

10258

Finalizers (<code>__gc</code> metamethods) for userdata are called in the

10084

reverse order that they were marked,

10259

reverse order that they were marked for finalization,

10085

10260

not that they were created (see <a href="#2.5.1">§2.5.1</a>).

10086

10261

(Most userdata are marked immediately after they are created.)

10087

10262

Moreover,

10110

10285

Function <code>lua_objlen</code> was renamed <a href="#lua_rawlen"><code>lua_rawlen</code></a>.

10111

10286

</li>

10112

10287

10288

<li>

10289

Function <a href="#lua_load"><code>lua_load</code></a> has an extra parameter, <code>mode</code>.

10290

Pass <code>NULL</code> to simulate the old behavior.

10291

</li>

10292

10113

10293

</ul>

10114

10294

10115

10295

10202

10382

<HR>

10203

10383

10204

10384

Last update:

10205

Fri Jul 8 17:11:02 BRT 2011

10385

Mon Dec 5 11:07:57 BRST 2011

10206

10386

</SMALL>

10207

10387

<!--

10208

Last change: revised for Lua 5.2.0 (beta)

10388

Last change: revised for Lua 5.2.0

10209

10389

-->

10210

10390

10211

10391

</body></html>