Added macro example. Added @@func() as short version of @insert func().

Author: ReFreezed

examples/macros.lua2p

@@ -0,0 +1,46 @@
+--[[============================================================
+--=
+--=  LuaPreprocess example: Macros.
+--=
+--=  Here we define a better assert function using a macro.
+--=
+--============================================================]]
+
+!(
+local DEBUG = true
+
+function assert(conditionCode, messageCode)
+	if not DEBUG then
+		-- Make assert() calls do absolutely nothing if we're not in debug mode.
+		return ""
+	end
+	if not messageCode then
+		messageCode = string.format("%q", "Assertion failed: "..conditionCode)
+	end
+	return "if not ("..conditionCode..") then  error("..messageCode..")  end"
+end
+)
+
+local i = 4
+
+--
+-- A call to Lua's normal assert function might look something like this. A
+-- problem is that the message expression is evaluated even if the condition
+-- is true, which is completely unnecessary. (This example is very simple of
+-- course, but imagine more costly operations happening.)
+--
+assert(i > 1 and i < 7, "Invalid index. It must be 1<=i<=7 but is "..i)
+
+--
+-- By prepending @insert we actually call the assert function in the
+-- metaprogram which, as we defined above, separates the condition and the
+-- message arguments so that the message expression never evaluates as long as
+-- the condition is true.
+--
+@insert assert(i > 1 and i < 7, "Invalid index. It must be 1<=i<=7 but is "..i)
+
+-- We also made the default message better by including the condition code
+-- itself in the message.
+@insert assert(i > 1 and i < 7)
+
+print("'i' is all good!")

examples/macros.output.lua

@@ -0,0 +1,31 @@
+--[[============================================================
+--=
+--=  LuaPreprocess example: Macros.
+--=
+--=  Here we define a better assert function using a macro.
+--=
+--============================================================]]
+
+local i = 4
+
+--
+-- A call to Lua's normal assert function might look something like this. A
+-- problem is that the message expression is evaluated even if the condition
+-- is true, which is completely unnecessary. (This example is very simple of
+-- course, but imagine more costly operations happening.)
+--
+assert(i > 1 and i < 7, "Invalid index. It must be 1<=i<=7 but is "..i)
+
+--
+-- By prepending @insert we actually call the assert function in the
+-- metaprogram which, as we defined above, separates the condition and the
+-- message arguments so that the message expression never evaluates as long as
+-- the condition is true.
+--
+if not (i > 1 and i < 7) then  error("Invalid index. It must be 1<=i<=7 but is "..i)  end
+
+-- We also made the default message better by including the condition code
+-- itself in the message.
+if not (i > 1 and i < 7) then  error("Assertion failed: i > 1 and i < 7")  end
+
+print("'i' is all good!")

preprocess.lua

@@ -5,6 +5,7 @@
 --=
 --=  License: MIT (see the bottom of this file)
 --=  Website: https://github.com/ReFreezed/LuaPreprocess
+--=  Documentation: https://github.com/ReFreezed/LuaPreprocess/wiki
 --=
 --=  Tested with Lua 5.1, 5.2, 5.3 and 5.4.
 --=
@@ -37,8 +38,8 @@
 
 	How to metaprogram:
 
-	The exclamation mark (!) is used to indicate what code is part
-	of the metaprogram. There are 4 ways to write metaprogram code:
+	The exclamation mark (!) is used to indicate what code is part of
+	the metaprogram. There are 4 main ways to write metaprogram code:
 
 	!...     The line will simply run during preprocessing. The line can span multiple actual lines if it contains brackets.
 	!!...    The line will appear in both the metaprogram and the final program. The line must be an assignment.
@@ -79,10 +80,10 @@
 
 	-- Extended preprocessor line. (Lines are consumed until brackets
 	-- are balanced when the end of the line has been reached.)
