# Lua Power Patches |
| wiki

A power patch is a small patch to a source code distribution that makes some useful change. Power patches are judged based on how few lines of code are changed, general usefulness, and backwards compatibility. By limiting them to localized changes, the chance that several such patches can work together is high. It also keeps maintenance work to a minimum as new versions of the source package are released. Truly good patches will have a short life, as the authors of the original program will incorporate them into their code.

New power patches, ports of existing patches to different Lua versions, and bug fixes are welcome.

Don't forget that if you apply a patch that changes the syntax or semantics of Lua, the resulting language cannot be called "Lua".

### How to Apply a Patch

Unpack the correct Lua distribution into a clean directory. Do a `cd` to the top of the directory and run:

  `patch -p1 < patchfile`

### Patch Tools

- Unix, etc. users should have `diff` and `patch` in the standard installation. Some versions of patch (for example the one that comes with Solaris) don't support Unified Context diffs properly (the ones with + and - at the front of each line. GNU patch copes with this.
- Windows.
  - There is a version of the patch command for DOS (part of the DJGPP toolset) [1]. This has been tested, and works.
  - Another, more general solution for doing Unix tasks in Windows is Cygwin [2].

### Patch Guidelines

- adhere to style of surrounding code - This is important because you want the original author to happily incorporate your patch upstream. Be sure to match the indenting style (both width and use of real tabs or spaces).
- make patch adhering to guidelines in "NOTES FOR PATCH SENDERS" section of `patch` man page - The patch is made using the `diff` utility. For example assume you have a directory `lua` with the original Lua distribution, and adjacent to that is a copy called `lua_new` which includes your patches. Use the following sequence to make the patch. Be sure to look over the resulting patch file in case you had some extraneous temporary files in your patched tree. Also beware of "false diffs" that can be caused by lines with trailing spaces.

      cd lua
      make clean
      cd ../lua_new
      make clean
      cd ..
      diff -urN lua lua_new > mychange.patch

- the patch file should have unix line termination

## Available Patches

These are roughly in order of Lua version, newest to oldest.

### Advanced readline support

This patch adds the following features to the existing readline support in Lua 5.x:

- Completion of keywords and global variable names.
- Recursive and metatable-aware completion of variable names.
- Context sensitive delimiter completion.
- Save/restore of the history to/from a file (`LUA_HISTORY` environment variable).
- Setting a limit for the size of the history (`LUA_HISTSIZE` environment variable).
- Setting the application name to allow for `$if lua ... $endif` in `~/.inputrc`.

After applying the patch start lua and try these (replace `~` with the TAB key):

      ~~
      fu~foo() ret~fa~end<CR>
      io~~~s~~~o~~~w~"foo\n")<CR>

It has been verified to work with Lua 5.0, 5.0.2, 5.1-work0 and GNU readline 2.2.1, 4.0, 4.3 or NETBSD libedit 2.6.5, 2.6.9.

- Backwards compatible: yes
- Lines changed/added/deleted: ~250
- Lua authors' position: ?
- Author: MikePall
- Last update: 2004-May-28
- [download (for Lua 5.0 and 5.1-work0)]

### Bitwise operators and hexadecimal support

This patch adds the following features to Lua 5.x:

