Download the full version of the ebook at ebookfinal.

com

Programming in Lua 3rd Edition Roberto

Ierusalimschy

https://ebookfinal.com/download/programming-in-lua-3rd-
edition-roberto-ierusalimschy/

OR CLICK BUTTON

DOWNLOAD EBOOK

Download more ebook instantly today at https://ebookfinal.com

Instant digital products (PDF, ePub, MOBI) available
Download now and explore formats that suit you...

Programming in Lua 2nd Edition Roberto Ierusalimschy

https://ebookfinal.com/download/programming-in-lua-2nd-edition-
roberto-ierusalimschy/

ebookfinal.com

Beginning Lua Programming 1st Edition Jung

https://ebookfinal.com/download/beginning-lua-programming-1st-edition-
jung/

ebookfinal.com

LÖVE for Lua Game Programming 1st Edition Akinlaja

https://ebookfinal.com/download/love-for-lua-game-programming-1st-
edition-akinlaja/

ebookfinal.com

Beginning Linux programming 3rd Edition Neil Matthew

https://ebookfinal.com/download/beginning-linux-programming-3rd-
edition-neil-matthew/

ebookfinal.com
CNC programming handbook a comprehensive guide to
practical CNC programming 3rd ed Edition Smid

https://ebookfinal.com/download/cnc-programming-handbook-a-
comprehensive-guide-to-practical-cnc-programming-3rd-ed-edition-smid/

ebookfinal.com

Android Programming Tutorials 3rd Edition Mark L Murphy

https://ebookfinal.com/download/android-programming-tutorials-3rd-
edition-mark-l-murphy/

ebookfinal.com

Practical Programming for Strength Training 3rd Edition

Rippetoe

https://ebookfinal.com/download/practical-programming-for-strength-
training-3rd-edition-rippetoe/

ebookfinal.com

Beginning Programming for Dummies 3rd ed Edition Wallace

Wang

https://ebookfinal.com/download/beginning-programming-for-dummies-3rd-
ed-edition-wallace-wang/

ebookfinal.com

Programming Languages Principles and Practices 3rd Edition

Kenneth C. Louden

https://ebookfinal.com/download/programming-languages-principles-and-
practices-3rd-edition-kenneth-c-louden/

ebookfinal.com
Programming in Lua
Third Edition
Programming in Lua
Third Edition

Roberto Ierusalimschy
PUC-Rio, Brazil

Lua.org

Rio de Janeiro
ProgramminginLua,ThirdEdition
by Roberto Ierusalimschy

ISBN 978-85-903798-5-0

Copyright c 2013, 2003 by Roberto Ierusalimschy. All rights reserved.

The author can be contacted at [email protected].

Book cover by Luiza Novaes. Lua logo design by Alexandre Nako. Typeset by
the author using LATEX.

Although the author used his best efforts preparing this book, he assumes no
responsibility for errors or omissions, or for any damage that may result from
the use of the information presented here. All product names mentioned in this
book are trademarks of their respective owners.

CIP–BibliotecadoDepartamentodeInformática,PUC-Rio
Ierusalimschy, Roberto
I22 Programming in Lua / Roberto Ierusalimschy. – 3th ed.
– Rio de Janeiro, 2013.
xviii, 348 p. : 25 cm.
Includes index.
ISBN 978-85-903798-5-0
1. Lua (Programming language). I. Title.
005.133 – dc20

Feisty Duck Digital

Book Distribution
www.feistyduck.com
to Ida, Noemi, and Ana Lucia
 Contents

Preface xiii

I The Language 1
1 Getting Started 3
1.1 Chunks 4
1.2 Some Lexical Conventions 5
1.3 Global Variables 6
1.4 The Stand-Alone Interpreter 6
Exercises 8

2 Types and Values 9

2.1 Nil 10
2.2 Booleans 10
2.3 Numbers 10
2.4 Strings 11
2.5 Tables 15
2.6 Functions 18
2.7 Userdata and Threads 18
Exercises 18

3 Expressions 21
3.1 Arithmetic Operators 21
3.2 Relational Operators 22
3.3 Logical Operators 23
3.4 Concatenation 23
3.5 The Length Operator 24
3.6 Precedence 25
3.7 Table Constructors 26
Exercises 28

vii
viii Contents

4 Statements 29
4.1 Assignment 29
4.2 Local Variables and Blocks 30
4.3 Control Structures 32
4.4 break, return, and goto 36
Exercises 38

5 Functions 41
5.1 Multiple Results 42
5.2 Variadic Functions 46
5.3 Named Arguments 48
Exercises 49

6 More about Functions 51

6.1 Closures 53
6.2 Non-Global Functions 56
6.3 Proper Tail Calls 58
Exercises 59

7 Iterators and the Generic for 61

7.1 Iterators and Closures 61
7.2 The Semantics of the Generic for 63
7.3 Stateless Iterators 64
7.4 Iterators with Complex State 66
7.5 True Iterators 67
Exercises 68

8 Compilation, Execution, and Errors 71

8.1 Compilation 71
8.2 Precompiled Code 75
8.3 C Code 76
8.4 Errors 77
8.5 Error Handling and Exceptions 79
8.6 Error Messages and Tracebacks 79
Exercises 81

9 Coroutines 83
9.1 Coroutine Basics 83
9.2 Pipes and Filters 86
9.3 Coroutines as Iterators 89
9.4 Non-Preemptive Multithreading 91
Exercises 95
 ix

10 Complete Examples 97
10.1 The Eight-Queen Puzzle 97
10.2 Most Frequent Words 99
10.3 Markov Chain Algorithm 101
Exercises 102

II Tables and Objects 105

11 Data Structures 107
11.1 Arrays 107
11.2 Matrices and Multi-Dimensional Arrays 108
11.3 Linked Lists 110
11.4 Queues and Double Queues 110
11.5 Sets and Bags 111
11.6 String Buffers 113
11.7 Graphs 114
Exercises 116

12 Data Files and Persistence 117

12.1 Data Files 117
12.2 Serialization 119
Exercises 125

13 Metatables and Metamethods 127

13.1 Arithmetic Metamethods 128
13.2 Relational Metamethods 131
13.3 Library-Defined Metamethods 132
13.4 Table-Access Metamethods 133
Exercises 138

14 The Environment 139

14.1 Global Variables with Dynamic Names 139
14.2 Global-Variable Declarations 141
14.3 Non-Global Environments 142
14.4 Using _ENV 144
14.5 _ENV and load 147
Exercises 148

15 Modules and Packages 151

15.1 The require Function 153
15.2 The Basic Approach for Writing Modules in Lua 156
15.3 Using Environments 158
15.4 Submodules and Packages 159
Exercises 161
x Contents

16 Object-Oriented Programming 163

16.1 Classes 165
16.2 Inheritance 166
16.3 Multiple Inheritance 168
16.4 Privacy 170
16.5 The Single-Method Approach 172
Exercises 173

17 Weak Tables and Finalizers 175

17.1 Weak Tables 175
17.2 Memoize Functions 177
17.3 Object Attributes 179
17.4 Revisiting Tables with Default Values 179
17.5 Ephemeron Tables 180
17.6 Finalizers 181
Exercises 185

III The Standard Libraries 187

18 The Mathematical Library 189
Exercises 190

19 The Bitwise Library 191

Exercises 194

20 The Table Library 195

20.1 Insert and Remove 195
20.2 Sort 196
20.3 Concatenation 197
Exercises 198

21 The String Library 199

21.1 Basic String Functions 199
21.2 Pattern-Matching Functions 201
21.3 Patterns 204
21.4 Captures 208
21.5 Replacements 209
21.6 Tricks of the Trade 213
21.7 Unicode 216
Exercises 218

22 The I/O Library 221

22.1 The Simple I/O Model 221
22.2 The Complete I/O Model 224
 xi

22.3 Other Operations on Files 228

Exercises 229

23 The Operating System Library 231

23.1 Date and Time 231
23.2 Other System Calls 233
Exercises 235

24 The Debug Library 237

24.1 Introspective Facilities 237
24.2 Hooks 242
24.3 Profiles 243
Exercises 245

IV The C API 247

25 An Overview of the C API 249
25.1 A First Example 250
25.2 The Stack 253
25.3 Error Handling with the C API 258
Exercises 260

26 Extending Your Application 261

26.1 The Basics 261
26.2 Table Manipulation 263
26.3 Calling Lua Functions 267
26.4 A Generic Call Function 269
Exercises 270

27 Calling C from Lua 273

27.1 C Functions 273
27.2 Continuations 275
27.3 C Modules 278
Exercises 280

28 Techniques for Writing C Functions 281

28.1 Array Manipulation 281
28.2 String Manipulation 283
28.3 Storing State in C Functions 286
Exercises 292

29 User-Defined Types in C 293

29.1 Userdata 294
29.2 Metatables 296
xii Contents

29.3 Object-Oriented Access 299

29.4 Array Access 300
29.5 Light Userdata 301
Exercises 302

30 Managing Resources 305

30.1 A Directory Iterator 305
30.2 An XML Parser 307
Exercises 316

31 Threads and States 319

31.1 Multiple Threads 319
31.2 Lua States 323
Exercises 331

32 Memory Management 333

32.1 The Allocation Function 333
32.2 The Garbage Collector 335
Exercises 338

Index 339
 Preface

When Waldemar, Luiz, and I started the development of Lua, back in 1993, we
could hardly imagine that it would spread as it did. Started as an in-house
language for two specific projects, currently Lua is widely used in all areas that
can benefit from a simple, extensible, portable, and efficient scripting language,
such as embedded systems, mobile devices, and, of course, games.
We designed Lua, from the beginning, to be integrated with software written
in C/C++ and other conventional languages. This integration brings many
benefits. Lua is a tiny and simple language, partly because it does not try to
do what C is already good for, such as sheer performance, low-level operations,
and interface with third-party software. Lua relies on C for these tasks. What
Lua does offer is what C is not good for: a good distance from the hardware,
dynamic structures, no redundancies, and ease of testing and debugging. For
these goals, Lua has a safe environment, automatic memory management, and
good facilities for handling strings and other kinds of data with dynamic size.
Part of the power of Lua comes from its libraries. This is not by chance. After
all, one of the main strengths of Lua is its extensibility. Many features con-
tribute to this strength. Dynamic typing allows a great degree of polymorphism.
Automatic memory management simplifies interfaces, because there is no need
to decide who is responsible for allocating and deallocating memory, or how to
handle overflows. Higher-order functions and anonymous functions allow a high
degree of parameterization, making functions more versatile.
More than an extensible language, Lua is also a glue language. Lua supports
a component-based approach to software development, where we create an ap-
plication by gluing together existing high-level components. These components
are written in a compiled, statically typed language, such as C or C++; Lua is the
glue that we use to compose and connect these components. Usually, the compo-
nents (or objects) represent more concrete, low-level concepts (such as widgets
and data structures) that are not subject to many changes during program de-
velopment, and that take the bulk of the CPU time of the final program. Lua
gives the final shape of the application, which will probably change a lot dur-
ing the life cycle of the product. However, unlike other glue technologies, Lua
is a full-fledged language as well. Therefore, we can use Lua not only to glue

xiii
xiv Preface

components, but also to adapt and reshape them, and to create completely new
components.
Of course, Lua is not the only scripting language around. There are other
languages that you can use for more or less the same purposes. Nevertheless,
Lua offers a set of features that makes it your best choice for many tasks and
gives it a unique profile:
Extensibility: Lua’s extensibility is so remarkable that many people regard Lua
not as a language, but as a kit for building domain-specific languages. We
designed Lua from scratch to be extended, both through Lua code and
through external C code. As a proof of concept, Lua implements most of
its own basic functionality through external libraries. It is really easy to
interface Lua with C/C++, and Lua has been used integrated with several
other languages as well, such as Fortran, Java, Smalltalk, Ada, C#, and
even with other scripting languages, such as Perl and Python.
Simplicity: Lua is a simple and small language. It has few (but powerful)
concepts. This simplicity makes Lua easy to learn and contributes to its
small size. Its complete distribution (source code, manual, plus binaries
for some platforms) fits comfortably in a floppy disk.
Efficiency: Lua has a quite efficient implementation. Independent benchmarks
show Lua as one of the fastest languages in the realm of scripting lan-
guages.
Portability: When we talk about portability, we are talking about running Lua
on all platforms we have ever heard about: all flavors of UNIX and Win-
dows, PlayStation, Xbox, Mac OS X and iOS, Android, Kindle Fire, NOOK,
Haiku, QUALCOMM Brew, IBM mainframes, RISC OS, Symbian OS, Rab-
bit processors, Raspberry Pi, Arduino, and many more. The source code for
each of these platforms is virtually the same. Lua does not use conditional
compilation to adapt its code to different machines; instead, it sticks to
the standard ANSI (ISO) C. This way, you do not usually need to adapt it
to a new environment: if you have an ANSI C compiler, you just have to
compile Lua, out of the box.