-	!newClass{
+	!newClass{ -- Starts here.
 		name  = "Entity",
 		props = {x=0, y=0},
-	}
+	} -- Ends here.
 
 	-- Preprocessor block.
 	!(
@@ -100,27 +101,22 @@
 
 	-- Dual code (both preprocessor line and final output).
 	!!local partial = "Hello"
-	local   whole   = partial..!(partial..", world!")
+	local   whole   = partial .. !(partial..", world!")
 	print(whole) -- HelloHello, world!
 
 	-- Beware in preprocessor blocks that only call a single function!
-	!(func())  -- This will bee seen as an inline block and output whatever value func() returns as a literal.
-	!(func();) -- If that's not wanted then a trailing ";" will prevent that. This line won't output anything by itself.
-	-- When the full metaprogram is generated, "!(func())" translates into "outputValue(func())"
-	-- while "!(func();)" simply translates into "func();" (because "outputValue(func();)" would be invalid Lua code).
-	-- Though in this specific case a preprocessor line would be nicer:
+	!( func()  ) -- This will bee seen as an inline block and output whatever value func() returns as a literal.
+	!( func(); ) -- If that's not wanted then a trailing `;` will prevent that. This line won't output anything by itself.
+	-- When the full metaprogram is generated, `!(func())` translates into `outputValue(func())`
+	-- while `!(func();)` simply translates into `func();` (because `outputValue(func();)` would be invalid Lua code).
+	-- Though in this specific case a preprocessor line (without the parenthesis) would be nicer:
 	!func()
 
---============================================================]]
+	-- For the full documentation, see: https://github.com/ReFreezed/LuaPreprocess/wiki
 
+--============================================================]]
 
 
---[[ Make sure the library doesn't add globals.
-setmetatable(_G, {__newindex=function(_G, k, v)
-	print(debug.traceback("WARNING: Setting global '"..tostring(k).."'.", 2))
-	rawset(_G, k, v)
-end})
---]]
 
 local PP_VERSION = "1.12.0"
 
@@ -206,7 +202,7 @@ local _tokenize
 local assertarg
 local copyTable
 local countString, countSubString
-local error, errorline, errorOnLine, errorInFile, errorAtToken
+local error, errorLine, errorOnLine, errorInFile, errorAtToken
 local errorIfNotRunningMeta
 local escapePattern
 local F, tryToFormatError
@@ -232,9 +228,9 @@ function tryToFormatError(err0)
 	local err, path, ln = nil
 
 	if type(err0) == "string" then
-		do               path, ln, err = err0:match'^(%a:[%w_/\\.]+):(%d+): (.*)'
-		if not err then  path, ln, err = err0:match'^([%w_/\\.]+):(%d+): (.*)'
-		if not err then  path, ln, err = err0:match'^(.-):(%d+): (.*)'
+		do               path, ln, err = err0:match"^(%a:[%w_/\\.]+):(%d+): (.*)"
+		if not err then  path, ln, err = err0:match"^([%w_/\\.]+):(%d+): (.*)"
+		if not err then  path, ln, err = err0:match"^(.-):(%d+): (.*)"
 		end end end
 	end
 
@@ -296,7 +292,7 @@ function error(err, level)
 	currentErrorHandler(err, level)
 end
 
-function errorline(err)
+function errorLine(err)
 	print(tryToFormatError(err))
 	currentErrorHandler(err, 2)
 end