- Hexadecimal support for 0xXXX in numeric literals.
- Hexadecimal support for '\xXX' characters within strings.
- Infix bitwise operators for AND (&), OR (|) and XOR (#).
- Unary bitwise negation using # alone.

NOTE: This patch adds opcodes to the Lua virtual machine. The two major consequences of this are that (1) the result cannot be called 'Lua', and (2) compiled code will not run on interpreters that do not include this patch.

After applying the patch, try running the following:

      > hex=function(n) print("0x"..string.format("%X",n)) end
      > hex(0x54&0x55)
      0x54
      > hex(0x54|0x66)
      0x76
      > hex(0x54#0x66)
      0x32
      > hex(#0x45)
      0xFFFFFFBA
      > print("Hel\x6c\x6f world\x21")
      Hello world!
      >

This has been tested on Lua-5.0, -5.0.1, and -5.0.2.

- Backwards compatible: No (opcodes added)
- Lines changed/added/deleted: ~150
- Lua authors' position: ?
- Author: Doug.Rogers@innocon.com
- Last update: 2004-Jun-21
- [download (for Lua 5.0(.X))]

### __usedindex metatable patch

`__newindex` catches creation/assignment to new table indexes, but not to pre-existing ones. What if the old value had a back-reference to its parent? (`__gc` is not enough.) What if the changed value should be mirrored in a C data structure?

`__usedindex` will act the same as `__newindex`, except that `table[key]` will exist.

Example:

      function used(t,k,v)
         local o
         o = rawget(t,k)
         print("__usedindex",t,k,v,o)
         rawset(t,k,v)
      end
      function new(t,k,v)
         print("__newindex",t,k,v)
         rawset(t,k,v)
      end

- Backwards compatible: yes
- Lines changed/added/deleted: 6/16/0
- Lua authors' position: -
- Author: Christopher.Dunn@Motorola.com
- Last update: 2004-Feb-29
- [download (for Lua 5.0)]

### Make superfluous 'do' and 'then' tokens optional

Lua requires 'then' following an `if` statement, and 'do' following `while` and `for` statements. This patch makes them optional.

- Backwards compatible: yes
- Lines changed/added/deleted: 3/0/0
- Lua authors' position: unknown (MakeSuperfluousTokensOptional)
- Author: EricTetz
- Last update: 2003-Aug-30
- [download (for Lua 5.0)]

### Lua setconstant patch

Add a Lua function setconstant( table ), It will mark a table of strings or numbers as constant, so that the content of this table will never be garbage collected. Note that the table can be nested, and anything other than number and string will not be suited to this function.

- Backwards compatible: yes
- Lines changed/added/deleted: 0/80/23
- Lua authors' position: -
- Author: PaulLiu
- Last update: 2002-Jun-11
- [download (for Lua 4.0)]

### Unix/Win32 Makefiles

Changes the lua-4.1-work4 Makefiles so that it's easy to build the Lua libraries and executables under Win32 with MSVC, using GNU Make, by editing lua/config. Does not hurt Unix compatibility. The main difficulty is that Windows uses different file extensions and a few slightly different archiver/linker/compiler options. By using macros to stand for the file extensions, the config file can configure for either Unix or Win32, without having to edit the actual Makefiles.

- Lua version: lua-4.1-work4
- Backwards compatible: yes, this patch leaves all the existing Lua config defaults and should build under Unix the same as the standard distribution.
- Lines chagned/added/deleted: ?
- Lua authors' position: unknown
- Author: ThatcherUlrich
- Last update: 2002-Feb-18 (initial revision)
- Todo: More testing, and implement building of DLL's under Windows.
- [download]

### yield()

Changes the Lua VM so that calls from Lua to Lua functions are "stackless"; i.e. no execution state is stored on the C stack. Adds a `yield()` function to the Lua base library, which can be used to implement latent functions/cooperative multitasking. When a script calls `yield()`, the function call to `lua_dostring/lua_dofile/lua_dobuffer` from the host program returns with the code `LUA_YIELD`. The script's execution state is preserved in the `lua_State` structure, and a new API function, `lua_resume(L)`, can be used to continue the script's execution at some later time.

As a side benefit, this patch makes Lua's tailcalls (ones that use the `OP_TAILCALL` opcode) properly non-recursive.

- Backwards compatible: yes, provided there are no name collisions with "yield()".
- Lines changed/added/deleted: ~400
- Lua authors' position: An improved implementation is available in 5.0-alpha.
- Author: Thatcher Ulrich
- Last update: 2002-Jan-16 (fixed some bugs -ThatcherUlrich)
- Todo: There are still some bugs surrounding error handling. For example, from an interactive lua session, if you `'dofile("program.lua")'`, and `program.lua` does a `yield()`, Lua can crash. If possible, I recommend using the supported implementation in 5.0 instead.
- [download]

(was "sleep patch"; "yield" was deemed a better name for this functionality, so I changed the name. -ThatcherUlrich)

### Enhanced table constructors

The record part of table constructors (`field=value`) is modified so that function statements are allowed and the comma is optional now. So this becomes valid:

      x = {
        function foo() end
        function bar() end
        c=1
        d=2
      }

and is the same as:

      x = {
        foo=function() end,
        bar=function() end,
        c=1,
        d=2,
      }

The comma is still required in front of `[val]=val` records and in list initializers `({ expr, expr })`.

- Backwards compatible: yes
- Lines changed/added/deleted: 4/8/0
- Lua authors' position: Don't know
- Author: Edgar Toernig
- Last update: 2001-Dec-16
- [4.0 version]

### Local functions

New syntactic sugar for the local-statement:

      local foo(...) ... end

is the same as

      local foo foo=function(...) ... end

Note that `foo` is visible within the function. In Lua 4.0 that doesn't help a lot (in fact, an error is raised when `%foo` is accessed).

- Backwards compatible: yes
- Lines changed/added/deleted: 2/6/0
- Lua authors' position: Don't know
- Author: Edgar Toernig
- Last update: 2001-Dec-16
- [4.0 version] [4.1 version]

  I'm not used to Lua 4.1's code generator so that (more useful) version of this patch has to wait a little bit.

### Block Comments

Adds block comments to Lua: `--[[...]]`. Uses the long string parser (`[[...]]`) so block comments may be nested. Recommended usage:

      --[[---------
      Comment...
      --]]---------

That has the nice property that a block comment may be disabled by inserting a single space just before the first `[` (or by adding a single `-` before `--[[`).

- Backwards compatible: no, but unlikely to break existing programs.
- Lines changed/added/deleted: 4/10/0
- Lua authors' position: Considering this for Lua 4.1.
- Author: Edgar Toernig
- Last update: 2001-Dec-14
- [4.0 version] [4.1 version]

### lua_getcclosure()

Adds missing function to the API that retrieves closure values of a C function. (See lua-l message "pushcclosure / tocfunction issue" by John Belmonte, 2000-Oct-7.)

- Backwards compatible: yes
- Lines changed/added/deleted: 0/19/0
- Lua authors' position: Considering this for Lua 4.1. (See lua-l message "Re: pushcclosure / tocfunction issue" by Roberto Ierusalimschy, 2000-Oct-11.)
- Author: John Belmonte
- Last update: 2001-Feb-3
- [download]

### Nested Function Names

Changes parser to allow definition function names to be nested in more than one level of tables. (See lua-l message "Re: Son of Lua - Sol" by John Belmonte, 2001-Feb-2.)

The syntax becomes: `NAME {'.' NAME} [':' NAME]`

- Backwards compatible: yes
- Lines changed/added/deleted: 2/0/0
- Lua authors' position: Will be included in Lua 4.1. (See lua-l message "Re: index tag method" by Roberto Ierusalimschy, 2001-Feb-19.)
- Author: John Belmonte
- Last update: 2001-Feb-3
- [download]

### Weak References

Adds weak references to Lua. See http://www.lua.org/notes/ltn006.html.

- Backwards compatible: yes
- Lines changed/added/deleted: 0/77/0
- Lua authors' position: Will add weak tables to Lua 4.1. (See lua-l message "Re: Coroutine support in 4.1 / IPC mechanisms" by Luiz Henrique de Figueiredo, 2001-Apr-20.)
- Author: John Belmonte
- Last update: 2001-Feb-28
- [download]

### List Iteration For Construct

Adds another form of the `for` construct that iterates lists. Semantically equivalent to the standard library function `foreachi` (See lua-l message "list iteration for statement" by John Belmonte, 2001-Apr-26.)

- Backwards compatible: yes
- Lines changed/added/deleted: 5/88/0
- Lua authors' position: -
- Author: John Belmonte
- Last update: 2001-Jun-9
- [download]

### Lua autoconf patch

Autoconfiscates the Lua distribution (4.1work4).

- Backwards compatible: yes
- Lines changed/added/deleted: unknown
- Lua authors' position: - unlikely to be added to the distribution
- Author: unknown
- Last update: unknown
- [3]

### lua_dolines patch

Patch to Lua-4.0.1. Add

lua_dolines(lua_State *L, char *fname, FILE *f, int *lineno)

to the Lua API which executes Lua code from an already open file until '$' is encountered.

- Backwards compatible: yes
- Lines changed/added/deleted: 79
- Lua authors' position: will be obsoleted by lua_load in 5.0 (See lua-l message " Re: [ANNOUNCE] lua_dolines-1.1.patch" by Luiz Henrique de Figueiredo , 2002-Jul-29)
- Author: JuergenFuhrmann)
- Last update: 2002-Jul-29
- [Download][README]

### lua_gc_long patch

Patch to Lua-4.0.1.

This patch changes the way scaled integers are compared to longs. It actually is a bug fix, as otherwise, on typical 64 bit boxes, lua_setgcthreshold(L,0) does not work.

- Backwards compatible: yes
- Lines changed/added/deleted: 2
- Lua authors' position: already known, fixed in 5.0b (See lua-l message "Re: gc confusion: now resolved" by Roberto Ierusalimschy , 2003-Feb-20)
- Author: JuergenFuhrmann)
- Last update: 2003-Feb-21
- [Download][README]

FindPage · RecentChanges · preferences
edit · history
Last edited June 21, 2004 4:46 pm PDT (diff)