Skip to content

Command Line

Jump to bottom
ReFreezed edited this page Jul 12, 2021 · 14 revisions

Note: The documentation has moved to the LuaPreprocess website. Information here may be out of date!

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=logs/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

--backtickstrings

--backtickstrings

[v1.11.2] Enable backtick strings.

--data

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

[v1.9] A string with any data. If this option is present then the value will be available through the global dataFromCommandLine in the processed files (and any message handler). Otherwise, dataFromCommandLine is nil.

--faststrings

--faststrings

[v1.13.1] Force fast serialization of string values. (Non-ASCII characters will look ugly.)

--handler

--handler=pathToMessageHandler or -h=pathToMessageHandler

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

--jitsyntax

--jitsyntax

[v1.12] Allow LuaJIT-specific syntax, specifically literals for 64-bit integers and complex numbers.

--linenumbers

--linenumbers

Add comments with line numbers to the output.

--meta

--meta

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

--nonil

--nonil

[v1.11.2] Disallow !(...) and outputValue(...) from outputting nil.

--novalidate

--novalidate

[v1.12] Disable validation of outputted Lua.

--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 with this option.

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

--outputpaths

--outputpaths or -o

[v1.9] 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

Messages are sent when events happen, for example before a metaprogram runs or after the output has been written to file.

There are two ways of catching and handling messages (in the file specified by --handler) - either by returning a function or a table. If the file returns a function then it will be called with various messages as its first argument. If the file returns a table, the keys should be the message names and the values should be functions to handle the respective message. (See below.)

The file shares the same environment as the processed files, making it a good place to put things all files use/share in their metaprogram (i.e. global functions and other values).

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"

[v1.11] Sent for each @insert "name" statement. The handler is expected to return a Lua code 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 exits).

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.
Clone this wiki locally