-
Notifications
You must be signed in to change notification settings - Fork 5
API
There are two general contexts where code run:
- Build system: The place you call processFile()/processString() from.
- Metaprogram: The file/Lua string being processed. (All examples on this page are in this context, unless noted otherwise.)
All global functions that are available to metaprograms are also available to the build system through the library:
-- Build system context:
local pp = require("preprocess") -- Examples on this page assume the library has been required into `pp`.
local luaString = pp.toLua("foo")
-- Metaprogram context:
!local luaString = toLua("foo")Global functions in metaprograms:
- concatTokens
- copyTable
- eachToken
- escapePattern
- fileExists
- getCurrentPathIn (only during processing)
- getCurrentPathOut (only during processing)
- getFileContents
- getNextUsefulToken
- isToken
- newToken
- outputLua (only during processing)
- outputValue (only during processing)
- pack
- printf
- removeUselessTokens
- run
- serialize
- tokenize
- toLua
- unpack
Exported stuff from the library:
- (all the functions above)
- VERSION
- metaEnvironment
- processFile
- processString
luaString = concatTokens( tokens )
Concatinate tokens by their representations.
local tokens = {}
table.insert(tokens, newToken("identifier", "foo"))
table.insert(tokens, newToken("punctuation", "="))
table.insert(tokens, newToken("string", "bar"))
local luaString = concatTokens(tokens) -- foo="bar"copy = copyTable( table [, deep=false ] )
Copy a table, optionally recursively (deep copy). Multiple references to the same table and self-references are preserved during deep copying.
for index, token in eachToken( tokens [, ignoreUselessTokens=false ] ) do
Loop through tokens.
escapedString = escapePattern( string )
Escape a string so it can be used in a pattern as plain text.
local s = "2*5=10"
print(s:match("2*5")) -- Matches "5"
print(s:match(escapePattern("2*5"))) -- Matches "2*5"contents, error = getFileContents( path [, isTextFile=false ] )
Get the entire contents of a binary file or text file. Returns nil and a message on error.
bool = fileExists( path )
Check if a file exists.
path = getCurrentPathIn( )
Get what file is currently being processed, if any.
path = getCurrentPathOut( )
Get what file the currently processed file will be written to, if any.
token, index = getNextUsefulToken( tokens, startIndex [, steps=1 ] )
Get the next token that isn't a whitespace or comment. Returns nil if no more tokens are found. Specify a negative steps value to get an earlier token.
bool = isToken( token, tokenType [, tokenValue=any ] )
Check if a token is of a specific type, optionally also check it's value.
local tokens = tokenize("local foo = 123")
local token1 = tokens[1]
if token1 and isToken(token1, "keyword", "if") then
print("We got an if statement.")
endtoken = newToken( tokenType, ... )
Create a new token. Different token types take different arguments.
commentToken = newToken( "comment", contents [, forceLongForm=false ] )
identifierToken = newToken( "identifier", identifier )
keywordToken = newToken( "keyword", keyword )
numberToken = newToken( "number", number [, numberFormat="auto" ] )
punctuationToken = newToken( "punctuation", symbol )
stringToken = newToken( "string", contents [, longForm=false ] )
whitespaceToken = newToken( "whitespace", contents )
preprocessorToken = newToken( "pp_entry", isDouble )commentToken = { type="comment", representation=string, value=string, long=isLongForm }
identifierToken = { type="identifier", representation=string, value=string }
keywordToken = { type="keyword", representation=string, value=string }
numberToken = { type="number", representation=string, value=number }
punctuationToken = { type="punctuation", representation=string, value=string }
stringToken = { type="string", representation=string, value=string, long=isLongForm }
whitespaceToken = { type="whitespace", representation=string, value=string }
preprocessorToken = { type="pp_entry", representation=string, value=string, double=isDouble }-
"integer"(e.g. 42) -
"float"(e.g. 3.14) -
"scientific"(e.g. 0.7e+12) -
"SCIENTIFIC"(e.g. 0.7E+12 (upper case)) -
"hexadecimal"(e.g. 0x19af) -
"HEXADECIMAL"(e.g. 0x19AF (upper case)) "auto"
Note: Infinite numbers and NaN always get automatic format.
outputLua( luaString1, ... )
Output one or more strings as raw Lua code. Raises an error if no file or string is being processed.
local funcName = "doNothing"
outputLua("local function ", funcName, "()\n")
outputLua("end\n")outputValue( value1, ... )
Output one or more values, like strings or tables, as literals. Cannot output functions or userdata. Raises an error if no file or string is being processed.
outputLua("local person = ")
outputValue({name="Barry", age=49})values = pack( value1, ... )
Put values in a new table.
values.n is the amount of values (which can be zero) including any nil values.
Alias for table.pack() in Lua 5.2+.
local function getValues()
return 99, nil, "hello"
end
local values = pack(getValues())
print(#values) -- Either 3 or 1 depending on interpreter implementation details. Unreliable!
print(values.n) -- 3
print(unpack(values, 1, values.n)) -- 99, nil, "hello"printf( formatString, value1, ... )
Print a formatted string.
Same as print(formatString:format(value1, ...)).
removeUselessTokens( tokens )
Remove whitespace and comment tokens.
returnValue1, ... = run( path [, arg1, ... ] )
Execute a Lua file, optionally sending it extra arguments. Similar to dofile().
local docs = run("scripts/downloadDocumentation.lua", "perl")success, error = serialize( buffer, value )
Same as toLua() except adds the result to an array instead of returning the Lua code as a string.
local buffer = {}
table.insert(buffer, "local person = ")
serialize(buffer, {name="Barry", age=49})
local luaString = table.concat(buffer)
outputLua(luaString)
-- Output: local person = {age=49,name="Barry"}tokens, error = tokenize( luaString [, allowPreprocessorTokens=false ] )
Convert Lua code to tokens. Returns nil and a message on error. See newToken() for token fields and types. Additional token fields:
-
line: Token start line number. -
lineEnd: Token end line number. -
position: Starting position in bytes.
luaString, error = toLua( value )
Convert a value to a Lua literal. Does not work with certain types, like functions or userdata. Returns nil and a message if an error ocurred.
local person = {name="Barry", age=49}
local luaString = toLua(person)
outputLua("local person = ", luaString)
-- Output: local person = {age=49,name="Barry"}value1, ... = unpack( table [, fromIndex=1, toIndex=#table ] )
Is the normal unpack() in Lua 5.1 and alias for table.unpack() in Lua 5.2+.
All global functions that are available to metaprograms are also here (like getFileContents() etc.).
pp.VERSION
The version of LuaPreprocess, e.g. "1.8.0".
pp.metaEnvironment
The environment used for metaprograms (and the message handler in the command line program).
-- Build system context:
pp.metaEnvironment.theValue = "Hello"
-- Metaprogram context:
!print(theValue) -- HelloprocessedFileInfo, error = pp.processFile( params )
Process a Lua file.
-
processedFileInfo: Table with various information (see processedFileInfo), or nil if an error happened. -
error: Error message, or nil if no error happened. -
params: Table with the following fields:
pathIn = pathToInputFile -- [Required]
pathOut = pathToOutputFile -- [Required]
pathMeta = pathForMetaprogram -- [Optional] You can inspect this temporary output file if an error ocurrs in the metaprogram.
addLineNumbers = boolean -- [Optional] Add comments with line numbers to the output.
debug = boolean -- [Optional] Debug mode. The metaprogram file is formatted more nicely and does not get deleted automatically.
backtickStrings = boolean -- [Optional] Enable the backtick (`) to be used as string literal delimiters. Backtick strings don't interpret any escape sequences and can't contain backticks.
onAfterMeta = function( luaString ) -- [Optional] Here you can modify and return the Lua code before it's written to 'pathOut'.
onBeforeMeta = function( ) -- [Optional] Called before the metaprogram runs.
onError = function( error ) -- [Optional] You can use this to get traceback information. 'error' is the same value as what is returned from processFile().luaString, processedFileInfo = pp.processString( params )
Process Lua code.
-
processedFileInfo: Table with various information (see processedFileInfo), or a message if an error happened. -
params: Table with the following fields:
code = luaString -- [Required]
pathMeta = pathForMetaprogram -- [Optional] You can inspect this temporary output file if an error ocurrs in the metaprogram.
addLineNumbers = boolean -- [Optional] Add comments with line numbers to the output.
debug = boolean -- [Optional] Debug mode. The metaprogram file is formatted more nicely and does not get deleted automatically.
backtickStrings = boolean -- [Optional] Enable the backtick (`) to be used as string literal delimiters. Backtick strings don't interpret any escape sequences and can't contain backticks.
onBeforeMeta = function( ) -- [Optional] Called before the metaprogram runs.
onError = function( error ) -- [Optional] You can use this to get traceback information. 'error' is the same value as what is returned from processString().Table returned from processFile() and processString(). Contains these fields:
-
path: Path to the processed file. This is empty if processString() was used. -
outputPath: Path to the outputted file. This is empty if processString() was used. -
processedByteCount: The length of the processed data in bytes. -
lineCount: Total line count. -
linesOfCode: Amount of lines with code. -
tokenCount: Total token count. -
hasPreprocessorCode: Whether any preprocessor code was encountered.