valentinchcloud/luapreprocess

A small and straightforward Lua preprocessor using simple syntax.

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

Example Program

The exclamation mark (!) is used to indicate what code is part of the metaprogram. (Screenshot)

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

-- Preprocessor lines.
initGame()
!if IS_DEVELOPER then
	enableCheats()
!end

function doNetworkStuff()
	!for i = 1, 3 do
		local success = connectToServer()
		if success then  return "Connected!"  end
	!end
	return "Failed to connect after 3 tries"
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 string.)
!!("myRandomGlobal"..math.random(9)) = "foo"

Output

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

-- Preprocessor lines.
initGame()
enableCheats()

function doNetworkStuff()
	local success = connectToServer()
	if success then  return "Connected!"  end
	local success = connectToServer()
	if success then  return "Connected!"  end
	local success = connectToServer()
	if success then  return "Connected!"  end

	return "Failed to connect after 3 tries"
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: C62D9E6C179835E2D4D2F4613BA054B5948D00E7"

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

See the examples folder for more.

Usage

First you of course 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   = "app.lua2p",    -- This is the file we want to process.
	pathMeta = "app.meta.lua", -- Temporary output file for the metaprogram.
	pathOut  = "app.lua",      -- The output path.
}

if not info then
	error(err)
end

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

See the top of preprocess.lua for documentation.

Preprocess files from the command line

Windows

Preprocess.cmd [options] filepath1 [filepath2 ...]

Any System

lua preprocess-cl.lua [options] filepath1 [filepath2 ...]

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

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