The table of contents

The Table of Contents

See the Brainstorming page for some context.

Note: At this point we strive for completeness of the TOC. Here should go everything we think that is worth writing in the Cookbook, without regard for the book size. Please don't hesitate to add more just because "there is too much stuff already".

If you want to write a particular article, add your name next to it. Even if there is a name already, please don't hesitate to add yours as well! We will either split article in two — if there are two significantly different views on the problem, or share writing in some other way — nobody can write everything after all.

If you miss your pet topic and don't sure where it should go, please add it to the end of the page.

TODO: This is a cookbook. Most articles should be (perhaps implicitly) along the "how do I" or, at least "what does it mean" lines.

I. Cover

II. Copyright

III. Table of Contents

Part I: Introduction

About the language
- Why Lua?
- The philosophy
Installing Lua
- Overview: embedded vs. Lua-centric approach.
  
  In the light of approaches to the code installation, with the link to the later section with details.
- Building Lua from source
  - With GCC
  - With MSVC
- Building LuaJIT2 from source
  - With GCC
  - With MSVC
- Installing Lua on your OS from binary distributions
  - Windows, raw
  - Windows, Cygwin / MinGW
  - Windows, Lua for Windows
  - OS X, raw
  - OS X, Macports
  - Ubuntu
- Alternative implementations
  - LuaJIT2
  - Java
  - .Net
  - Flash
  - JavaScript
  - Metalua
- Editors and IDEs. Where to edit Lua code
Version information
- Differences in 5.2
  - list them, point to the specific chapters for more information

Part II: Generic recipes

Booleans
- Introduction
- no boolean tricks in Lua?
Numbers
- Introduction
  - Only one numeric type: the double
  - What every computer scientist needs to know about floating point numbers
  - 0 evaluates to true
  - Coercion
  - NaN is not a first class value
- no number tricks in Lua?
Tables
- Introduction
  - Passed as reference
  - Metatables
- Table length and Holes
  - Annotated array idiom
  - __len Lua 5.2
- Deep copying of tables
- Automagic table
- Proxy tables
- Read-only tables
- Lazy tables
- Cache tables Weak keys, values, keys+values. Perils.
- Functables
- Slices. As in Penlight
Strings
- Introduction
  - Immutability
  - s[10] does not work
  - UTF-8, binary-safe strings, using in string literals, libraries for full support
- Creating strings piece by piece. using both table.concat and LTN009
- String ropes.
- String weaving. As in LTN.
- Simple string template engine with gsub.
- Where to get conventional regular expressions in Lua. And why you should use LPeg instead.
- LPeg tips and tricks.
Functions
- Introduction
  - First-class value
  - Closures
  - Lexical scoping
  - Environments refer to the proper chapter
  - Tail recursion
  - Syntax sugar
    - function foo() end == foo = function() end
    - local function foo() end == local foo; foo = function () end
    - Braceless calls
- Mutually recursive local functions
- "Iterating" with tail recursion
- Simple state machine using tail recursion
- Function factories such as pairs and ipairs, demonstrates closures
- Memoization
- Tablefuncs
- Function decorators
Nil
- Introduction
  - Not a first-class value
  - Evaluates to false
  - Represents the absence of a mapping for a key in a table
- Storing nils in tables
- function a() end ~= function a() return nil end tostring(a()) fails on the first a()
Coroutines
- Coroutines as an alternative to state machines
- Using coroutines for animation
- Simple coroutine scheduler
Userdata
- Introduction
- newproxy
- More userdata hackery
Data Structures
- Introduction
  - some data structures can be done with functions instead of tables. Pros and cons should be discussed somewhere
- Linear array
- Multidimensional array
- Lists Cheap insert/delete operations.
- Queues
- Stacks
- Records
- Dictionaries / Maps
- Sets
- Tuples
- Objects Duck typing. References to next chapters.
- Nested tables as a graph
  - Nested tables as a graph basics
  - How to traverse nested tables, with and without self-references
  - A generic way to traverse a graph with up/down callbacks
