Lua: add Version type to simplify comparisons

Version specifiers like `PANDOC_VERSION` and `PANDOC_API_VERSION` are
turned into `Version` objects. The objects simplify version-appropriate
comparisons while maintaining backward-compatibility.

A function `pandoc.types.Version` is added as part of the newly
introduced module `pandoc.types`, allowing users to create version
objects in scripts.

1 files changed, 42 insertions, 9 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 3b3bb2f17..a5a7f2922 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -151,21 +151,21 @@ variables.
 :   Table of the options which were provided to the parser.
 
 `PANDOC_VERSION`
-:   Contains the pandoc version as a numerically indexed table,
-    most significant number first. E.g., for pandoc 2.1.1, the
-    value of the variable is a table `{2, 1, 1}`. Use
-    `table.concat(PANDOC_VERSION, '.')` to produce a version
-    string. This variable is also set in custom writers.
+:   Contains the pandoc version as a [Version object] which
+    behaves like a numerically indexed table, most significant
+    number first. E.g., for pandoc 2.7.3, the value of the
+    variable is equivalent to a table `{2, 7, 3}`. Use
+    `tostring(PANDOC_VERSION)` to produce a version string. This
+    variable is also set in custom writers.
 
 `PANDOC_API_VERSION`
 :   Contains the version of the pandoc-types API against which
     pandoc was compiled. It is given as a numerically indexed
     table, most significant number first. E.g., if pandoc was
     compiled against pandoc-types 1.17.3, then the value of the
-    variable will be a table `{1, 17, 3}`. Use
-    `table.concat(PANDOC_API_VERSION, '.')` to produce a version
-    string from this table. This variable is also set in custom
-    writers.
+    variable will behave like the table `{1, 17, 3}`. Use
+    `tostring(PANDOC_API_VERSION)` to produce a version string.
+    This variable is also set in custom writers.
 
 `PANDOC_SCRIPT_FILE`
 :   The name used to involve the filter. This value can be used
@@ -178,6 +178,8 @@ variables.
     variable is of type [CommonState](#type-ref-CommonState) and
     is read-only.
 
+[Version object]: #type-ref-Version
+
 # Pandoc Module
 
 The `pandoc` lua module is loaded into the filter's lua
@@ -1353,6 +1355,32 @@ available to readers and writers.
 A pandoc log message. Object have no fields, but can be converted
 to a string via `tostring`.
 
+## Version {#type-ref-Version}
+
+A version object. This represents a software version like
+"2.7.3". The object behaves like a numerically indexed table,
+i.e., if `version` represents the version `2.7.3`, then
+
+    version[1] == 2
+    version[2] == 7
+    version[3] == 3
+    #version == 3   -- length
+
+Comparisons are performed element-wise, i.e.
+
+    Version '1.12' > Version '1.9'
+
+### `must_be_at_least`
+
+`must_be_at_least(actual, expected [, error_message])`
+
+Raise an error message if the actual version is older than the
+expected version.
+
+Usage:
+
+    PANDOC_VERSION:must_be_at_least('2.7.3')
+
 [Block]: #type-ref-Block
 [List]: #module-pandoc.list
 [MetaValue]: #type-ref-MetaValue
@@ -2726,3 +2754,8 @@ Parameters:
 Returns:
 
 -   The result(s) of the call to `callback`
+
+
+# Module pandoc.types
+
+Constructors for types which are not part of the pandoc AST.