Merge branch 'lua-code-combine' into up-to-date

Author: jdutant

Makefile

@@ -2,6 +2,16 @@
 FILTER_FILE := $(wildcard *.lua)
 # Name of the filter, *without* `.lua` file extension
 FILTER_NAME = $(patsubst %.lua,%,$(FILTER_FILE))
+# Source files
+#	Optional: build the filter file from multiple sources.
+#	*Do not comment out!* To deactivate it's safer to
+#	define an empty SOURCE_MAIN variable with:
+# 	SOURCE_MAIN =
+SOURCE_DIR =
+SOURCE_MAIN =
+SOURCE_MODULES =
+#
+SOURCE_FILES = $(SOURCE_MAIN:%=$(SOURCE_DIR)%.lua) $(SOURCE_MODULES:%=$(SOURCE_DIR)%.lua)
 
 # Allow to use a different pandoc binary, e.g. when testing.
 PANDOC ?= pandoc
@@ -42,6 +52,45 @@ help:
 	'/^## / h ; /^[^_.$$#][^ ]+:/ { G; s/^(.*):.*##(.*)/\1@\2/; P ; h ; }' \
 	$(MAKEFILE_LIST) | tr @ '\t'
 
+#
+# Build
+#
+
+## Build the filter file from sources (requires luacc)
+# If SOURCE_MAIN is not empty, combine source files with
+# luacc and replace the filter file.
+# ifeq is safer than ifdef (easier for the user to make
+# the variable empty than to make it undefined).
+.PHONY: build
+build: _build
+
+ifneq ($(SOURCE_MAIN), )
+.PHONY: _build
+_build: _check_luacc $(SOURCE_FILES)
+	@if [ -f $(QUARTO_EXT_DIR)/$(FILTER_FILE) ]; then \
+		luacc -o $(QUARTO_EXT_DIR)/$(FILTER_FILE) -i $(SOURCE_DIR) \
+			$(SOURCE_DIR)/$(SOURCE_MAIN) $(SOURCE_MODULES); \
+		if [ ! -L $(FILTER_FILE) ]; then \
+		    ln -s $(QUARTO_EXT_DIR)/$(FILTER_FILE) $(FILTER_FILE); \
+		fi \
+	else \
+		luacc -o $(FILTER_FILE) -i $(SOURCE_DIR) \
+			$(SOURCE_DIR)/$(SOURCE_MAIN) $(SOURCE_MODULES); \
+	fi
+else
+.PHONY: _build
+_build:
+
+endif
+
+.PHONY: check_luacc
+_check_luacc:
+	@if ! command -v luacc &> /dev/null ; then \
+		echo "LuaCC is needed to build the filter. Available on LuaRocks:"; \
+		echo " https://luarocks.org/modules/mihacooper/luacc"; \
+		exit; \
+	fi
+
 #
 # Test
 #
@@ -62,7 +111,7 @@ test: $(FILTER_FILE) test/input.md test/test.yaml
 # would cause it to be regenerated on each run, making the test
 # pointless.
 .PHONY: generate
-generate: $(FILTER_FILE) test/input.md test/test.yaml
+generate: build $(FILTER_FILE) test/input.md test/test.yaml
 	@for ext in $(FORMAT) ; do \
 		$(PANDOC) --defaults test/test.yaml --to $$ext \
 		--output test/expected.$$ext ; \
@@ -142,7 +191,7 @@ $(QUARTO_EXT_DIR)/$(FILTER_FILE): $(FILTER_FILE) $(QUARTO_EXT_DIR)
 
 ## Sets a new release (uses VERSION macro if defined)
 .PHONY: release
-release: quarto-extension regenerate
+release: build quarto-extension generate
 	git commit -am "Release $(FILTER_NAME) $(VERSION)"
 	git tag v$(VERSION) -m "$(FILTER_NAME) $(VERSION)"
 	@echo 'Do not forget to push the tag back to github with `git push --tags`'

README.md

@@ -152,6 +152,53 @@ contents of this README, an example generated from the test input,
 as well as the full filter code. The page components are combined
 with the `.tools/docs.lua` filter.
 
+#### `build`
+
+Build the filter from multiple source files. Use this target if you
+want to develop the filter as multiple source files but distribute
+it in a single source.
+
+Requires [Lua Code Combiner][luacc], available on LuaRocks. Install
+with `luarocks install luacc` (requires [LuaRocks][luarocks]).
+
+[luacc]: https://luarocks.org/modules/mihacooper/luacc
+[luarocks]: https://luarocks.org
+
+__Setup__. Suppose your source files are as follows:
+
+```
+/path/to/filter
+    |-src/
+         |-main.lua
+         |-module1.lua
+         |-module2.lua
+```
+
+Where `main.lua` uses the module files with the standard Lua
+function `require('module1')` or `myvar = require('module2')`.
+
+Edit the Makefile lines below as follows:
+
+```
+SOURCE_DIR = src/
+SOURCE_MAIN = main
+SOURCE_MODULES = module1 module2
+```
+
+__Usage__. `build` uses LuaCC to combine the main source and its
+module into a single Lua file which will **replace** your filter's
+file. It is automatically called when using `generate` and `release`.
+
+
+Deactivate by setting  `SOURCE_MAIN` to be empty:
+
+```
+SOURCE_MAIN =
+```
+
+Commenting this line out is not recommended, as the variable
+may remain defined in your shell session.
+
 ### Website
 
 The repository template comes with a GitHub Action to publish a