Dates and Times
Files
Iterators
- Introduction
  - generic for's iterator protocol
- Rolling your own iterators
- Iterating with coroutines Lua 5.2, resumable VM patch for 5.1
- Chaining iterators
- Filters
- Examples
  - range, ordered by criteria, traversing a tree with coroutines...
Varargs
- Introduction
  - also not a first-class value
  - cannot be an upvalue
  - select, unpack and (...)
- Variable Assignment with Varargs the local _, _, a = ... pattern
- Selecting the First N Elements
- Appending One Element
- Combining
- Reversing
- Vararg Saving
- The map Function
- The filter Function
- Iterating over Varargs
Scopes, Environments and Sandboxing
- Introduction
  - load* functions
- strict declaration with the strict module
- locals vs globals by default
- Lexical environment tricks Lua 5.2
- Approaches to run-time global environment protection
- Basic techniques: setfenv. Also: Why sandboxing is useful even if you're running trusted code
- The list of sandbox-safe functions. What is safe out-of the box, what should be left out, and what is safe with precautions.
- Advanced: debug hooks, ulimit. Memory limits.
- Live programming: (re)loading new code into a continuously running Lua state (like in Erlang)
Error Handling and Resource Management
- Introduction
  - pcall, xpcall, error, assert
- return nil, err vs error
- Resource Acquisition Is Initialization
- try / catch vs Exceptions refer to Lua Gems?
- state of the Lua nation on resource cleanup
  - probably some of the approaches should be shown here
Modules and Packaging
- Introduction
- Basics: dofile, loadfile, require, package.path, package.cpath. When installing third-party modules manually, you're on your own.
- Exporting a module with module: pros and cons. also: considered harmful
- Exporting a module without module
- How to unload a module
- How to reload a module
- Selective export exporting a function or object to control access to the module's symbols
- Lazy importing as in Penlight
- Installing third-party modules with LuaDist
- Installing third-party modules with LuaRocks
  - Installing LuaRocks
    - On Linux / OS X, with GCC, from source
    - On Windows, binaries
  - Using LuaRocks to install, update and remove a module. Also: luarocks.require
  - Creating a minimal Lua module with a rockspec file. (agladysh)
- How to build an executable from a bunch of Lua code (on Linux and Windows)
Hacks and Hidden Features maybe we should rename the chapter :)
- LuaHacks which hacks?
- Hidden Features which features?

Part III: Programming paradigms

Object-oriented and prototype-based programming
- Three ways to create an object: table, metatable, closures; pros and cons
- Inheritance / prototypes with metatables
- Hiding a member from the child class using unique keys (agladysh)
- Protecting private object members: why you should not do this, and how to do it if you must
- Existing OOP frameworks
- How to create a proxy object system for non-Lua APIs (agladysh)
Functional programming
- Replacing goto with tail recursion (catwell)
- Map-reduce, filter, fold (catwell)
- Currying, Y-combinator, anonymous recursion...
- More?
Domain-Specific Languages distinguish external and internal DSLs?
- Using Lua as a language for config files
- Creating a simple DDL with Lua (agladysh)
- Minimal DSL with Lua by hand
- Techniques
  - Dynamic finders as in Ruby on Rails
  - Operator definition with Metatables used in Placeholder Expressions and LPeg
  - loadstring-style code generation
  - orbit.htmlify-style code generation
  - Using LPeg to create a DSL LPeg's own re module is a perfect example
  - Metalua extensions just refer to the Modifying Lua section?
- Examples maybe show them in the Techniques section instead of a separate section
  - Short Anonymous Functions
  - List Comprehensions
  - Placeholder Expressions
  - State machines

Part IV: Applied recipes

Design Patterns
- Some GOF design patterns in Lua? This is an old, but good read
Testing, Profiling, Debugging
- Testing
  - Known libraries Lunit, Shake, any others?
