modules/codegen: Add wrapper for lex/flex/reflex

This module is a bit of a dumping ground for code generators,
particularly ones that are important and non-trivial to wrap, either due
to multiple implementations, major command line changes, or complex
outputs (such as those that may output a directory structure).

The initially provided method is for lex. It provides a simple wrapper
that handles win_flex, reflex, flex, and generic lex.

5 files changed, 86 insertions, 0 deletions

diff --git a/docs/markdown/Codegen-module.md b/docs/markdown/Codegen-module.md
new file mode 100644
index 000000000..5c2618d6b
--- /dev/null
+++ b/docs/markdown/Codegen-module.md
@@ -0,0 +1,80 @@
+---
+short-description: Common Code Generators Module
+authors:
+    - name: Dylan Baker
+      email: dylan@pnwbakers.com
+      years: [2024, 2025]
+...
+
+# Codegen Module
+
+*(New in 1.10.0)*
+
+This module provides wrappers around common code generators, such as flex/lex. This purpose of this is to make it easier and more pleasant to use *common* code generators in a mesonic way.
+
+## Functions
+
+### lex()
+
+```meson
+lex_gen = codegen.lex(implementations : ['flex', 'reflex'], flex_version : ['>= 2.6', '< 3'], reflex_version : '!= 1.4.2')
+```
+
+This function provides fine grained control over what implementation(s) and version(s) of lex are acceptable for a given project (These are set per-subproject). It returns a [new object](#lexgenerator), which can be used to generate code.
+
+It accepts the following keyword arguments:
+
+ - `implementations`: a string array of acceptable implementations to use. May include: `lex`, `flex`, `reflex`, or `win_flex`.
+ - `lex_version`: a string array of version constraints to apply to the `lex` binary
+ - `flex_version`: a string array of version constraints to apply to the `flex` binary
+ - `reflex_version`: a string array of version constraints to apply to the `relex` binary
+ - `win_flex_version`: a string array of version constraints to apply to the `win_flex` binary
+ - `required`: A boolean or feature option
+ - `disabler`: Return a disabler if not found
+ - `native`: Is this generator for the host or build machine?
+
+## Returned Objects
+
+### LexGenerator
+
+#### lex.implementation
+
+```meson
+lex = codegen.lex()
+impl = lex.implementation()
+```
+
+Returns the string name of the lex implementation chosen. May be one of:
+
+- lex
+- flex
+- reflex
+- win_flex
+
+#### lex.generate
+
+```meson
+lex = codegen.lex()
+lex.generate('lexer.l')
+```
+
+This function wraps flex, lex, reflex (but not RE/flex), and win_flex (on Windows). When using win_flex it will automatically add the `--wincompat` argument.
+
+This requires an input file, which may be a string, File, or generated source. It additionally takes the following options keyword arguments:
+
+- `args`: An array of extra arguments to pass the lexer
+- `plainname`: If set to true then `@PLAINNAME@` will be used as the source base, otherwise `@BASENAME@`.
+- `source`: the name of the source output. If this is unset Meson will use `{base}.{ext}` with an extension of `cpp` if the input has an extension of `.ll`, or `c` otherwise, with base being determined by the `plainname` argument.
+- `header`: The optional output name for a header file. If this is unset no header is added
+- `table`: The optional output name for a table file. If this is unset no table will be generated
+
+The outputs will be in the form `source [header] [table]`, which means those can be accessed by indexing the output of the `lex` call:
+
+```meson
+lex = codegen.lex()
+l1 = lex.generate('lexer.l', header : '@BASENAME@.h', table : '@BASENAME@.tab.h')
+headers = [l1[1], l1[2]]  # [header, table]
+
+l2 = lex.generate('lexer.l', table : '@BASENAME@.tab.h')
+table = l2[1]
+```
diff --git a/docs/markdown/_Sidebar.md b/docs/markdown/_Sidebar.md
index ce73d5aad..eb6afb60f 100644
--- a/docs/markdown/_Sidebar.md
+++ b/docs/markdown/_Sidebar.md
@@ -9,6 +9,7 @@
 
 ### [Modules](Module-reference.md)
 
+* [codegen](Codegen-module.md)
 * [gnome](Gnome-module.md)
 * [i18n](i18n-module.md)
 * [pkgconfig](Pkgconfig-module.md)
diff --git a/docs/markdown/snippets/codegen_module.md b/docs/markdown/snippets/codegen_module.md
new file mode 100644
index 000000000..b4ea04c0a
--- /dev/null
+++ b/docs/markdown/snippets/codegen_module.md
@@ -0,0 +1,3 @@
+## Experimental Codegen module
+
+A new module wrapping some common code generators has been added. Currently it supports lex/flex.
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index c8cb48cf1..b3967a27f 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -38,6 +38,7 @@ index.md
 		Code-formatting.md
 		Modules.md
 			CMake-module.md
+			Codegen-module.md
 			Cuda-module.md
 			Dlang-module.md
 			External-Project-module.md
diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html
index 65a21a260..f16489896 100644
--- a/docs/theme/extra/templates/navbar_links.html
+++ b/docs/theme/extra/templates/navbar_links.html
@@ -7,6 +7,7 @@
   <ul class="dropdown-menu" id="modules-menu">
     @for tup in [ \
             ("CMake-module.html","CMake"), \
+            ("Codegen-module.html","Codegen"), \
             ("Cuda-module.html","CUDA"), \
             ("Dlang-module.html","Dlang"), \
             ("External-Project-module.html","External Project"), \