Command Line

• Command Line Usage
  • Examples
• Options
• Message Handlers
• Messages
• Other Info

Command Line Usage

Values inside square brackets ([]) are optional.

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 ...]

Exit codes:

• 0: The script executed successfully.
• 1: An error happened.

Examples

lua preprocess-cl.lua --saveinfo=misc/info.lua --silent src/main.lua2p src/network.lua2p
lua preprocess-cl.lua --debug src/main.lua2p src/network.lua2p
lua preprocess-cl.lua --outputpaths --linenumbers src/main.lua2p output/main.lua src/network.lua2p output/network.lua

Options

--data

--data="Any data." or -d="Any data."

A string with any data. If the option is present then the value will be available through the global dataFromCommandLine in the processed files (and the message handler, if you have one).

--handler

--handler=pathToMessageHandler or -h=pathToMessageHandler

Path to a Lua file that's expected to return a function or a table of functions. See Message Handlers and Messages for more info.

--linenumbers

--linenumbers

Add comments with line numbers to the output.

--meta

--meta

Output the metaprogram to a temporary file (*.meta.lua). This is useful if an error happens in the metaprogram. The file is removed if there's no error and --debug isn't enabled.

--outputextension

--outputextension=fileExtension

Specify what file extension generated files should have. The default extension is "lua". If any input files end with .lua then you must specify another file extension.

It's suggested that you use .lua2p (as in "Lua To Process") as extension for unprocessed files.

--outputpaths

--outputpaths or -o

This flag makes every other specified path be the output path for the previous path. Example:

lua preprocess-cl.lua --outputpaths src/main.lua2p output/main.lua src/network.lua2p output/network.lua

--saveinfo

--saveinfo=pathToSaveProcessingInfoTo or -i=pathToSaveProcessingInfoTo

Processing information includes what files had any preprocessor code in them, and things like that. The format of the file is a Lua module that returns processingInfo.

--silent

--silent

Only print errors to the console.

--debug

--debug

Enable some preprocessing debug features. Useful if you want to inspect the generated metaprogram (*.meta.lua). (This also enables the --meta option.)

--

--

Stop options from being parsed further. Needed if you have paths starting with "-".

Message Handlers

There are two ways to handle messages - either by returning a function or a table from the module. If it returns a function then it will be called with various messages as it's first argument. If it's a table, the keys should be the message names and the values should be functions to handle the respective message.

The file shares the same environment as the processed files, making it a good place to put things all files use/share.

Using Multiple Specific Message Handlers

-- messageHandler.lua
return {
	beforemeta = function(path)
		print("... Now processing "..path)
	end,

	aftermeta = function(path, luaString)
		-- Remove comments (quick and dirty).
		luaString = luaString
			:gsub("%-%-%[%[.-%]%]", "") -- Multi-line.
			:gsub("%-%-[^\n]*",     "") -- Single line.

		return luaString
	end,

	filedone = function(path, outputPath)
		print("... Done with "..path.." (writing to "..outputPath..")")
	end,
}

Using a Single Catch-All Message Handler

-- messageHandler.lua
return function(message, ...)
	if message == "beforemeta" then
		local path = ...
		print("... Now processing "..path)

	elseif message == "aftermeta" then
		local path, luaString = ...

		-- Remove comments (quick and dirty).
		luaString = luaString
			:gsub("%-%-%[%[.-%]%]", "") -- Multi-line.
			:gsub("%-%-[^\n]*",     "") -- Single line.

		return luaString

	elseif message == "filedone" then
		local path, outputPath = ...
		print("... Done with "..path.." (writing to "..outputPath..")")
	end
end

Messages

init

Sent before any other message.

Arguments:

• inputPaths: Array of file paths to process. Paths can be added or removed freely.
• outputPaths: If the --outputpaths option is present this is an array of output paths for the respective path in inputPaths, otherwise it's nil.

insert

Sent for each @insert statement. The handler is expected to return a Lua string.

Arguments:

• path: The file being processed.
• name: The name of the resource to be inserted (could be a file path or anything).

beforemeta

Sent before a file's metaprogram runs.

Arguments:

• path: The file being processed.

aftermeta

Sent after a file's metaprogram has produced output (before the output is written to a file).

Arguments:

• path: The file being processed.
• luaString: The produced Lua code. You can modify this and return the modified string.

filedone

Sent after a file has finished processing and the output written to file.

Arguments:

• path: The file being processed.
• outputPath: Where the output of the metaprogram was written.
• info: processedFileInfo.

fileerror

Sent if an error happens while processing a file (right before the program quits).

Arguments:

• path: The file being processed.
• error: The error message.

Other Info

processingInfo

Table saved by the --saveinfo option. Contains these fields:

• date: Datetime string of when the preprocessing began, e.g. "2019-05-21 15:28:34".
• files: Array of processedFileInfo.