LuaPreprocess - a small and straightforward Lua preprocessor featuring a simple syntax. Write embedded metaprograms to generate code using normal Lua inside your Lua files.

LuaPreprocess is written in pure Lua. The library is a single file with no external dependencies. MIT license. A separate command line program is available too.

• Example Program
• Usage
  • Library
  • Command Line
• Documentation
• Help

Example Program

The exclamation mark (!) is used to indicate what code is part of the metaprogram. (See screenshot of processing steps with highlighting)

-- Normal Lua.
local n = 0
doSomething()

-- Preprocessor lines.
!local IS_DEVELOPER = true
initGame()
!if IS_DEVELOPER then
	enableCheats()
!else
	enableTelemetry()
!end

function newArrayOfThreeBits()
	return {
		!for i = 1, 3 do
			0,
		!end
	}
end

-- Extended preprocessor line. (Lines are consumed until brackets
-- are balanced when the end of the line is reached.)
!defineClass{
	name  = "Entity",
	props = {x=0, y=0},
}

-- Preprocessor block.
!(
local hashLib = require("md5")
function getHash()
	return hashLib.calculate("Hello, world!")
end
)

-- Preprocessor inline block. (Expression that returns a value.)
local text = !("Precalculated hash: "..getHash())

-- Preprocessor inline block variant. (Expression that returns a Lua code string.)
!!("myRandomGlobal"..math.random(9)) = "foo"

Output

-- Normal Lua.
local n = 0
doSomething()

-- Preprocessor lines.
initGame()
enableCheats()

function newArrayOfThreeBits()
	return {
		0,
		0,
		0,
	}
end

-- Extended preprocessor line. (Lines are consumed until brackets
-- are balanced when the end of the line is reached.)
function newEntity() return {__name="Entity",x=0,y=0} end

-- Preprocessor block.

-- Preprocessor inline block. (Expression that returns a value.)
local text = "Precalculated hash: 6CD3556DEB0DA54BCA060B4C39479839"

-- Preprocessor inline block variant. (Expression that returns a Lua code string.)
myRandomGlobal4 = "foo"

See the examples folder for more. (See also an example for the LÖVE framework.)

Usage

First you need Lua installed on your system. (Binaries can be downloaded from LuaBinaries via SourceForge if you don't want to, or can't, compile Lua from source. For Windows I can recommend installing LuaForWindows which is a "batteries included" Lua package.)

Preprocess Files Using the Library

local pp = require("preprocess")

local info, err = pp.processFile{
	pathIn   = "src/app.lua2p",     -- This is the file we want to process.
	pathOut  = "output/app.lua",    -- The output path.
	pathMeta = "temp/app.meta.lua", -- Temporary output file for the metaprogram.
}

if not info then
	error(err)
end

print("Lines of code processed: "..info.lineCount)

See the docs or the top of preprocess.lua for documentation.

Preprocess Files from the Command Line

Windows

Preprocess.cmd [options] filepath1 [filepath2 ...]
OR
Preprocess.cmd --outputpaths [options] inputpath1 outputpath1 [inputpath2 outputpath2 ...]

Any System

lua preprocess-cl.lua [options] filepath1 [filepath2 ...]
OR
lua preprocess-cl.lua --outputpaths [options] inputpath1 outputpath1 [inputpath2 outputpath2 ...]

If a filepath is, for example, C:/MyApp/app.lua2p then LuaPreprocess will write the processed file to C:/MyApp/app.lua.

See the docs, or the top of preprocess-cl.lua and preprocess.lua, for the options and more documentation.

Documentation

• Docs
• Library: See the top of preprocess.lua
• Command line: See the top of preprocess-cl.lua

Help

Got a question? If the documentation doesn't have the answer, look if someone has asked the question in the issue tracker, or create a new issue.