Audience
Lua users typically fall into three broad groups: those that use Lua already
embedded in an application program, those that use Lua stand alone, and those
that use Lua and C together.
Many people use Lua embedded in an application program, such as Adobe
Lightroom, Nmap, or World of Warcraft. These applications use the Lua–C API
to register new functions, to create new types, and to change the behavior of
some language operations, configuring Lua for their specific domains. Fre-
quently, the users of such applications do not even know that Lua is an inde-
pendent language adapted for a particular domain. For instance, many devel-
opers of plug-ins for Lightroom do not know about other uses of the language;
 xv

Nmap users tend to think of Lua as the language of the Nmap Scripting Engine;
players of World of Warcraft may regard Lua as a language exclusive to that
game.
Lua is useful also as a stand-alone language, not only for text-processing and
one-shot little programs, but increasingly for medium-to-large projects, too. For
such uses, the main functionality of Lua comes from libraries. The standard
libraries, for instance, offer basic pattern matching and other functions for
string handling. As Lua improves its support for libraries, there has been a
proliferation of external packages. Lua Rocks, a deployment and management
system for Lua modules, currently features more than 150 packages.
Finally, there are those programmers that work on the other side of the
bench, writing applications that use Lua as a C library. Those people will
program more in C than in Lua, although they need a good understanding of
Lua to create interfaces that are simple, easy to use, and well integrated with
the language.
This book has much to offer to all these people. The first part covers the
language itself, showing how we can explore all its potential. We focus on
different language constructs and use numerous examples and exercises to show
how to use them for practical tasks. Some chapters in this part cover basic
concepts, such as control structures, while others cover topics more advanced,
such as iterators and coroutines.
The second part is entirely devoted to tables, the sole data structure in Lua.
Its chapters discuss data structures, persistence, packages, and object-oriented
programming. There we will unveil the real power of the language.
The third part presents the standard libraries. This part is particularly
useful for those that use Lua as a stand-alone language, although many other
applications also incorporate all or part of the standard libraries. This part
devotes one chapter to each standard library: the mathematical library, the
bitwise library, the table library, the string library, the I/O library, the operating
system library, and the debug library.
Finally, the last part of the book covers the API between Lua and C, for those
that use C to get the full power of Lua. The flavor of this part is necessarily
quite different from the rest of the book. There, we will be programming in C,
not in Lua; therefore, we will be wearing a different hat. For some readers, the
discussion of the C API may be of marginal interest; for others, it may be the
most relevant part of this book.

About the Third Edition

This book is an updated and expanded version of the second edition of Program-
ming in Lua (also known as the PiL 2 book). Although the book structure is
virtually the same, this new edition has substantial new material.
First, I have updated the whole book to Lua 5.2. Of particular relevance is the
chapter about environments, which was mostly rewritten. I also rewrote several
examples to show how to benefit from the new features offered by Lua 5.2.
xvi Preface

Nevertheless, I clearly marked the differences from Lua 5.1, so you can use the
book for that version too.
Second, and more important, I have added exercises to all chapters of the
book. These exercises range from simple questions about the language to full
small-size projects. Several exercises illustrate important aspects of program-
ming in Lua and are as important as the examples to expand your toolbox of
useful techniques.
As we did with the first and second editions of Programming in Lua, we self-
published this third edition. Despite the limited marketing, this avenue brings
several benefits: we have total control over the book contents; we keep the full
rights to offer the book in other forms; we have freedom to choose when to release
another edition; and we can ensure that the book does not go out of print.

Other Resources
The reference manual is a must for anyone who wants to really learn a language.
This book does not replace the Lua reference manual. Quite the opposite, they
complement each other. The manual only describes Lua. It shows neither
examples nor a rationale for the constructs of the language. On the other hand,
it describes the whole language; this book skips over seldom-used dark corners of
Lua. Moreover, the manual is the authoritative document about Lua. Wherever
this book disagrees with the manual, trust the manual. To get the manual and
more information about Lua, visit the Lua site at http://www.lua.org.
You can also find useful information at the Lua users’ site, kept by the
community of users at http://lua-users.org. Among other resources, it offers
a tutorial, a list of third-party packages and documentation, and an archive of
the official Lua mailing list.
This book describes Lua 5.2, although most of its contents also apply to
Lua 5.1 and Lua 5.0. The few differences between Lua 5.2 and older Lua 5
versions are clearly marked in the text. If you are using a more recent version
(released after the book), check the corresponding manual for occasional differ-
ences between versions. If you are using a version older than 5.2, this is a good
time to consider an upgrade.

A Few Typographical Conventions

The book encloses “literal strings” between double quotes and single charac-
ters, such as ‘a’, between single quotes. Strings that are used as patterns are
also enclosed between single quotes, like ‘[%w_]*’. The book uses a typewriter
font both for chunks of code and for identifiers. For reservedwords , it uses
a boldface font. Larger chunks of code are shown in display style:
-- program "Hello World"
print("Hello World") --> Hello World
The notation --> shows the output of a statement or, occasionally, the result of
an expression:
 xvii

print(10) --> 10
13 + 3 --> 16
Because a double hyphen (--) starts a comment in Lua, there is no problem
if you include these annotations in your programs. Finally, the book uses the
notation <--> to indicate that something is equivalent to something else:

this <--> that

Running the Examples