- Profiling
- Debugging
LuaJIT
- Advantages and Limitations
- API Extensions
Interactivity
- Console programming
  - Terminal colors
  - CLI arguments parsing
  - ncurses
Persistence
- Simple do-it yourself table serialization (agladysh)
- How to serialize data to Lua source code.
- How to serialize to common formats
  - XML
  - JSON
  - PHP's serialize()
  - AMF
- Modules for fast binary serialization.
- How to serialize everything. Pluto
- Using databases with Lua
- Using Redis with Lua (catwell)
Multithreading, Concurrent and Event-driven Programming
- Event handlers
- Connection handlers
- GIL in Lua, LuaThreads is a dead end, use forks.
- Simple Lua job processor, by hand.
- Existing solutions: Lanes, Rings, concurrentlua etc. Feature table (platform, interpreter constraints, communication, locking etc).
The Web
- LuaSocket, lua-ev
- Simple server by hand, Kepler stuff overview
- HTTP-servers overview
- Web-frameworks overview
- Web scraping with Lua (http libraries including ssl)
- Working with XML
  - Saving Lua data to XML without extra libraries
  - Overview of XML modules for Lua
- Working with JSON
  - Saving Lua data to JSON without extra libraries
  - Overview of JSON modules for Lua
- Web Services
  - RPC
  - Using SOAP LuaSoap
  - Interacting with Web-service APIs in Lua Spore?
Alternative Hardware
- elua
- pblua
- other embedded hardware stuff

Part V: Embedding Lua

Bringing Lua in Covers bringing Lua in, not working with API. With comments on LJ2 specifics where aplicable.
- In C for Linux
- In C++ for Linux
- In C for Windows (MSVC)
- In C++ for Windows (MSVC)
- In Java for PC
- In Java for mobile devices
- In .Net for PC (Windows)
- In .Net for PC (Mono)
- In ActionScript for Flash (agladysh)
- In JavaScript
- In Objective C for iOS (agladysh)
- In Python
- In Perl
Lua C API
- Guidelines for writing Lua-C interface Write in Lua first. Keep interface surface minimal. Write dead simple in C, wrap it in Lua so it is comfortable.
- How to keep Lua data stack under control (agladysh)
- How to work with Lua tables from C
- How to work with Lua from C++
- How to setup a sandbox from C Including detecting loop-hanged scripts when calling from C
- Minimal C module with a rockspec (agladysh)
- Guidelines for building C modules
  - On Linux
  - On OS X
  - On Windows with GCC
  - On Windows with MSVC
- How to bind a C "object" to Lua with plain API
- How to bind C++ object to Lua with plain API
- Overview of existing binding libraries. And why you should use raw API
- Overview of existing binding generators. And when you should use them
Examples
- World of Warcraft somebody will complain if nothing's mentioned about it :)
- Löve and other Lua-centric and Lua-aware game engines (Where to use Lua? How can I try to work with Lua while having fun?) Other applications which embed Lua?

Part VI: Playing at meta-level

Static code analysis
- Simple off-line global environment protection. By means of bytecode analysis
- Existing Lua linters:
  - lua-inspect
  - lualint
  - more?
- Roll your own simple Lua analyzer with Metalua
Modifying Lua
- Precautions. Think twice before creating yet another dialect.
- What does that stuff in luaconf.h mean?
- How to modify Lua to use fixed-point integers as Lua numbers by hand
- LNUM and other existing Power-patches
- Token filters
- Source code transformations
  - Lua parser overview
  - Metalua
    - show examples from the DSL chapters in Metalua?
  - more?
- Simple Metalua extension

Part VII: Afterword

Where to get more information
- Books
- Tutorial sites
- Mailing lists, forums, stackoverflow
- Where to find modules
- How to share code
Glossary
Alphabetic Index
Back cover

TODO

Homeless topics:

Documentation generation
GUIs with Lua
Plotting with Lua
POSIX
Working with bits and why you should avoid it