From 6a1f7450156fb70ed6ac3841b2291ecd569271c0 Mon Sep 17 00:00:00 2001
From: Reuh <fildadut@reuh.eu>
Date: Mon, 7 Jun 2021 17:16:31 +0200
Subject: [PATCH] Update README

---
 README.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 805972c..c9215ba 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,13 @@ Unlike Moonscript, Candran tries to stay close to the Lua syntax, and existing L
 #import("lib.thing") -- static import
 #local debug or= false
 
+#if debug
+#	define("log(...)", "print(...)")
+#else
+#	define("log(...)", "") -- remove calls to log from the compiled code when debug is true
+#end
+log("example macro") -- preprocessor macros
+
 local function calculate(toadd=25) -- default parameters
 	local result = thing.do()
 	result += toadd
@@ -448,9 +455,34 @@ The preprocessor has access to the following variables:
 * ````include(filename)````: a function which copy the contents of the file _filename_ to the output.
 * ````write(...)````: write to the preprocessor output. For example, ````#write("hello()")```` will output ````hello()```` in the final file.
 * ```placeholder(name)```: if the variable _name_ is defined in the preprocessor environement, its content will be inserted here.
+* ```define(identifier, replacement)```: define a macro. See below.
 * each arguments passed to the preprocessor is directly available in the environment.
 * and every standard Lua library.
 
+#### Macros
+
+Using `define(identifier, replacement)` in the preprocessor, you can define macros. Both identifier and replacement are expected to be string containing Candran/Lua code.
+
+There are two types of macros: variables, which replace every instance of the given identifier with the replacement text; and functions, which will replace every call to this function with the replacement text, also replacing its arguments. The `...` will be replaced with every remaining argument. Macros can not be recursive.
+
+If the replacement text is empty, the macro will simply be removed from the compiled code.
+
+```lua
+-- Variable macro
+#define("x", 42)
+print(x) -- 42
+
+-- Function macros
+#define("f(x)", "print(x)")
+f(42) -- replaced with print(42)
+
+#define("log(s, ...)", "print(s..": ", ...)")
+log("network", "error") -- network: error
+
+#define("debug()", "")
+debug() -- not present in complied code
+```
+
 Compile targets
 ---------------
 Candran is based on the Lua 5.4 syntax, but can be compiled to Lua 5.4, Lua 5.3, Lua 5.2, LuaJIT, and Lua 5.1 compatible code.
@@ -567,8 +599,8 @@ The table returned by _require("candran")_ gives you access to:
 
 ##### Compiler & preprocessor
 * ````candran.VERSION````: Candran's version string (e.g. `"0.10.0"`).
-* ````candran.preprocess(code[, options])````: return the Candran code _code_, preprocessed with the _options_ options table; or nil, err in case of error.
-* ````candran.compile(code[, options])````: return the Candran code compiled to Lua with the _options_ option table; or nil, err in case of error.
+* ````candran.preprocess(code[, options])````: return the Candran code _code_, `macros` table. The code is preprocessed with the _options_ options table; `macros` is indented to be passed to `candran.compile` to apply the defined macros. In case of error, returns nil, error.
+* ````candran.compile(code[, options[, macros]])````: return the Candran code compiled to Lua with the _options_ option table and the macros `macros` (table returned by the preprocessor); or nil, err in case of error.
 * ````candran.make(code[, options])````: return the Candran code, preprocessed and compiled with the _options_ options table; or nil, err in case of error.
 
 ##### Code loading helpers