@@ -674,9 +670,14 @@ function _tokenize(s, path, allowMetaTokens, allowBacktickStrings, allowJitSynta
 
 		-- Preprocessor: Keyword.
 		elseif allowMetaTokens and s:find("^@", ptr) then
-			local i1, i2, repr, word = s:find("^(@([%a_][%w_]*))", ptr)
-			ptr = i2+1
-			tok = {type="pp_keyword", representation=repr, value=word}
+			if s:find("^@@", ptr) then
+				ptr = ptr+2
+				tok = {type="pp_keyword", representation="@@", value="insert"}
+			else
+				local i1, i2, repr, word = s:find("^(@([%a_][%w_]*))", ptr)
+				ptr = i2+1
+				tok = {type="pp_keyword", representation=repr, value=word}
+			end
 
 		else
 			return nil, errorInFile(s, path, ptr, "Tokenizer", "Unknown character.")
@@ -1179,7 +1180,7 @@ function metaFuncs.run(path, ...)
 	assertarg(1, path, "string")
 
 	local mainChunk, err = loadLuaFile(path, metaEnv)
-	if not mainChunk then  errorline(err)  end
+	if not mainChunk then  errorLine(err)  end
 
 	-- We want multiple return values while avoiding a tail call to preserve stack info.
 	local returnValues = pack(mainChunk(...))
@@ -1627,7 +1628,7 @@ local function processKeywords(tokensRaw, fileBuffers, params, stats)
 				if not (isTokenAndNotNil(tokNext, "string") or isTokenAndNotNil(tokNext, "identifier")) then
 					errorAtToken(
 						fileBuffers, ppKeywordTok, (tokNext and tokNext.position or ppKeywordTok.position+#ppKeywordTok.representation),
-						"Parser", "Expected a string or identifier after @insert."
+						"Parser", "Expected a string or identifier after %s.", ppKeywordTok.representation
 					)
 				end
 
@@ -1950,7 +1951,7 @@ local function _processFileOrString(params, isFile)
 		luaUnprocessed, err = getFileContents(pathIn)
 
 		if not luaUnprocessed then
-			errorline("Could not read file: "..err)
+			errorLine("Could not read file: "..err)
 		end
 
 		currentPathIn  = params.pathIn
@@ -2376,7 +2377,7 @@ local function _processFileOrString(params, isFile)
 		if type(luaModified) == "string" then
 			lua = luaModified
 		elseif luaModified ~= nil then
-			errorline("onAfterMeta() did not return a string. (Got "..type(luaModified)..")")
+			errorLine("onAfterMeta() did not return a string. (Got "..type(luaModified)..")")
 		end
 	end
 

tests/quickTest.lua2p

@@ -22,6 +22,12 @@ a = a..!(b)..a -- Comment, string concat.
 !local bool = --[[ Just a multiline
 comment here...]] true
 
+!local function wrapped(concept)
+	print!("Get wrapped! Also, "..concept.."...")
+!end
+!wrapped("dogs")
+!wrapped("clouds")
+
 
 
 !(
@@ -108,7 +114,7 @@ local ok = 1==1
 
 !local function PASS_THROUGH(lua)  return lua  end
 local s = @insert PASS_THROUGH "foo"
-local t = @insert PASS_THROUGH { 496, b=true }
+local t = @@      PASS_THROUGH { 496, b=true } -- @@func() means the same as @insert func().
 
 local f = @insert PASS_THROUGH(function(a, b)
 	while true do

tests/quickTest.output.lua

@@ -66,9 +66,18 @@ local ok = 1==1
 if not (ok) then error("Oh "..tonumber("7",10).." noes!") end
 
 local s = "foo"
-local t = { 496, b=true }
+local t = { 496, b=true } -- @@func() means the same as @insert func().
 
+local f = function(a, b)
+	while true do
+		repeat until arePlanetsAligned("mars", "jupiter")
+		break
+	end
+	return "", nil
+end
 
 
+
+-- Misc.
 print("dataFromCommandLine: Hello, world!")
 print("The end.")

tests/runExamples.cmd

@@ -2,11 +2,13 @@
 CD /D "%~dp0.."
 
 SETLOCAL EnableDelayedExpansion
+SET _fails=0
 
 FOR /R examples %%G IN (*.lua2p) DO (
 	ECHO. & ECHO Processing example '%%~nxG'...
 	lua preprocess-cl.lua "%%G" --debug --silent
-	IF !ERRORLEVEL! EQU 0  lua "%%~dpnG.lua"
+	IF !ERRORLEVEL! EQU 0 ( lua "%%~dpnG.lua" ) ELSE ( SET /A "_fails=!_fails!+1" )
 )
 
-ECHO. & ECHO All examples finished!
+ECHO.
+IF %_fails% EQU 0 ( ECHO Finished examples successfully. ) ELSE ( ECHO Finished examples with %_fails% failures. )