You will need a Lua interpreter to run the examples in this book. Ideally, you
should use Lua 5.2, but most of the examples run also on Lua 5.1 without
modifications.
The Lua site (http://www.lua.org) keeps the source code for the interpreter.
If you have a C compiler and a working knowledge of how to compile C code
in your machine, you should try to install Lua from its source code; it is really
easy. The Lua Binaries site (search for luabinaries) offers precompiled Lua
interpreters for most major platforms. If you use Linux or another UNIX-like
system, you may check the repository of your distribution; several distributions
already offer a package with Lua. For Windows, a good option is Lua for Win-
dows (search for luaforwindows), which is a “batteries-included environment”
for Lua. It includes the interpreter and an integrated text editor, plus many
libraries.
If you are using Lua embedded in an application, such as WoW or Nmap,
you may need to refer to the application manual (or to a “local guru”) to learn
how to run your programs. Nevertheless, Lua is still the same language; most
things that we will see in this book are valid regardless of how you are using
Lua. Nevertheless, I recommend that you start your study of Lua using the
stand-alone interpreter to run your first examples and experiments.

Acknowledgments
It is almost ten years since I published the first edition of this book. Several
friends and institutions have helped me along this journey.
As always, Luiz Henrique de Figueiredo and Waldemar Celes, Lua coauthors,
offered all kinds of help. André Carregal, Asko Kauppi, Brett Kapilik, Diego
Nehab, Edwin Moragas, Fernando Jefferson, Gavin Wraith, John D. Ramsdell,
and Norman Ramsey provided invaluable suggestions and useful insights for
diverse editions of this book.
Luiza Novaes, head of the Arts & Design Department at PUC-Rio, managed
to find some time in her busy schedule to create an ideal cover for this edition.
Lightning Source, Inc. proved a reliable and efficient option for printing and
distributing the book. Without them, the option of self-publishing the book
would not be an option.
xviii Preface

The Center for Latin American Studies at Stanford University provided me

with a much-needed break from regular work, in a stimulating environment,
during which I did most of the work for this third edition.
I also would like to thank the Pontifical Catholic University of Rio de Janeiro
(PUC-Rio) and the Brazilian National Research Council (CNPq) for their contin-
uous support to my work.
Finally, I must express my deep gratitude to Noemi Rodriguez, for all kinds
of help (technical and non-technical) and for illumining my life.
 Part I

The Language
 Getting Started
1
To keep with the tradition, our first program in Lua just prints “Hello World”:

print("Hello World")

If you are using the stand-alone Lua interpreter, all you have to do to run your
first program is to call the interpreter — usually named lua or lua5.2 — with the
name of the text file that contains your program. If you save the above program
in a file hello.lua, the following command should run it:

% lua hello.lua
As a more complex example, the next program defines a function to compute
the factorial of a given number, asks the user for a number, and prints its
factorial:
-- defines a factorial function
function fact (n)
if n == 0 then
return 1
else
return n * fact(n-1)
end
end
print("enter a number:")
a = io.read("*n") -- reads a number
print(fact(a))

3
4 Chapter 1 Getting Started

1.1 Chunks
Each piece of code that Lua executes, such as a file or a single line in interac-
tive mode, is called a chunk. A chunk is simply a sequence of commands (or
statements).
Lua needs no separator between consecutive statements, but you can use
a semicolon if you wish. My personal convention is to use semicolons only to
separate two or more statements written in the same line. Line breaks play no
role in Lua’s syntax; for instance, the following four chunks are all valid and
equivalent:
a = 1
b = a*2
a = 1;
b = a*2;
a = 1; b = a*2
a = 1 b = a*2 -- ugly, but valid

A chunk can be as simple as a single statement, such as in the “Hello World”

example, or it can be composed of a mix of statements and function definitions
(which are actually assignments, as we will see later), such as the factorial
example. A chunk can be as large as you wish. Because Lua is used also as a
data-description language, chunks with several megabytes are not uncommon.
The Lua interpreter has no problems at all with large chunks.
Instead of writing your program to a file, you can run the stand-alone inter-
preter in interactive mode. If you call lua without any arguments, you will get
its prompt:
% lua
Lua 5.2 Copyright (C) 1994-2012 Lua.org, PUC-Rio
>
Thereafter, each command that you type (such as print"Hello World") executes
immediately after you enter it. To exit the interactive mode and the interpreter,
just type the end-of-file control character (ctrl-D in UNIX, ctrl-Z in Windows),
or call the exit function, from the Operating System library — you have to type
os.exit().
In interactive mode, Lua usually interprets each line that you type as a
complete chunk. However, if it detects that the line does not form a complete
chunk, it waits for more input, until it has a complete chunk. This way, you
can enter a multi-line definition, such as the factorial function, directly in
interactive mode. However, it is usually more convenient to put such definitions
in a file and then call Lua to run the file.
You can use the -i option to instruct Lua to start an interactive session after
running the given chunk:
% lua -i prog
1.2 Some Lexical Conventions 5

A command line like this one will run the chunk in file prog and then prompt you
for interaction. This is especially useful for debugging and manual testing. At
the end of this chapter, we will see other options for the stand-alone interpreter.
Another way to run chunks is with the dofile function, which immediately
executes a file. For instance, suppose you have a file lib1.lua with the following
code:
function norm (x, y)
return (x^2 + y^2)^0.5
end
function twice (x)
return 2*x
end
Then, in interactive mode, you can type
> dofile("lib1.lua") -- load your library
> n = norm(3.4, 1.0)
> print(twice(n)) --> 7.0880180586677
The dofile function is useful also when you are testing a piece of code. You
can work with two windows: one is a text editor with your program (in a file
prog.lua, say) and the other is a console running Lua in interactive mode. After
saving a modification in your program, you execute dofile("prog.lua") in the
Lua console to load the new code; then you can exercise the new code, calling its
functions and printing the results.

1.2 Some Lexical Conventions

Identifiers (or names) in Lua can be any string of letters, digits, and underscores,
not beginning with a digit; for instance
i j i10 _ij
aSomewhatLongName _INPUT
You should avoid identifiers starting with an underscore followed by one or more
upper-case letters (e.g., _VERSION); they are reserved for special uses in Lua.
Usually, I reserve the identifier _ (a single underscore) for dummy variables.
In older versions of Lua, the concept of what is a letter depended on the
locale. However, such letters make your program unsuitable to run in systems
that do not support that locale. Lua 5.2 accepts only the ranges A-Z and a-z as
letters to be used in identifiers.
The following words are reserved; we cannot use them as identifiers:
and break do else elseif
end false goto for function
if in local nil not
or repeat return then true
until while
6 Chapter 1 Getting Started

Lua is case-sensitive: and is a reserved word, but And and AND are two other
different identifiers.
A comment starts anywhere with a double hyphen (--) and runs until the
end of the line. Lua also offers block comments, which start with --[[ and run
until the next ]].1 A common trick to comment out a piece of code is to enclose
the code between --[[ and --]], like here:
--[[
print(10) -- no action (commented out)
--]]
To reactivate the code, we add a single hyphen to the first line:
---[[
print(10) --> 10
--]]
In the first example, the --[[ in the first line starts a block comment, and
the double hyphen in the last line is still inside that comment. In the second
example, the sequence ---[[ starts an ordinary, single-line comment, so that
the first and the last lines become independent comments. In this case, the
print is outside comments.

1.3 Global Variables

Global variables do not need declarations; you simply use them. It is not an
error to access a non-initialized variable; you just get the value nil as the result:

print(b) --> nil

b = 10
print(b) --> 10
If you assign nil to a global variable, Lua behaves as if the variable had never
been used:
b = nil
print(b) --> nil
After this assignment, Lua can eventually reclaim the memory used by the
variable.

1.4 The Stand-Alone Interpreter

The stand-alone interpreter (also called lua.c due to its source file, or simply
lua due to its executable) is a small program that allows the direct use of Lua.
This section presents its main options.
1 Block comments can be more complex than that, as we will see in Section 2.4.
1.4 The Stand-Alone Interpreter 7

When the interpreter loads a file, it ignores its first line if this line starts
with a hash (‘#’). This feature allows the use of Lua as a script interpreter in
UNIX systems. If you start your script with something like
#!/usr/local/bin/lua
(assuming that the stand-alone interpreter is located at /usr/local/bin), or
#!/usr/bin/env lua
then you can call the script directly, without explicitly calling the Lua inter-
preter.
The usage of lua is
lua [options] [script [args]]
Everything is optional. As we have seen already, when we call lua without
arguments the interpreter enters in interactive mode.
The -e option allows us to enter code directly into the command line, like
here:
% lua -e "print(math.sin(12))" --> -0.53657291800043
(UNIX needs the double quotes to stop the shell from interpreting the parenthe-
ses.)
The -l option loads a library. As we saw previously, -i enters interactive
mode after running the other arguments. Therefore, the next call will load the
lib library, then execute the assignment x = 10, and finally present a prompt for
interaction.
% lua -i -llib -e "x = 10"
In interactive mode, you can print the value of any expression by writing a
line that starts with an equal sign followed by the expression:
> = math.sin(3) --> 0.14112000805987
> a = 30
> = a --> 30
This feature helps to use Lua as a calculator.
Before running its arguments, the interpreter looks for an environment vari-
able named LUA_INIT_5_2 or else, if there is no such variable, LUA_INIT. If there
is one of these variables and its content is @filename, then the interpreter runs
the given file. If LUA_INIT_5_2 (or LUA_INIT) is defined but it does not start
with ‘@’, then the interpreter assumes that it contains Lua code and runs it.
LUA_INIT gives us great power when configuring the stand-alone interpreter,
because we have the full power of Lua in the configuration. We can preload
packages, change the path, define our own functions, rename or delete functions,
and so on.
A script can retrieve its arguments in the predefined global variable arg.
In a call like % lua script a b c, the interpreter creates the table arg with all
8 Chapter 1 Getting Started

the command-line arguments, before running the script. The script name goes
into index 0, its first argument (“a” in the example) goes to index 1, and so on.
Preceding options go to negative indices, as they appear before the script. For
instance, consider this call:
% lua -e "sin=math.sin" script a b
The interpreter collects the arguments as follows:
arg[-3] = "lua"
arg[-2] = "-e"
arg[-1] = "sin=math.sin"
arg[0] = "script"
arg[1] = "a"
arg[2] = "b"
More often than not, a script uses only the positive indices (arg[1] and arg[2],
in the example).
Since Lua 5.1, a script can also retrieve its arguments through a vararg ex-
pression. In the main body of a script, the expression ... (three dots) results in
the arguments to the script. (We will discuss vararg expressions in Section 5.2.)

Exercises
Exercise1.1: Run the factorial example. What happens to your program if you
enter a negative number? Modify the example to avoid this problem.
Exercise 1.2: Run the twice example, both by loading the file with the -l
option and with dofile. Which way do you prefer?
Exercise1.3: Can you name other languages that use -- for comments?
Exercise1.4: Which of the following strings are valid identifiers?

___ _end End end until? nil NULL

Exercise1.5: Write a simple script that prints its own name without knowing
it in advance.
 Types and Values
2
Lua is a dynamically typed language. There are no type definitions in the
language; each value carries its own type.
There are eight basic types in Lua: nil, boolean, number, string, userdata,
function, thread, and table. The type function gives the type name of any given
value:
print(type("Hello world")) --> string
print(type(10.4*3)) --> number
print(type(print)) --> function
print(type(type)) --> function
print(type(true)) --> boolean
print(type(nil)) --> nil
print(type(type(X))) --> string
The last line will result in “string” no matter the value of X, because the result
of type is always a string.
Variables have no predefined types; any variable can contain values of any
type:

print(type(a)) --> nil ('a' is not initialized)

a = 10
print(type(a)) --> number
a = "a string!!"
print(type(a)) --> string
a = print -- yes, this is valid!
a(type(a)) --> function

9
10 Chapter 2 Types and Values

Notice the last two lines: functions are first-class values in Lua; so, we can
manipulate them like any other value. (We will see more about this facility in
Chapter 6.)
Usually, when you use a single variable for different types, the result is
messy code. However, sometimes the judicious use of this facility is helpful,
for instance in the use of nil to differentiate a normal return value from an
abnormal condition.

2.1 Nil
Nil is a type with a single value, nil, whose main property is to be different from
any other value. Lua uses nil as a kind of non-value, to represent the absence
of a useful value. As we have seen, a global variable has a nil value by default,
before its first assignment, and you can assign nil to a global variable to delete
it.

2.2 Booleans
The boolean type has two values, false and true, which represent the traditional
boolean values. However, booleans do not hold a monopoly of condition values:
in Lua, any value can represent a condition. Conditional tests (e.g., conditions in
control structures) consider both the boolean false and nil as false and anything
else as true. In particular, Lua considers both zero and the empty string as true
in conditional tests.
Throughout this book, I will type “false” to mean any false value, that is, the
boolean false or nil. When I mean specifically the boolean value, I will type
“false”. The same holds for “true” and “true”.

2.3 Numbers
The number type represents real (double-precision floating-point) numbers. Lua
has no integer type.
Some people fear that even a simple increment or comparison can go weird
with floating-point numbers. Reality, however, is not like that. Virtually all plat-
forms nowadays follow the IEEE 754 standard for floating-point representation.
Following this standard, the only possible source of errors is a representation er-
ror, which happens when a number cannot be exactly represented. An operation
rounds its result only if that result has no exact representation. Any operation
with a result that has an exact representation must give that exact result.
The fact is that any integer up to 253 (approximately 1016 ) has an exact
representation as a double-precision floating-point number. When you use a
double to represent an integer, there is no rounding error at all, unless the
2.4 Strings 11

number has an absolute value greater than 253 . In particular, a Lua number
can represent any 32-bit integer without rounding problems.
Of course, fractional numbers can have representation errors. The situation
here is not different from what happens with pen and paper. If we want to
write 1/7 in decimal, we will have to stop somewhere. If we use ten digits
to represent a number, 1/7 becomes rounded to 0.142857142. If we compute
1/7 * 7 using ten digits, the result will be 0.999999994, which is different from 1.
Moreover, numbers that have a finite representation in decimal can have an
infinite representation in binary. For instance, 12.7 - 20 + 7.3 is not exactly zero
when computed with doubles, because both 12.7 and 7.3 do not have an exact
finite representation in binary (see Exercise 2.3).
Before we go on, remember: integers do have exact representations and
therefore do not have rounding errors.
Most modern CPUs do floating-point arithmetic as fast as (or even faster
than) integer arithmetic. Nevertheless, it is easy to compile Lua so that it
uses another type for numbers, such as longs or single-precision floats. This
is particularly useful for platforms without hardware support for floating point,
such as embedded systems. See file luaconf.h in the distribution for details.
We can write numeric constants with an optional decimal part, plus an
optional decimal exponent. Examples of valid numeric constants are:
4 0.4 4.57e-3 0.3e12 5E+20
Moreover, we can also write hexadecimal constants, prefixing them with 0x.
Since Lua 5.2, hexadecimal constants can also have a fractional part and a
binary exponent (prefixed by ‘p’ or ‘P’), as in the following examples:
0xff (255) 0x1A3 (419) 0x0.2 (0.125) 0x1p-1 (0.5)
0xa.bp2 (42.75)
(For each constant, we added its decimal representation in parentheses.)

2.4 Strings
Strings in Lua have the usual meaning: a sequence of characters. Lua is
eight-bit clean and its strings can contain characters with any numeric code,
including embedded zeros. This means that you can store any binary data into
a string. You can also store Unicode strings in any representation (UTF-8, UTF-
16, etc.). The standard string library that comes with Lua offers no explicit
support for those representations. Nevertheless, we can handle UTF-8 strings
quite reasonably, as we will discuss in Section 21.7.
Strings in Lua are immutable values. You cannot change a character inside
a string, as you can in C; instead, you create a new string with the desired
modifications, as in the next example:
a = "one string"
b = string.gsub(a, "one", "another") -- change string parts
print(a) --> one string
print(b) --> another string
12 Chapter 2 Types and Values

Strings in Lua are subject to automatic memory management, like all other
Lua objects (tables, functions, etc.). This means that you do not have to worry
about allocation and deallocation of strings; Lua handles this for you. A string
can contain a single letter or an entire book. Programs that manipulate strings
with 100K or 1M characters are not unusual in Lua.
You can get the length of a string using the prefix operator ‘#’ (called the
length operator):
a = "hello"
print(#a) --> 5
print(#"good\0bye") --> 8

Literal strings
We can delimit literal strings by matching single or double quotes:
a = "a line"
b = 'another line'
They are equivalent; the only difference is that inside each kind of quote you can
use the other quote without escapes.
As a matter of style, most programmers always use the same kind of quotes
for the same kind of strings, where the “kinds” of strings depend on the program.
For instance, a library that manipulates XML may reserve single-quoted strings
for XML fragments, because those fragments often contain double quotes.
Strings in Lua can contain the following C-like escape sequences:
\a bell
\b back space
\f form feed
\n newline
\r carriage return
\t horizontal tab
\v vertical tab
\\ backslash
\" double quote
\' single quote

The following examples illustrate their use:

> print("one line\nnext line\n\"in quotes\", 'in quotes'")
one line
next line
"in quotes", 'in quotes'
> print('a backslash inside quotes: \'\\\'')
a backslash inside quotes: '\'
> print("a simpler way: '\\'")
a simpler way: '\'
2.4 Strings 13

We can specify a character in a string also by its numeric value through the
escape sequences \ddd and \x\hh, where ddd is a sequence of up to three dec-
imal digits and hh is a sequence of exactly two hexadecimal digits. As a some-
what complex example, the two literals "alo\n123\"" and '\97lo\10\04923"'
have the same value, in a system using ASCII: 97 is the ASCII code for ‘a’, 10 is
the code for newline, and 49 is the code for the digit ‘1’. (In this example we must
write 49 with three digits, as \049, because it is followed by another digit; other-
wise Lua would read the number as 492.) We can also write that same string as
'\x61\x6c\x6f\x0a\x31\x32\x33\x22', representing each character by its hex-
adecimal code.

Long strings
We can delimit literal strings also by matching double square brackets, as we
do with long comments. Literals in this bracketed form can run for several
lines and do not interpret escape sequences. Moreover, this form ignores the
first character of the string when this character is a newline. This form is
especially convenient for writing strings that contain large pieces of code, as
in the following example:
page = [[
<html>
<head>
<title>An HTML Page</title>
</head>
<body>
<a href="http://www.lua.org">Lua</a>
</body>
</html>
]]
write(page)

Sometimes, you may want to enclose a piece of code containing something

like a=b[c[i]] (notice the ]] in this code), or you may need to enclose some code
that already has some code commented out. To handle such cases, you can add
any number of equal signs between the two open brackets, as in [===[. After
this change, the literal string ends only at the next closing brackets with the
same number of equal signs in between (]===], in our example). The scanner
ignores pairs of brackets with a different number of equal signs. By choosing an
appropriate number of signs, you can enclose any literal string without having
to add escapes into it.
This same facility is valid for comments, too. For instance, if you start a long
comment with --[=[, it extends until the next ]=]. This facility allows you easily
to comment out a piece of code that contains parts already commented out.
Long strings are the ideal format to include literal text in your code, but you
should not use them for non-text literals. Although literal strings in Lua can
14 Chapter 2 Types and Values

contain arbitrary characters, it is not a good idea to use them in your code: you
may have problems with your text editor; moreover, end-of-line sequences like
“\r\n” may change to “\n” when read. Instead, it is better to code arbitrary bi-
nary data using numeric escape sequences, either in decimal or in hexadecimal,
such as “\x13\x01\xA1\xBB”. However, this poses a problem for long strings,
because they would result in quite long lines.
For those situations, Lua 5.2 offers the escape sequence \z: it skips all
subsequent characters in the string until the first non-space character. The next
example illustrates its use:

data = "\x00\x01\x02\x03\x04\x05\x06\x07\z
\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F"
The \z at the end of the first line skips the following end-of-line and the inden-
tation of the next line, so that the byte \x07 is directly followed by \x08 in the
resulting string.

Coercions
Lua provides automatic conversions between numbers and strings at run time.
Any numeric operation applied to a string tries to convert the string to a number:

print("10" + 1) --> 11
print("10 + 1") --> 10 + 1
print("-5.3e-10"*"2") --> -1.06e-09
print("hello" + 1) -- ERROR (cannot convert "hello")

Lua applies such coercions not only in arithmetic operators, but also in other
places that expect a number, such as the argument to math.sin.
Conversely, whenever Lua finds a number where it expects a string, it con-
verts the number to a string:

print(10 .. 20) --> 1020

(The .. is the string concatenation operator in Lua. When you write it right
after a numeral, you must separate them with a space; otherwise, Lua thinks
that the first dot is a decimal point.)
Today we are not sure that these automatic coercions were a good idea in
the design of Lua. As a rule, it is better not to count on them. They are handy
in a few places, but add complexity both to the language and to programs that
use them. After all, strings and numbers are different things, despite these
conversions. A comparison like 10 == "10" is false, because 10 is a number and
“10” is a string.
If you need to convert a string to a number explicitly, you can use the function
tonumber, which returns nil if the string does not denote a proper number:
2.5 Tables 15

line = io.read() -- read a line

n = tonumber(line) -- try to convert it to a number
if n == nil then
error(line .. " is not a valid number")
else
print(n*2)
end
To convert a number to a string, you can call the function tostring, or
concatenate the number with the empty string:
print(tostring(10) == "10") --> true
print(10 .. "" == "10") --> true
These conversions are always valid.

2.5 Tables
The table type implements associative arrays. An associative array is an array
that can be indexed not only with numbers, but also with strings or any other
value of the language, except nil.
Tables are the main (in fact, the only) data structuring mechanism in Lua,
and a powerful one. We use tables to represent ordinary arrays, sets, records,
and other data structures in a simple, uniform, and efficient way. Lua uses
tables to represent packages and objects as well. When we write io.read, we
think about “the read function from the io module”. For Lua, this expression
means “index the table io using the string read as the key”.
Tables in Lua are neither values nor variables; they are objects. If you are
familiar with arrays in Java or Scheme, then you have a fair idea of what I
mean. You may think of a table as a dynamically allocated object; your program
manipulates only references (or pointers) to them. Lua never does hidden copies
or creation of new tables behind the scenes. Moreover, you do not have to declare
a table in Lua; in fact, there is no way to declare one. You create tables by means
of a constructor expression, which in its simplest form is written as {}:
a = {} -- create a table and store its reference in 'a'
k = "x"
a[k] = 10 -- new entry, with key="x" and value=10
a[20] = "great" -- new entry, with key=20 and value="great"
print(a["x"]) --> 10
k = 20
print(a[k]) --> "great"
a["x"] = a["x"] + 1 -- increments entry "x"
print(a["x"]) --> 11
A table is always anonymous. There is no fixed relationship between a
variable that holds a table and the table itself:
16 Chapter 2 Types and Values

a = {}
a["x"] = 10
b = a -- 'b' refers to the same table as 'a'
print(b["x"]) --> 10
b["x"] = 20
print(a["x"]) --> 20
a = nil -- only 'b' still refers to the table
b = nil -- no references left to the table
When a program has no more references to a table, Lua’s garbage collector will
eventually delete the table and reuse its memory.
Each table can store values with different types of indices, and it grows as
needed to accommodate new entries:
a = {} -- empty table
-- create 1000 new entries
for i = 1, 1000 do a[i] = i*2 end
print(a[9]) --> 18
a["x"] = 10
print(a["x"]) --> 10
print(a["y"]) --> nil
Note the last line: like global variables, table fields evaluate to nil when not
initialized. Also like global variables, you can assign nil to a table field to delete
it. This is not a coincidence: Lua stores global variables in ordinary tables. We
will discuss this subject further in Chapter 14.
To represent records, you use the field name as an index. Lua supports this
representation by providing a.name as syntactic sugar for a["name"]. Therefore,
we could write the last lines of the previous example in a cleaner manner as
follows:
a.x = 10 -- same as a["x"] = 10
print(a.x) -- same as print(a["x"])
print(a.y) -- same as print(a["y"])
For Lua, the two forms are equivalent and can be intermixed freely. For a human
reader, however, each form may signal a different intention. The dot notation
clearly shows that we are using the table as a record, where we have some set of
fixed, predefined keys. The string notation gives the idea that the table can have
any string as a key, and that for some reason we are manipulating that specific
key.
A common mistake for beginners is to confuse a.x with a[x]. The first form
represents a["x"], that is, a table indexed by the string “x”. The second form is
a table indexed by the value of the variable x. See the difference:
a = {}
x = "y"
a[x] = 10 -- put 10 in field "y"
print(a[x]) --> 10 -- value of field "y"
print(a.x) --> nil -- value of field "x" (undefined)
print(a.y) --> 10 -- value of field "y"
2.5 Tables 17

To represent a conventional array or a list, you simply use a table with

integer keys. There is neither a way nor a need to declare a size; you just
initialize the elements you need:
-- read 10 lines, storing them in a table
a = {}
for i = 1, 10 do
a[i] = io.read()
end
Given that you can index a table with any value, you can start the indices of
an array with any number that pleases you. However, it is customary in Lua to
start arrays with one (and not with zero, as in C) and several facilities in Lua
stick to this convention.
Usually, when you manipulate a list you must know its length. It can be a
constant or it can be stored somewhere. Often we store the length of a list in a
non-numeric field of the table; for historical reasons, several programs use the
field “n” for this purpose.
Often, however, the length is implicit. Remember that any non-initialized
index results in nil; you can use this value as a sentinel to mark the end of the
list. For instance, after you read 10 lines into a list, it is easy to know that its
length is 10, because its numeric keys are 1, 2, . . . , 10. This technique only works
when the list does not have holes, which are nil elements inside it. We call such
a list without holes a sequence.
For sequences, Lua offers the length operator ‘#’. It returns the last index, or
the length, of the sequence. For instance, you could print the lines read in the
last example with the following code:
-- print the lines
for i = 1, #a do
print(a[i])
end
Because we can index a table with any type, when indexing a table we have
the same subtleties that arise in equality. Although we can index a table both
with the number 0 and with the string “0”, these two values are different and
therefore denote different entries in a table. Similarly, the strings “+1”, “01”,
and “1” all denote different entries. When in doubt about the actual types of
your indices, use an explicit conversion to be sure:
i = 10; j = "10"; k = "+10"
a = {}
a[i] = "one value"
a[j] = "another value"
a[k] = "yet another value"
print(a[i]) --> one value
print(a[j]) --> another value
print(a[k]) --> yet another value
print(a[tonumber(j)]) --> one value
print(a[tonumber(k)]) --> one value
18 Chapter 2 Types and Values

You can introduce subtle bugs in your program if you do not pay attention to this
point.

2.6 Functions
Functions are first-class values in Lua: programs can store functions in vari-
ables, pass functions as arguments to other functions, and return functions as
results. Such facilities give great flexibility to the language; a program can re-
define a function to add new functionality, or simply erase a function to create
a secure environment when running a piece of untrusted code (such as code re-
ceived through a network). Moreover, Lua offers good support for functional
programming, including nested functions with proper lexical scoping; just wait
until Chapter 6. Finally, first-class functions play a key role in Lua’s object-
oriented facilities, as we will see in Chapter 16.
Lua can call functions written in Lua and functions written in C. Typically,
we resort to C functions both to achieve better performance and to access facili-
ties not easily accessible directly from Lua, such as operating-system facilities.
All the standard libraries in Lua are written in C. They comprise functions for
string manipulation, table manipulation, I/O, access to basic operating system
facilities, mathematical functions, and debugging.
We will discuss Lua functions in Chapter 5 and C functions in Chapter 27.

2.7 Userdata and Threads

The userdata type allows arbitrary C data to be stored in Lua variables. It has
no predefined operations in Lua, except assignment and equality test. Userdata
are used to represent new types created by an application program or a library
written in C; for instance, the standard I/O library uses them to represent open
files. We will discuss more about userdata later, when we get to the C API.
We will explain the thread type in Chapter 9, where we discuss coroutines.

Exercises
Exercise 2.1: What is the value of the expression type(nil) == nil? (You can
use Lua to check your answer.) Can you explain this result?
Exercise 2.2: Which of the following are valid numerals? What are their
values?
.0e12 .e12 0.0e 0x12 0xABFG 0xA FFFF 0xFFFFFFFF
0x 0x1P10 0.1e1 0x0.1p1

Exercise 2.3: The number 12.7 is equal to the fraction 127/10, where the
denominator is a power of ten. Can you express it as a common fraction where
the denominator is a power of two? What about the number 5.5?
Exercises 19

Exercise 2.4: How can you embed the following piece of XML as a string in
Lua?
<![CDATA[
Hello world
]]>
Show at least two different ways.
Exercise 2.5: Suppose you need to format a long sequence of arbitrary bytes
as a string literal in Lua. How would you do it? Consider issues like readability,
maximum line length, and performance.
Exercise2.6: Assume the following code:

a = {}; a.a = a
What would be the value of a.a.a.a? Is any a in that sequence somehow
different from the others?
Now, add the next line to the previous code:

a.a.a.a = 3
What would be the value of a.a.a.a now?
 Expressions
3
Expressions denote values. Expressions in Lua include the numeric constants
and string literals, variables, unary and binary operations, and function calls.
Expressions include also the unconventional function definitions and table con-
structors.

3.1 Arithmetic Operators

Lua supports the usual arithmetic operators: the binary ‘+’ (addition), ‘-’ (sub-
traction), ‘*’ (multiplication), ‘/’ (division), ‘^’ (exponentiation), ‘%’ (modulo), and
the unary ‘-’ (negation). All of them operate on real numbers. For instance,
x^0.5 computes the square root of x, while x^(-1/3) computes the inverse of its
cubic root.
The following rule defines the modulo operator:

a % b == a - math.floor(a/b)*b
For integer operands, it has the usual meaning, with the result always having
the same sign as the second argument. For real operands, it has some extra
uses. For instance, x%1 is the fractional part of x, and so x - x%1 is its integer
part. Similarly, x - x%0.01 is x with exactly two decimal digits:
x = math.pi
print(x - x%0.01) --> 3.14
As another example of the use of the modulo operator, suppose you want to
check whether a vehicle turning a given angle will start to backtrack. If the
angle is given in degrees, you can use the following formula:

21
22 Chapter 3 Expressions

local tolerance = 10
function isturnback (angle)
angle = angle % 360
return (math.abs(angle - 180) < tolerance)
end
This definition works even for negative angles:
print(isturnback(-180)) --> true
If we want to work with radians instead of degrees, we simply change the
constants in our function:
local tolerance = 0.17
function isturnback (angle)
angle = angle % (2*math.pi)
return (math.abs(angle - math.pi) < tolerance)
end
The operation angle % (2*math.pi) is all we need to normalize any angle to a
value in the interval [0, 2π).

3.2 Relational Operators

Lua provides the following relational operators:
< > <= >= == ~=
All these operators always produce a boolean value.
The == operator tests for equality; the ~= operator is the negation of equality.
We can apply both operators to any two values. If the values have different
types, Lua considers them not equal. Otherwise, Lua compares them according
to their types. Specifically, nil is equal only to itself.
Lua compares tables and userdata by reference, that is, two such values are
considered equal only if they are the very same object. For instance, after the
code
a = {}; a.x = 1; a.y = 0
b = {}; b.x = 1; b.y = 0
c = a
you have a == c but a ~= b.
We can apply the order operators only to two numbers or to two strings. Lua
compares strings in alphabetical order, which follows the locale set for Lua. For
instance, with a Portuguese Latin-1 locale, we have "acai" < "açaí" < "acorde".
Values other than numbers and strings can be compared only for equality (and
inequality).
When comparing values with different types, you must be careful: remember
that "0" is different from 0. Moreover, 2 < 15 is obviously true, but "2" < "15"
is false (alphabetical order). To avoid inconsistent results, Lua raises an error
when you mix strings and numbers in an order comparison, such as 2 < "15".
3.3 Logical Operators 23

3.3 Logical Operators

The logical operators are and, or, and not. Like control structures, all logical
operators consider both the boolean false and nil as false, and anything else
as true. The and operator returns its first argument if it is false; otherwise, it
returns its second argument. The or operator returns its first argument if it is
not false; otherwise, it returns its second argument:
print(4 and 5) --> 5
print(nil and 13) --> nil
print(false and 13) --> false
print(4 or 5) --> 4
print(false or 5) --> 5
Both and and or use short-cut evaluation, that is, they evaluate their second
operand only when necessary. Short-cut evaluation ensures that expressions
like (type(v) == "table" and v.tag == "h1") do not cause run-time errors: Lua
will not try to evaluate v.tag when v is not a table.
A useful Lua idiom is x = x or v, which is equivalent to

if not x then x = v end

That is, it sets x to a default value v when x is not set (provided that x is not set
to false).
Another useful idiom is (a and b) or c, or simply a and b or c, because and
has a higher precedence than or. It is equivalent to the C expression a ? b : c,
provided that b is not false. For instance, we can select the maximum of two
numbers x and y with a statement like

max = (x > y) and x or y

When x>y, the first expression of the and is true, so the and results in its second
expression (x), which is always true (because it is a number), and then the or
expression results in the value of its first expression, x. When x > y is false, the
and expression is false and so the or results in its second expression, y.
The not operator always returns a boolean value:
print(not nil) --> true
print(not false) --> true
print(not 0) --> false
print(not not 1) --> true
print(not not nil) --> false

3.4 Concatenation
Lua denotes the string concatenation operator by .. (two dots). If any operand
is a number, Lua converts this number to a string. (Some languages use the ‘+’
operator for concatenation, but 3+5 is different from 3 .. 5.)
24 Chapter 3 Expressions

print("Hello " .. "World") --> Hello World

print(0 .. 1) --> 01
print(000 .. 01) --> 01
Remember that strings in Lua are immutable values. The concatenation opera-
tor always creates a new string, without any modification to its operands:
a = "Hello"
print(a .. " World") --> Hello World
print(a) --> Hello

3.5 The Length Operator

The length operator works on strings and tables. On strings, it gives the number
of bytes in the string. On tables, it gives the length of the sequence represented
by the table.
The length operator provides several common Lua idioms for manipulating
sequences:
print(a[#a]) -- prints the last value of sequence 'a'
a[#a] = nil -- removes this last value
a[#a + 1] = v -- appends 'v' to the end of the list
As we saw in the last chapter, the length operator is unpredictable for lists
with holes (nils). It only works for sequences, which we defined as lists without
holes. More precisely, a sequence is a table where the numeric keys comprise a
set 1, . . . , n for some n. (Remember that any key with value nil is actually not in
the table.) In particular, a table with no numeric keys is a sequence with length
zero.
Over the years, there have been many proposals to extend the meaning of the
length operator to lists with holes, but this extension is easier said than done.
The problem is that, because a list is actually a table, the concept of “length”
is somewhat fuzzy. For instance, consider the list resulting from the following
code:
a = {}
a[1] = 1
a[2] = nil -- does nothing, as a[2] is already nil
a[3] = 1
a[4] = 1
It is easy to say that the length of this list is four, and that is has a hole at
index 2. However, what can we say about the next similar example?
a = {}
a[1] = 1
a[10000] = 1
Should we consider a as a list with 10000 elements, where 9998 of them are nil?
Now, the program does this:
3.6 Precedence 25

a[10000] = nil
What is the list length now? Should it be 9999, because the program deleted
the last element? Or maybe still 10000, as the program only changed the last
element to nil? Or should the length collapse to 1?
Another common proposal is to make the # operator return the total number
of elements in the table. This semantics is clear and well defined, but not useful
at all. Consider all previous examples and think how useful would be such
operator for real algorithms over lists or arrays.
Yet more troubling are nils at the end of the list. What should be the length
of the following list?

a = {10, 20, 30, nil, nil}

Remember that, for Lua, a field with nil is indistinct from an absent field.
Therefore, the previous table is equal to {10, 20, 30}; its length is 3, not 5.
You may consider that a nil at the end of a list is a very special case. However,
many lists are built by adding elements one by one. Any list with holes that was
built that way must have had nils at its end along the way.
Most lists we use in our programs are sequences (e.g., a file line cannot be
nil) and, therefore, most of the time the use of the length operator is safe. If
you really need to handle lists with holes, you should store the length explicitly
somewhere.

3.6 Precedence
Operator precedence in Lua follows the table below, from the higher to the lower
priority:
^
not # - (unary)
* / %
+ -
..
< > <= >= ~= ==
and
or
All binary operators are left associative, except for ‘^’ (exponentiation) and ‘..’
(concatenation), which are right associative. Therefore, the following expres-
sions on the left are equivalent to those on the right:
a+i < b/2+1 <--> (a+i) < ((b/2)+1)
5+x^2*8 <--> 5+((x^2)*8)
a < y and y <= z <--> (a < y) and (y <= z)
-x^2 <--> -(x^2)
x^y^z <--> x^(y^z)
26 Chapter 3 Expressions

When in doubt, always use explicit parentheses. It is easier than looking it up

in the manual and you will probably have the same doubt when you read the
code again.

3.7 Table Constructors

Constructors are expressions that create and initialize tables. They are a dis-
tinctive feature of Lua and one of its most useful and versatile mechanisms.
The simplest constructor is the empty constructor, {}, which creates an
empty table; we have seen it before. Constructors also initialize lists. For
instance, the statement

days = {"Sunday", "Monday", "Tuesday", "Wednesday",

"Thursday", "Friday", "Saturday"}
will initialize days[1] with the string “Sunday” (the first element of the construc-
tor has index 1, not 0), days[2] with “Monday”, and so on:

print(days[4]) --> Wednesday

Lua also offers a special syntax to initialize a table record-like, as in the next
example:

a = {x=10, y=20}

This previous line is equivalent to these commands:

a = {}; a.x=10; a.y=20

The original expression, however, is faster, because Lua creates the table already
with the right size.
No matter what constructor we use to create a table, we can always add fields
to and remove fields from the result:
w = {x=0, y=0, label="console"}
x = {math.sin(0), math.sin(1), math.sin(2)}
w[1] = "another field" -- add key 1 to table 'w'
x.f = w -- add key "f" to table 'x'
print(w["x"]) --> 0
print(w[1]) --> another field
print(x.f[1]) --> another field
w.x = nil -- remove field "x"
However, as I just mentioned, creating a table with a proper constructor is more
efficient, besides being more elegant.
We can mix record-style and list-style initializations in the same constructor:
3.7 Table Constructors 27

polyline = {color="blue",
thickness=2,
npoints=4,
{x=0, y=0}, -- polyline[1]
{x=-10, y=0}, -- polyline[2]
{x=-10, y=1}, -- polyline[3]
{x=0, y=1} -- polyline[4]
}
The above example also illustrates how we can nest constructors to represent
more complex data structures. Each of the elements polyline[i] is a table
representing a record:

print(polyline[2].x) --> -10

print(polyline[4].y) --> 1

Those two constructor forms have their limitations. For instance, you cannot
initialize fields with negative indices, nor with string indices that are not proper
identifiers. For such needs, there is another, more general, format. In this
format, we explicitly write the index to be initialized as an expression, between
square brackets:

opnames = {["+"] = "add", ["-"] = "sub",

["*"] = "mul", ["/"] = "div"}

i = 20; s = "-"
a = {[i+0] = s, [i+1] = s..s, [i+2] = s..s..s}

print(opnames[s]) --> sub

print(a[22]) --> ---

This syntax is more cumbersome, but more flexible too: both the list-style and
the record-style forms are special cases of this more general syntax. The con-
structor {x = 0, y = 0} is equivalent to {["x"] = 0, ["y"] = 0}, and the constructor
{"r", "g", "b"} is equivalent to {[1] = "r", [2] = "g", [3] = "b"}.
You can always put a comma after the last entry. These trailing commas are
optional, but are always valid:

a = {[1]="red", [2]="green", [3]="blue",}

This flexibility frees programs that generate Lua constructors from the need to
handle the last element as a special case.
Finally, you can always use a semicolon instead of a comma in a constructor.
I usually reserve semicolons to delimit different sections in a constructor, for
instance to separate its list part from its record part:

{x=10, y=45; "one", "two", "three"}

28 Chapter 3 Expressions

Exercises
Exercise3.1: What will the following program print?
for i = -10, 10 do
print(i, i % 3)
end
Exercise3.2: What is the result of the expression 2^3^4? What about 2^-3^4?
Exercise3.3: We can represent a polynomial an xn + an−1 xn−1 + . . .+ a1 x1 + a0
in Lua as a list of its coefficients, such as {a0 , a1 , ..., an }.
Write a function that receives a polynomial (represented as a table) and a
value for x and returns the polynomial value.
Exercise3.4: Can you write the function from the previous item so that it uses
at most n additions and n multiplications (and no exponentiations)?
Exercise 3.5: How can you check whether a value is a boolean without using
the type function?
Exercise3.6: Consider the following expression:
(x and y and (not z)) or ((not y) and x)
Are the parentheses necessary? Would you recommend their use in that expres-
sion?
Exercise3.7: What will the following script print? Explain.
sunday = "monday"; monday = "sunday"
t = {sunday = "monday", [sunday] = monday}
print(t.sunday, t[sunday], t[t.sunday])

Exercise 3.8: Suppose that you want to create a table that associates each
escape sequence for strings (see Section 2.4) with its meaning. How could you
write a constructor for that table?
 Statements
4
Lua supports an almost conventional set of statements, similar to those in C
or Pascal. The conventional statements include assignment, control structures,
and procedure calls. Lua also supports some not so conventional statements,
such as multiple assignments and local variable declarations.

4.1 Assignment
Assignment is the basic means of changing the value of a variable or a table
field:
a = "hello" .. "world"
t.n = t.n + 1
Lua allows multiple assignment, which assigns a list of values to a list of
variables in one step. Both lists have their elements separated by commas. For
instance, in the assignment

a, b = 10, 2*x

the variable a gets the value 10 and b gets 2*x.

In a multiple assignment, Lua first evaluates all values and only then exe-
cutes the assignments. Therefore, we can use a multiple assignment to swap
two values, as in the following examples:
x, y = y, x -- swap 'x' for 'y'
a[i], a[j] = a[j], a[i] -- swap 'a[i]' for 'a[j]'

29
30 Chapter 4 Statements

Lua always adjusts the number of values to the number of variables: when
the list of values is shorter than the list of variables, the extra variables receive
nil as their values; when the list of values is longer, the extra values are silently
discarded:
a, b, c = 0, 1
print(a, b, c) --> 0 1 nil
a, b = a+1, b+1, b+2 -- value of b+2 is ignored
print(a, b) --> 1 2
a, b, c = 0
print(a, b, c) --> 0 nil nil
The last assignment in the above example shows a common mistake. To initial-
ize a set of variables, you must provide a value for each one:
a, b, c = 0, 0, 0
print(a, b, c) --> 0 0 0
Actually, most of the previous examples are somewhat artificial. I seldom
use multiple assignment simply to write several unrelated assignments in one
line. In particular, a multiple assignment is not faster than its equivalent
single assignments. Nevertheless, often we really need multiple assignment. We
already saw an example, to swap two values. A more frequent use is to collect
multiple returns from function calls. As we will discuss in detail in Section 5.1,
a function call can return multiple values. In such cases, a single expression can
supply the values for several variables. For instance, in the assignment a,b=f()
the call to f returns two results: a gets the first and b gets the second.

4.2 Local Variables and Blocks

Besides global variables, Lua supports local variables. We create local variables
with the local statement:
j = 10 -- global variable
local i = 1 -- local variable
Unlike global variables, local variables have their scope limited to the block
where they are declared. A block is the body of a control structure, the body of a
function, or a chunk (the file or string where the variable is declared):
x = 10
local i = 1 -- local to the chunk
while i <= x do
local x = i*2 -- local to the while body
print(x) --> 2, 4, 6, 8, ...
i = i + 1
end
4.2 Local Variables and Blocks 31

if i > 20 then
local x -- local to the "then" body
x = 20
print(x + 2) -- (would print 22 if test succeeded)
else
print(x) --> 10 (the global one)
end
print(x) --> 10 (the global one)

Beware that this example will not work as expected if you enter it in interactive
mode. In interactive mode, each line is a chunk by itself (unless it is not
a complete command). As soon as you enter the second line of the example
(local i = 1), Lua runs it and starts a new chunk in the next line. By then, the
local declaration is already out of scope. To solve this problem, we can delimit
the whole block explicitly, bracketing it with the keywords do–end. Once you
enter the do, the command completes only at the corresponding end, so Lua
does not execute each line by itself.
These do blocks are useful also when you need finer control over the scope of
some local variables:
do
local a2 = 2*a
local d = (b^2 - 4*a*c)^(1/2)
x1 = (-b + d)/a2
x2 = (-b - d)/a2
end -- scope of 'a2' and 'd' ends here
print(x1, x2)
It is good programming style to use local variables whenever possible. Local
variables help you avoid cluttering the global environment with unnecessary
names. Moreover, the access to local variables is faster than to global ones.
Finally, a local variable vanishes as soon as its scope ends, allowing the garbage
collector to release its value.
Lua handles local-variable declarations as statements. As such, you can
write local declarations anywhere you can write a statement. The scope of
the declared variables begins after the declaration and goes until the end of
the block. Each declaration can include an initial assignment, which works the
same way as a conventional assignment: extra values are thrown away; extra
variables get nil. If a declaration has no initial assignment, it initializes all its
variables with nil:
local a, b = 1, 10
if a < b then
print(a) --> 1
local a -- '= nil' is implicit
print(a) --> nil
end -- ends the block started at 'then'
print(a, b) --> 1 10
Exploring the Variety of Random
Documents with Different Content
highest but one of the ten grades or
ranks of chiefs. ↑
4 A royal progress in olden time was
known by its predominating red
insignia. ↑
5 Moa, trunk-fish (Ostracion
camurum). ↑
6 The recurrence of the names
Olopana and Luukia, and the flood
incident, prominent in the history of
Moikeha (Vol. iv, page 156 of these
Memoirs), again illustrates the free use
by the bards of popular characters and
plots for repetition in their stories. ↑

[Contents]

Legend of Kalaepuni Kaao no Kalaepuni a

and Kalaehina. me Kalaehina.

CHAPTER I. MOKUNA I.

RELATING TO NO KALAEPUNI.
KALAEPUNI.
Kalanipo and Kamaelekapu were O Kalanipo ka makuakane, o
the father and mother of Kamaelekapu ka wahine, o
Kalaepuni and Kalaehina. Kalaepuni ka mua o Kalaehina
Kalaepuni was the elder and ka muli, a o Holualoa i Kona,
Kalaehina was the younger. Hawaii, ka aina; o
They were born and raised in Keawenuiaumi ke ’lii o Hawaii ia
Holualoa, Kona, during the reign wa e noho ana. No Kalaepuni.
of Keawenuiaumi, king of He keiki kolohe loa ia a me ka
Hawaii. Regarding Kalaepuni: he makau ole, eono ona mau
was a very mischievous boy and makahiki, hoomaka oia e pepehi
one who was without fear. At the i kona poe hoa paani; mai laila
age of six he was able to whip all ka pii ana o kona ikaika a hiki i
his playmates and his strength ka iwakalua o kona mau
developed from that time on until makahiki. Lilo ae la o Kalaepuni i
he reached the age of twenty mea kaulana ma Hawaii a puni,
years, at which time Kalaepuni manao iho la ia e pepehi i na
became famous 1 over the whole keiki alii a pau loa o Hawaii, mai
of Hawaii for his great strength. ka mea nunui a ka mea liilii loa,
At twenty he determined to kill all a ka mea e omo ana i ka waiu.
the young chiefs of Hawaii, 2 [201]A o Keawenuiaumi hoi, aole
those who were of very high ona manao e pepehi, no ka mea
blood as well as those of low ua kokoke mai kona wa
blood, both big and small, even elemakule; nolaila, waiho wale
the mere sucklings. In his plan to kona manao ia Keawenuiaumi.
[200]kill all the chiefs he did not Aka, ua komo ka makau o
intend to kill Keawenuiaumi, Keawenuiaumi ia Kalaepuni, a
because, as he reasoned, manao iho la e mahuka mai na
Keawenuiaumi was already well maka aku o Kalaepuni.
on in years. But Keawenuiaumi 3
was afraid of Kalaepuni and he
made his plans to escape and to
get out from the presence of
Kalaepuni.

Shortly after the events narrated Mahope o laila, holo aku la o

above, Kalaepuni went out Kalaepuni me na lawaia a
fishing with some of Keawenuiaumi, ma waho ae o
Keawenuiaumi’s fishermen to Kalahiki, he kupalupalu mano ka
the fishing grounds outside of lakou lawaia. A makaukau na
Kalahiki; they went out shark mano a pau loa malalo o na waa
fishing. After some of the bait o lakou, huki na lawaia a
was thrown out the sharks began Keawenuiaumi i ka mano i luna
to gather under the canoe, when o na waa, lele iho la o Kalaepuni
the baited hooks were let down i waena o na mano, a pepehi iho
and several sharks were caught la i na mano i laka mai ma ke
and hauled into the canoe. While kupalu ana, a lanakila o
Keawenuiaumi’s men were Kalaepuni maluna o na mano a
hauling the sharks up, Kalaepuni pau loa. Alaila, olelo iho o
jumped out amongst the sharks Kalaepuni i kana olelo kaena
that were gathered under the penei: “Ma keia hope aku, e
canoe and began to fight them, 4 hoolilo ana wau i o’u mau lima i
killing them all. After killing all the makau kihele mano! A e hoolilo
sharks, Kalaepuni began au i na mano a pau, i lehu i loko
boasting, saying: “Henceforth I o kuu poho lima.”
shall use my hands as hooks for
catching sharks and shall make
all sharks as dust in my hands.”

After they had been fishing for A pau ka lawaia ana, hoi aku la
some time they returned and lakou a pae ka waa ma
landed their canoe at Honaunau Honaunau, e ku ana he kumu
where a large kou tree was kou nui i laila, o ka nui o ua kou
standing. This was a very large la, ekolu kanaka e apo me na
tree requiring three men to span lima, alaila, puni kona kino.
its girth. Kalaepuni, however, Lalau iho la o Kalaepuni i ke
took hold of the tree and pulled it kumu kou a huhuki ae la, ua like
up by the roots 5 as though it was me ka mauu opala ia ia, ka
but a blade of grass, so maunu a uaua ole ke huhuki ae.
resistless was it. After pulling up Alaila, waiho iho la ia i kana
the tree he again boasted, olelo kaena, penei: “E hoolilo
saying: “I am going to turn my ana au i o’u mau lima i ko’i kua
hands into an axe for the cutting waa no Hilo.”
down of trees for canoes in Hilo.”

Because of these feats of great A no keia mau mea a Kalaepuni

strength shown by Kalaepuni i hoike ai imua o ke ’lii, o
before the king, Keawenuiaumi Keawenuiaumi, makau iho la o
became more and more afraid of Keawenuiaumi, a mahuka aku la
him and he went and hid himself a noho ma ke kua o ka mauna o
in a place back of the Hualalai Hualalai, ma waena o Maunaloa
mountain, between Maunaloa a me ka mauna o Kona. Ua
and the Kona mountain. The kaulana ia wahi i noho ia e
place after this became famous Keawenuiaumi, o ia o Ahu-a-Umi
because it was here that a hiki i keia la, e waiho la ma ka
Keawenuiaumi lived in hiding, mauna o Kona, ma ka Hikina o
near the Ahu-a-Umi 6 as can be Kona.
seen to this day, lying back of
the Kona mountain and in the
eastern part of that district.

Before Keawenuiaumi went off to Mamua ae o ka mahuka ana o

hide himself, he left word with Keawenuiaumi, waiho iho la ia i
one of his servants, Maunaloa by kana olelo i kekahi kauwa ana,
name, as follows: “I am now on ia Maunaloa: “Eia wau ke hele
my way. If Kalaepuni comes nei, i noho oe a i hiki mai o
while you are here, tell him that I Kalaepuni, olelo aku oe, ua
am dead.” 7 The servant make au.” Ae aku la ke kauwa,
consented to do this. hele aku la o Keawenuiaumi a
Keawenuiaumi then departed on noho i kahi i olelo mua ia maluna
his way to the place mentioned ae nei. A hele o Keawenuiaumi,
above. After the departure of hiki o Kalaepuni a ka hale, ninau
Keawenuiaumi, Kalaepuni ia Maunaloa, olelo mai o
arrived at the house and asked Maunaloa: “Ua make.” Alaila,
Maunaloa as to the whereabouts lawe ae la o Kalaepuni ia Hawaii
of the king. Maunaloa answered i loko o kona lima, a lilo iho la ko
that the king was dead. Keawenuiaumi noho ana alii ia
Kalaepuni then took charge of ia.
the whole island of Hawaii and
he reigned as king in place of
Keawenuiaumi.

While Keawenuiaumi was in the Ia Keawenuiaumi e noho ana i

mountain he one day said to his ka mauna, olelo aku la ia i kana
high priest, 8 Mokupane: “You kahuna, ia Mokupane: “E
must invoke the gods for the anaana oe ia Kalaepuni a make,
death of Kalaepuni that I may i lilo hou au i alii no Hawaii a
again reign as king of the whole puni.” Mahope o keia olelo a ke
of Hawaii.” Soon after this ’lii i ke kahuna, hoouna aku la o
request of the king was made, Mokupane i elua kanaha kanaka
Mokupane the priest sent two i Kahoolawe, maluna o na waa,
forties of men to Kahoolawe on e kohi i punawai, he umi anana
canoes to dig a well 9 ten fathoms ka hohonu, a e hoopuni o
in depth and to place large rocks [203]luna i na pohaku nunui loa.
around the mouth of the well. O ka aina i kohi ia ai ka punawai,
The name of [202]the land where o Keanapou i Kahoolawe, aia no
they were to dig the well is ke waiho la a hiki i keia la,
known as Keanapou and it is hoonoho ia iho la, he elemakule
there to this day. After the well me kana wahine i ua punawai
was dug and the rocks put in nei, he mau lawaia laua.
place, an old man and his wife
were placed in charge of it; they
were fisher folks.

When the two forties of men A makaukau ka hoi o na kanaha

were ready to return to Hawaii, kanaka elua i Hawaii, olelo aku o
Mokupane the priest instructed Mokupane, ke kahuna i na
the old couple, saying: “If a very elemakule: “E i noho olua a i hiki
large man with locks of hair that mai he kanaka nui, ua aki ia ka
are as long as a bunch of lauoho, ua like ka loihi me ka pu
olona 10 should come while you o ke olona, alaila, o ke kanaka ia
two are here, that is the man for nona keia punawai, a maanei oia
whom this well has been e make ai. A hiki mai i o olua nei,
prepared and here he must die. haawi aku olua i ka ia a pau loa
When he comes give him all ia ia, nana ia e ai a make i ka
your fish so that after he shall wai, a i noi mai ia olua i wai, mai
have eaten the fish he will be haawi olua i ka wai, kuhikuhi aku
very thirsty. When he asks of you olua i ka wai i ka luawai nei la.”
for some water don’t give him Mahope o keia olelo ana a ke
any, but direct him to this well.” kahuna, hoi aku la lakou a hiki i
After these instructions were Hawaii, ia wa, hoomaka o
imparted by the priest, he and Mokupane i kana pule anaana
the men returned to Hawaii, no Kalaepuni.
where the priest began to invoke
of the gods for the death of
Kalaepuni.

Soon after Mokupane began on Mahope o keia pule ana a

his prayers it was reported all Mokupane, ua kui ae la ke
over Hawaii that great schools of kaulana o ke ku ana o ka mano
sharks were being seen daily at ma Kauhola i Kohala, ma na
Kauhola off the coast of Kohala. wahi o Hawaii a puni, a lohe o
When this was reported to Kalaepuni, kupu ae la kona
Kalaepuni he at once entertained manao, e hele e lealea me ka
a strong desire to go to Kauhola mano ma Kauhola, no ka mea,
and have some sport with the ua olelo ia, o kana puni ka
sharks, as it was his chief delight hakaka me ka mano.
to kill them.

After Kalaepuni had arrived at A hiki ia i Kohala, a hehi i luna o

Kohala and set foot at Kauhola Kauhola, e paapu ana na
he saw a large number of people kanaka i laila, e nana ana i ka
gathered at the place looking at mano, ia wa, lele o Kalaepuni i
the sharks. When Kalaepuni saw lalo a hakaka me ka mano, nui
them he jumped in and began to na mano i make ia ia, ma keia
fight the sharks, killing a good hakaka ana. No ka nanea loa o
many of them. While Kalaepuni Kalaepuni i ka hakaka me ka
was busily engaged in his fight mano, ua ike ole ia i ke ko a ke
with the sharks he did not notice au i Alenuihaha, ekolu po, ekolu
how he was being carried away ao, i ka moana, pae i Keanapou i
from land by a strong current into Kahoolawe, nana aku la ia, he
the channel of Alanuihaha. 11 wahi hale e ku ana, hele aku la
After being in the sea for three ia a hiki ilaila. Nana aku la o
nights and three days he landed Kalaepuni, he elemakule a he
at Keanapou 12 in Kahoolawe. luahine e noho ana, aloha mai la
When he reached the shore he laua, aloha aku la o Kalaepuni,
looked about him and saw a ninau mai laua: “Ma ka moana
small house, near by, to which mai nei oe?” Ae aku o
he then went. Upon arrival at the Kalaepuni: “Ae, ekolu po, ekolu
place he looked and saw an ao, hiki mai la au ianei.” “I aku o
aged couple who greeted him, Kalaepuni, aohe ai a olua?”
which greeting he returned. The Hoole mai laua: “Aohe ai o keia
old people then asked him: “Did wahi, aia koonei ai i ka ihu o ka
you come from the sea?” “Yes,” waa, ina e holo mai ka waa mai
said Kalaepuni. “I have been Honuaula mai, a mai
three days and nights in the sea Ukumehame mai, alaila, ola keia
before I landed here.” Kalaepuni
then asked the old people: “Have wahi. He ai no koonei, o ka ai
you any food?” The old people kamaaiana no, o ke kupala.”
said: “No, there is no food in this
place. The only food that you
can get in this place is what is
brought here in canoes. When
any one comes from Honuaula 13
or Ukumehame, 13 then we get
food. The only food that grows
here is the kupala.” 14

Kalaepuni then looked up and Alawa ae la o Kalaepuni i luna, a

saw a shelf with some fish being ike i na haka ia e kaulai ana,
put out to be dried and asked: ninau aku la: “Na wai kela ia?”
“Who owns that fish?” “We do,” “Na maua no,” wahi a na
answered the old people. elemakule. Nonoi aku la o
Kalaepuni then asked them: Kalaepuni ia laua: “Na’u kekahi
“May I have some fish?” The old ia.” Ae mai la laua, noke aku ana
people then gave him all the fish o Kalaepuni i ka ai i ka ia, a pau
and Kalaepuni began to eat ia ia. Ninau hou o Kalaepuni:
them until he had finished the “Pau mai la no ka ia?” I aku laua
whole lot. Kalaepuni then asked: nei: “Elua ipu ia maka i koe, ua
“Is this all the fish you have?” liu i ka paakai.” Lalau aku la no o
The old people said: “We have Kalaepuni, a noke aku la a pau
two calabashes of pickled ones ia mau ipu ia. Ia wa, makewai o
left.” Kalaepuni then took the fish Kalaepuni, nonoi aku i wai i na
from the two calabashes and elemakule, hoole mai na
devoured them all. After this elemakule: “Aohe o maua wai,
Kalaepuni became very thirsty hookahi no wai o keia wahi, o ka
and so asked of the old people wai kai. A o ka wai maoli, aia a
for some water. The aged couple ua ka ua naulu, alaila, loaa
then said: “We have no water. koonei wai maoli, a o ka wai kai,
The only water we have here is oia koonei wai mau, i eli ia i loko
the salt water. Fresh water can o ka lua.” Mahope o keia
only be had after a rain storm; kamailio ana, hele aku la
but salt water is our only water; it Kalaepuni a iho i lalo o ka
is in a well.” After this Kalaepuni punawai i eli ia ai, e inu wai. [205]
went and climbed down the well
to take a drink. [204]

While Kalaepuni was drinking A inu o Kalaepuni i ka wai i lalo o

the water in the well, the old ka lua, olokaa aku la na
people began to roll down the elemakule i ka pohaku nui, a paa
rocks that were around the ke kua o Kalaepuni, oni ae la no
mouth of the well. After the back lele ka pohaku, olokaa no laua
of Kalaepuni was covered with nei i ka pohaku a kokoke e piha
rocks he would move and the ka lua, owala ae la no o
rocks would roll off; but the two Kalaepuni lele liilii ka pohaku.
kept on rolling the rocks until the Ma keia olokaa ana i ka pohaku,
well was almost filled up, without aole i make o Kalaepuni, aole i
killing Kalaepuni. In all this paa i na pohaku, aka, aole ia i
Kalaepuni still kept on drinking kena i ka wai no ka paa e o ka
and as the water was covered wai i na pohaku.
over with the rocks he could get
but very little.

When Kalaepuni saw that the Ma keia hana a na elemakule ia

two were bent on killing him he Kalaepuni, olelo aku o
called out: “I am going to kill you Kalaepuni: “E make ana olua
two.” He then began to turn and ia’u.” Oni ae la o Kalaepuni mai
twist out of the rocks until he had loko ae o na pohaku paakiki, a
freed himself. When the old hemo ae la, ike na elemakule, e
people saw that they would get make ana laua ia Kalaepuni ke
killed if Kalaepuni could get to pii ae i luna, nolaila, holo aku la
the top, the old man ran away. ka elemakule kane. Kahea aku
When the old woman saw this ka wahine: “O ka holo ka kau,
she called out: “Are you going to kai no o ka hoomanawanui ae a
run away? Is it not best to make ka enemi, alaila, pono, a
continue the fight until the enemy holo aku oe pakele, e holo no, a
is killed? Do you suppose that e make no, e noho no a e make
you could save yourself by no, o ka ikaika auanei keia e
running? You will get killed if you pakele ai ke holo aku.” Ma keia
run and you will get killed if you olelo a ka wahine, aohe hoolohe
stay, for with this great strength mai o ke kane, o ka holo loa,
none will ever escape.” With all aohe maliu mai i ka olelo a ka
this the old man kept on running wahine, aka, hoomanawanui no
and he never once turned back. ka wahine i ke kiola ana i ka
The old woman, however, kept pohaku, pa iho la ka lae o
on rolling down the rocks till one Kalaepuni i ka pohaku, a make
happened to strike Kalaepuni on iho la.
the head killing him.

CHAPTER II. MOKUNA II.

Relating to Kalaehina. NO KALAEHINA.

We can see in the above story Ua maopopo ia kakou ma ka

that Kalaepuni must have been a nana ana i ko Kalaepuni kaao,
very brave and fearless man and he kanaka koa loa ia a me ka
also that he was very powerful. makau ole, he kanaka ikaika loa,
In this chapter we will speak of a ma keia kaao ana, no kona
his younger brother Kalaehina. muli iho, oia o Kalaehina.
Mamua ae o ka make ana o
Before the death of Kalaepuni at Kalaepuni ma Keanapou, i
Keanapou, on Kahoolawe, and Kahoolawe, ia Kalaepuni e noho
while he was still king of Hawaii ana ma ko Keawenuiaumi noho
in place of Keawenuiaumi, he ana alii, o Hawaii. Kena aku la o
ordered the people from one end Kalaepuni i na kanaka, mai kela
of Kona to the other to go with pea a keia pea o Kona, e hele
Kalaehina and haul down me Kalaehina i ke kauo waa ma
canoes at Kapua, a place in Kapua, aia ia wahi ma Kona
South Kona next to Kau. In this Hema, e pili ana me Kau. Ma
expedition Kalaehina was placed keia hele ana, ua hoonoho ia o
in charge. There were as many Kalaehina i luna nui maluna o na
canoes as there were minor mea a pau loa, e like me ka nui
districts in Kona. When they o na waa a me na okana o
arrived at the place where the Kona. A hiki lakou i kahi o na
canoes were lying, there were waa e waiho ana, eono waa,
six of them, there being six minor eono okana, olelo aku o
districts in Kona, Kalaehina then Kalaehina i kana olelo kuahaua:
said to the people: “Ye servants “E na makaainana o kuu
of my older brother, Kalaepuni, kaikuaana, o Kalaepuni, e
hear me: the district that will get hoolohe mai oukou, o ka okana
its canoe down to the shore first, e hiki e ana kana waa i kai,
its people shall be the favorites alaila, e lilo ia mau kanaka i
of Kalaepuni.” punahele na Kalaepuni.”

Upon hearing this the people of Kauo aku la ka okana mua i ka

the respective districts then lakou waa, a hiki ma kekahi
began to haul the canoes until kipapali, o Nawaahookui ka inoa,
they came to a cliff about six eono iwilei kona kiekie, pela no
yards high at a place called ka hana a pau na waa eono,
Nawaahookui 15 where all six aohe waa i hiki loa i kai. Nolaila,
canoes got stuck fast, not one haalele lakou i na waa, a hoi aku
being able to get down to the la a hiki i mua o Kalaepuni,
beach. Therefore the people left ninau mai la o Kalaepuni:
the canoes where they were and “Auhea na waa?” Olelo aku o
returned to Kalaepuni. When Kalaehina: “Ua kauo mai nei
Kalaepuni saw the people he makou a kahi i haalele aku nei,
asked: “Where are the canoes?” he wahi kipapali, aia i laila kahi i
Kalaehina replied: “We hauled ili ai na waa a eono.” A lohe o
them until we could not get them Kalaepuni, huhu loa iho la ia i
past a certain place by a cliff and kona kaikaina, olelo aku la: “Aole
we have left them there all stuck anei au i hoonoho aku ia oe i
fast.” When Kalaepuni heard this luna maluna o na kanaka a pau,
he became very angry at his a no ke aha la oe i hooponopono
younger brother and said to him: ole ai e like me ka’u olelo ia oe?
“Did I not put you over all the Nolaila, o oe hookahi ke pii e
men? Why did you not make kauo mai i na waa, o na
them carry out my orders? You [207]kanaka a pau e noho lakou
must therefore go and haul them aole make pii, a i hiki ole na waa
down by [206]yourself. The rest of ia oe, alaila, kau ia oe i kanaka
the people shall not go to assist no ka heiau.”
you, and if you will not be able to
get the canoes down you shall
be a sacrifice for the temple.”

When Kalaehina heard the A lohe o Kalaehina i keia mau

command given him by his older olelo a kona kaikuaana, makau
brother he was much frightened, loa iho la ia, i ka hiki ole o na
for he believed that he was waa ia ia, noonoo iho la ia mai
unable to get the canoes down. ka po a ao, mai ke ao a po, hele
He, however, began to study the aku la ia a kahi o na waa i waiho
matter and all that night and the ai, nana iho la a haalele, hele
next day he spent in making aku la ia a hiki i Kau. Malaila o
plans as to how to overcome this Kalaehina i olelo ai me ka
most difficult matter. After at last hoopunipuni, penei kana mau
hitting on a plan he went up to olelo i ko Kau poe: “E na kanaka
the place where the canoes were o Kau nei, i kauoha mai nei ke
lying, took a look at them and ’lii, o Kalaepuni ia’u, e olelo aku
proceeded to Kau. When he ia oukou, e hele e kauo i na
arrived in Kau he deceived the waa.” A lohe na kanaka i keia
people, saying: “Ye people of olelo a Kalaehina, ia manawa,
Kau, the king, Kalaepuni has akoakoa koke mai lakou a kahi o
given me orders to tell you to go na waa i kau ai, oia o Kapua.
and haul the canoes down to the Hapai ae la na kanaka i na waa
beach.” When the people heard a kahi kupono e kauo ai, a lana i
this they all started for Kapua. loko o ke kai. Hoe ia aku la elima
Upon arriving at the place, the waa ma ka moana, a hiki i
people lifted up the canoes, Keauhou, kahi a Kalaepuni e
carried them to a place from noho ana, hookahi waa mahope
where they could be dragged to me Kalaehina. O ia waa i koe
the beach and placed in the sea; mahope, auamo ae la o
five of them were then paddled Kalaehina a hele mai la mauka a
to Keauhou, where Kalaepuni hiki i Kainaliu, auamo aku la o
was stopping, while Kalaehina Kalaehina a hiki imua o
followed behind with the other Kalaepuni kona kaikuaana,
canoe on his back, coming by mahalo iho la o Kalaepuni i kona
the upper road to Kainaliu. When kaikaina no ka ikaika loa i ke
Kalaepuni saw this he praised amo waa.
his younger brother for being so
strong.

When the day of celebration of A hiki mai ka la hookahakaha o

Kalaepuni arrived the king ke ’lii o Kalaepuni, ia la i hoike ai
displayed his brother’s strength o Kalaehina i kona ikaika i mua o
in the presence of all the people. na mea a pau loa. Lalau iho la ia
Kalaehina took up one of the six hookahi waa o na waa eono i
canoes and threw it into the sea kauo ia mai ai, a pahee aku la i
as though it was a spear, without loko o ke kai, me he ihe la, a me
much effort. A few days after this he mea ole la ia ia. Nana aku la
Kalaehina saw the king’s chief o Kalaehina i na aipuupuu a ke
steward chopping firewood, he ’lii, e kaka wahie ana, lalau iho la
picked up a stick of wood and ia hookahi pauku wahie, a hahau
struck it with his head, breaking iho la i kona poo, a okaoka liilii
the stick into small bits, thus loa, lilo iho la ka paa o ka ohia i
making the hard ohia appear as mea ole.
nothing.

When Kalaepuni saw how strong No keia ikaika o Kalaehina, olelo

Kalaehina, his brother, was, he mai o Kalaepuni: “E kuu
said: “My younger brother, we kaikaina, pomaikai kaua, i ko
are indeed fortunate because of kaua ikaika nui. Lilo ae nei au i
our great strength. I have alii no Hawaii nei ma kuu ikaika,
become king of Hawaii through e aho e holo oe i Maui e luku i
my great strength, now I think it na pua alii o laila, a e noho alii
well of you to go to Maui and kill ma ko Kamalalawalu wahi.” Ae
all the offspring of the chiefs of aku o Kalaehina i ka olelo a
that island so that you can kona kaikuaana, a Kalaepuni,
reign 16 in place of noho iho la ia a hala na la kapu
Kamalalawalu.” Kalaehina heiau o Hawaii, a hala ia, holo
agreed to this request of his aku la ia i Maui.
brother. At the close of the kapu
days set apart for the sacrifices
of the temple in Hawaii he set
sail for Maui.

When Kalaehina arrived at A hiki o Kalaehina ma Hana i

Hana, Maui, the people at the Maui, ia wa, he aha mokomoko
time were engaged in games of ka ke ’lii o Maui, a Kamalalawalu
strength and skill of the king of ma ka puu o Kauiki, e akoakoa
Maui, Kamalalawalu, at the hill of ana na kanaka he lehulehu, me
Kauwiki. Great crowds of people ka puloulou kapu o ke ’lii, ae aku
were gathered and the kapu la o Kalaehina maluna o ia kapu,
sticks separating the king’s lalau iho la i ka puloulou, a lilo i
palace from the people were put mea ole i loko o kona mau lima.
up. When Kalaehina saw them, A ike o Kamalalawalu ke ’lii i
he took them down 17 and boldly keia mau hana a Kalaehina,
entered into the place reserved kena ae la ia i ka lehulehu, e lele
for the king. When Kamalalawalu maluna o Kalaehina a pepehi. A
the king saw these doings of makaukau ka lima o ka lehulehu
Kalaehina he ordered the people e pepehi ia Kalaehina, ia wa o
to jump on Kalaehina and kill Kalaehina i pulumi ai me kona
him. As the people were about to mau lima i na kanaka, e like me
place their hands on him, he na naonao liilii loa, e kuolo ia
swept them off their feet as ana, pela ka hana ana o
though they were but ants, killing Kalaehina ia lakou. Ma keia
a large number of them. 18 At hana a Kalaehina, ua makau o
sight of this great strength, Kamalalawalu, a mahuka aku la
Kamalalawalu was so afraid that a noho ma ka punawai o
he escaped to a pool of water at Waianapanapa, aia ia wahi ma
Waianapanapa 19 which lies in Honokolani ma Hana a hiki i keia
Honokolani, Hana, and this pool la.
of water is there to this day.

Kalaehina then became the Lilo ae la o Kalaehina i alii no

king 20 of Maui and he reigned in Maui, ma ko Kamalalawalu noho
the place of Kamalalawalu. This alii ana, kui aku la keia kaulana
fact was reported from Hawaii to mai Hawaii a Niihau, i ka ikaika o
Niihau and his great strength Kalaehina a me kona noho alii
and succession as king of Maui ana no Maui ma kahi o
was the one topic of Kamalalawalu. [208]
conversation.

1 Strength, especially if combined with

skill, ever called forth Hawaiian
admiration. ↑
 Gaining fame fed Kalaepuni’s ambitions
2
for ruling power so that he sought to
remove all likely opponents. ↑
3 This successor of Umi seems to
have lost all his father’s power and
strength of character. ↑
4 This act, showing courage and skill,
has its counterpart in various
traditions. In this case it materially
aided his game of bluff. ↑
5 A story indicative of his great
strength, aimed to advance his fame
and interests, and intimidate the king. ↑
6 This memorial pile of king Umi, on
the plateau of central Hawaii at an
elevation of some 5000 feet, is
remarkable in several features. It not
only is the sole structure of the kind, of
hewn stone, but isolated from
habitations, the purpose or object of
which is not fully known. ↑
7 A falsehood that Kalaepuni quickly
took advantage of, as his
successor. ↑
8 Evidently a period of quiet
meditation induced sober second
thought that called for priestly aid to
strengthen the throne. ↑
9 Well digging was unusual among
Hawaiians. Probably the only
instance known up to the dawn of
civilization in these islands, was the
attempt by Kamehameha to sink a well
near the south point of Hawaii. ↑
10 Olona, a shrub (Touchardia latifolia)
that was cultivated for its highly
prized fiber for twine and fish-nets. ↑
11 The channel between Maui and
Hawaii. ↑
12 Fate seems to be coming the priest’s
way, that should land the object of
his prayers at the place designed for
his demise. ↑
13 Productive valleys near Lahaina,
Maui. ↑ a b
14 Kupala, a vegetable root eaten only
in times of great scarcity of food. ↑
15 The name indicates the incident,
“canoes stuck fast.” ↑
16 Kalaehina, recognized as
possessing great strength, is
designated an aspirant for the kingship
of Maui. ↑
17A defiant act, desecrating any
premises indicated as kapu, or
sacred. ↑
18 Intimidating his opponents by feats
of strength. ↑
19 Waianapanapa, dazzling water. ↑
20 Kalaehina becomes king of Maui, as
his brother became king of Hawaii,
through the hiding in fear of the rightful
rulers. ↑

[Contents]
Legend of Kapakohana. Kaao no Kapakohana.

Kapakohana was the strongest Oia ko Kauai kanaka ikaika loa,

man on Kauai 1 and because of a oia ke noho ana ma ko Ola
his great strength he, too, was wahi, ko Kauai alii nui. A lohe oia
reigning in place of Ola, 2 the i ko Kalaehina ikaika, makemake
great king of that island. When iho la oia e holo mai e hakaka
rumors of the great strength of me Kalaehina. Holo mai la ia mai
Kalaehina reached him he Kauai mai a pae ma Oahu, mai
became very anxious to meet Oahu mai a pae ma Honuaula i
Kalaehina. After making his Maui, kau na waa i laila, hele
preparations he set sail from aku la mauka a hiki i Kipahulu,
Kauai and first landed on Oahu; ahiahi iho la, moe malaila, i kau
from Oahu he set sail for Maui, hale kamaaina.
landing at Honuaula, where he
left his canoe and walked to
Kipahulu. That night he slept at a
house where he was befriended.

The people of the place asked Ninau mai la kamaaina: “Mahea

him: “Where are you going and kau wahi hele? A mai hea mai
where are you from?” He replied: nei oe.” Olelo aku keia: “Mai
“I am from Kauai and am on a Kauai mai nei au, e hele ana i ka
journey of sight seeing. I am makaikai a hiki i Hana a puni o
going to Hana and from there I Maui nei, alaila, hoi ia Kauai.” I
will make a complete circuit of mai na kamaaina: “Minamina
the island of Maui. After that I wale ko kanaka maikai, i ka
shall return to Kauai.” The make i ke ’lii huhu o makou, ia
people then said: “What a great Kalaehina, e aho e hoi oe.” I aku
pity that such a good looking o Kapakohana: “He huhu no ka
man 3 like you should be killed by ia i ka mea hele malie ma ke
our ill-tempered king Kalaehina. alanui.” “Ae, he huhu no, he oi
You had better return home.” kela o ke kanaka huhu a me ka
Kapakohana said: “Will he then ikaika, ua noke ia na ’lii a me na
get angry with a person who koa, aohe puko momona ia ia, a
goes quietly along the highway?” ua mahuka ke ’lii o makou, o
“Yes, he will get angry. He is the Kamalalawalu a holo, no ka
most violent tempered man and makau.” Ninau aku o
is also very powerful. He has Kapakohana: “Heaha na
destroyed most all the chiefs and hoailona ikaika ona a oukou i ike
warriors on the island and he ai?” “Eia, e hiki ia ia e huhuki i
pays homage to no one. Our na laau nunui e ulu ana, a e hiki
king, Kamalalawalu, has ia ia e kaka i kana wahie ma
escaped for fear of him.” kona poo (me he koi la ka oi), ke
Kapakohana then questioned lohi ke kaka ana o na aipuupuu.
them further: “What has he done Ina he la koele, aohe pane leo,
to show that he is powerful?” aohe walaau, nolaila kau ka weli
“Here, he can pull up large trees i na kanaka a pau nona, oia la i
by the roots, and he chops his lohe oe.” I aku o Kapakohana:
firewood with his head when the “Aohe hoi ha he ikaika, he ikaika
stewards act slow. On the king’s huhuki laau wale iho la no, ehia
labor days the people are not auanei au puupuu holo ia.” I mai
allowed 4 to talk for they all fear na kamaaina: “Aole oe e pakele,
him. That’s it that you may he ikaika auanei kela a kana
know.” Kapakohana then replied: mai.” Olelo aku o Kapakohana i
“He is not so very strong then, na kamaaina: “Ina e aa mai ia
seeing that his main strength is ia’u e hakaka maua, lealea loa
only in the pulling up of trees. au.”
With a few blows from my fists
he will run away.” The people
with whom he was staying said:
“You will not have any chance
against him for he is very
strong.” Kapakohana remarked:
“I would be pleased to meet him
in combat if he will say so.”

That night Kapakohana spent Moe iho la lakou a ao ia po, hele

with his friends. On the next day aku la o Kapakohana a hiki ma
he proceeded on his way and Kaiwiopele i Hana, ma keia hele
arrived at Kaiwiopele in Hana. In ana o Kapakohana, hahai pu
this journey the people with aku la na kamaaina o kona hale i
whom he had spent the night moe ai, e ike i ko laua hakaka
accompanied him, 5 for they were ana.
anxious to see the combat.

When Kapakohana arrived in the A hiki o Kapakohana i mua o

presence of Kalaehina, Kalaehina, nana mai la o
Kalaehina looked up and saw a Kalaehina a ike he kanaka e
man standing before him. He hoea aku ana i mua ona. Kahea
then called out in a loud voice: “I mai la o Kalaehina, me ka leo
will tear you up! 6 I will tear you nui: “E nahae auanei! E nahae
up!” When Kalaehina was auanei!” Ia manawa a Kalaehina
making this threat, the people i kahea ai, ke aloha nei ka
took pity on [210]Kapakohana, for lehulehu [211]ia Kapakohana i ka
they were sure that he would be make ia Kalaehina. A hiki o
killed. Kapakohana, however, Kapakohana i mua o ke alo o
fearlessly held his ground. When Kalaehina a me na kanaka
he saw the people working and mahiai, nana aku la ia, aohe
not a word could be heard from pane leo, aohe walaau, no ka
them, he knew that what he had mea, ua kau o Kalaehina i ke
heard was indeed true. kanawai, no ka walaau. Ia wa,
Kalaehina then prepared himself makaukau o Kalaehina e hopu ia
to grapple with Kapakohana. Kapakohana, a ike o
When Kapakohana saw that Kapakohana ia anehenehe o
Kalaehina was about to take Kalaehina, e hopu ia ia, kahea