From f9fb410cd962d0ca17d8de849e3839ca4dcece2f Mon Sep 17 00:00:00 2001
From: Albert Krewinkel <albert.krewinkel@fu-berlin.de>
Date: Fri, 6 Feb 2026 09:44:41 +0100
Subject: [PATCH] Lua: add new function `pandoc.types.Sources`.

This provides access to the `Sources` abstraction that pandoc uses for
input files.

Closes: #11441
---
 doc/lua-filters.md                            | 72 ++++++++++++++++++-
 .../src/Text/Pandoc/Lua/Marshal/Sources.hs    | 32 ++++++---
 .../src/Text/Pandoc/Lua/Module.hs             |  2 +-
 .../src/Text/Pandoc/Lua/Module/Types.hs       | 66 ++++++++++++-----
 .../test/lua/module/pandoc-types.lua          | 28 ++++++++
 tools/update-lua-module-docs.lua              |  2 +
 6 files changed, 175 insertions(+), 27 deletions(-)

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 62d29ec3b..ae864e89d 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -4197,13 +4197,22 @@ Returns:
 
 `documentation (object[, format])`
 
+Return the documentation for a function or module defined by
+pandoc. Throws an error if there is no documentation for the given
+object.
+
+The result format can be any textual format accepted by
+`pandoc.write`, and the documentation will be returned in that
+format. Additionally, the special format `blocks` is accepted, in
+which case the documentation is returned as [Blocks].
+
 Parameters:
 
 `object`
 :   Retrieve documentation for this object (any)
 
 `format`
-:   result format (string\|table)
+:   result format; defaults to `'ansi'` (string\|table)
 
 Returns:
 
@@ -7218,6 +7227,66 @@ Returns:
 
 *Since: 2.7.3*
 
+### Sources {#pandoc.types.Sources}
+
+`Sources (srcs)`
+
+Creates a new Sources element, i.e., a list of [Source] items.
+
+Pandoc's text readers expect the input text to be paired with
+information on where the text originated, e.g., a file name. This
+abstraction is provided via the `Sources` type.
+
+Pandoc accepts a range of objects wherever a *Sources* list is
+expected:
+
+- a list of [Source] items;
+- a simple string, which becomes an unnamed source;
+- a list of table objects, where each table contains the fields
+  `name` (the filepath) and `text` (the file contents)
+
+A Sources list can be converted to a string via the default
+`tostring` Lua function. This will concatenate all source items.
+
+Parameters:
+
+`srcs`
+:   sources (string\|{string,\...}\|table)
+
+Returns:
+
+- new Sources object ({[Source],\...})
+
+*Since: 3.9.1*
+
+## Types {#pandoc.types-types}
+
+### Source {#type-pandoc.types.Source}
+
+### Version {#type-pandoc.types.Version}
+
+#### Methods
+
+##### Version.must_be_at_least {#Version.must_be_at_least}
+
+`Version.must_be_at_least (self, reference[, msg])`
+
+Parameters:
+
+`self`
+:   version to check ([Version])
+
+`reference`
+:   minimum version ([Version])
+
+`msg`
+:   alternative message (string)
+
+Returns:
+
+Returns no result, and throws an error if this version is older
+than `reference`.
+
 <!-- END: AUTOGENERATED CONTENT -->
 
 <!-- Disabled due to limitations in the current documentation
@@ -7464,3 +7533,4 @@ Returns:
   [XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/latest/
   [Doc]: #type-doc
   [Template]: #type-template
+  [Source]: #type-pandoc.types.Source
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/Sources.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/Sources.hs
index 902c127f2..21b040d2c 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/Sources.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/Sources.hs
@@ -1,17 +1,17 @@
 {-# LANGUAGE LambdaCase           #-}
 {-# LANGUAGE OverloadedStrings    #-}
-{-# OPTIONS_GHC -fno-warn-orphans #-}
+{-# LANGUAGE TupleSections        #-}
 {- |
 Module      : Text.Pandoc.Lua.Marshaling.Sources
-Copyright   : © 2021-2024 Albert Krewinkel
-License     : GNU GPL, version 2 or above
-Maintainer  : Albert Krewinkel <albert+pandoc@tarleb.com>
+Copyright   : © 2021-2026 Albert Krewinkel <albert+pandoc@tarleb.com>
+License     : GPL-2.0-or-later
 
 Marshal 'Sources'.
 -}
 module Text.Pandoc.Lua.Marshal.Sources
   ( peekSources
   , pushSources
+  , typeSource
   ) where
 
 import Control.Monad ((<$!>))
@@ -37,17 +37,31 @@ pushSources (Sources srcs) = do
 -- | Retrieves sources from the stack.
 peekSources :: LuaError e => Peeker e Sources
 peekSources idx = liftLua (ltype idx) >>= \case
-  TypeString -> toSources <$!> peekText idx
-  TypeTable  -> Sources <$!> peekList (peekUD typeSource) idx
-  _          -> Sources . (:[]) <$!> peekUD typeSource idx
+  TypeTable  -> mconcat <$!> peekList peekSourcesSingleton idx
+  _          -> peekSourcesSingleton idx
+
+-- | Retrieves a Sources singleton, i.e., a list with exactly one item.
+peekSourcesSingleton :: LuaError e => Peeker e Sources
+peekSourcesSingleton = choice
+  [ fmap toSources . peekText
+  , fmap (Sources . (:[])) . peekUD typeSource
+  , fmap (toSources . (:[])) . peekPair peekString peekText
+  , fmap (toSources . (:[])) .
+    (\idx -> (,)
+      <$> peekFieldRaw peekString "name" idx
+      <*> peekFieldRaw peekText "text" idx)
+  ]
+
+-- | A @Sources@ item.
+type Source = (SourcePos, Text)
 
 -- | Source object type.
-typeSource :: LuaError e => DocumentedType e (SourcePos, Text)
+typeSource :: LuaError e => DocumentedType e Source
 typeSource = deftype "Source"
   [ operation Tostring $ lambda
     ### liftPure snd
     <#> udparam typeSource "srcs" "Source to print in native format"
-    =#> functionResult pushText "string" "Haskell representation"
+    =#> functionResult pushText "string" "source contents"
   ]
   [ readonly "name" "source name"
       (pushString, sourceName . fst)
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module.hs
index 9966c4a45..b8a49c5f6 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module.hs
@@ -2,7 +2,7 @@
 {-# LANGUAGE OverloadedStrings #-}
 {- |
    Module      : Text.Pandoc.Lua.Module
-   Copyright   : © 2017-2024 Albert Krewinkel
+   Copyright   : © 2017-2026 Albert Krewinkel
    License     : GPL-2.0-or-later
    Maintainer  : Albert Krewinkel <albert+pandoc@tarleb.com>
 
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Types.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Types.hs
index c044685da..ae0e5461c 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Types.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Types.hs
@@ -1,7 +1,7 @@
 {-# LANGUAGE OverloadedStrings #-}
 {- |
    Module      : Text.Pandoc.Lua.Module.Types
-   Copyright   : © 2019-2024 Albert Krewinkel
+   Copyright   : © 2019-2026 Albert Krewinkel
    License     : GNU GPL, version 2 or above
 
    Maintainer  : Albert Krewinkel <albert+pandoc@tarleb.com>
@@ -13,13 +13,15 @@ module Text.Pandoc.Lua.Module.Types
   ( documentedModule
   ) where
 
-import Data.Version (makeVersion)
-import HsLua ( Module (..), (###), (<#>), (=#>)
+import Data.Version (Version, makeVersion)
+import HsLua ( DocumentedFunction, Module (..)
+             , (###), (<#>), (=#>), (#?), associateType
              , defmodule, defun, functionResult, parameter, since
              , withDescription, withFunctions
              )
-import HsLua.Module.Version (peekVersionFuzzy, pushVersion)
+import HsLua.Module.Version (peekVersionFuzzy, pushVersion, typeVersion)
 import Text.Pandoc.Error (PandocError)
+import Text.Pandoc.Lua.Marshal.Sources (peekSources, pushSources, typeSource)
 import Text.Pandoc.Lua.PandocLua ()
 
 -- | Push the pandoc.types module on the Lua stack.
@@ -28,15 +30,47 @@ documentedModule = defmodule "pandoc.types"
   `withDescription`
       "Constructors for types that are not part of the pandoc AST."
   `withFunctions`
-      [ defun "Version"
-        ### return
-        <#> parameter peekVersionFuzzy "string|number|{integer,...}|Version"
-              "version_specifier"
-              (mconcat [ "A version string like `'2.7.3'`, "
-                       , "a Lua number like `2.0`, "
-                       , "a list of integers like `{2,7,3}`, "
-                       , "or a Version object."
-                       ])
-        =#> functionResult pushVersion "Version" "New Version object."
-        `since` makeVersion [2,7,3]
-      ]
+    [ mkVersion `since` v[2,7,3]
+    , mkSources `since` v[3,9,1]
+    ]
+  `associateType` typeSource
+  `associateType` typeVersion
+ where
+  v :: [Int] -> Version
+  v = makeVersion
+
+mkVersion :: DocumentedFunction PandocError
+mkVersion = defun "Version"
+  ### return
+  <#> parameter peekVersionFuzzy "string|number|{integer,...}|Version"
+        "version_specifier"
+        (mconcat [ "A version string like `'2.7.3'`, "
+                 , "a Lua number like `2.0`, "
+                 , "a list of integers like `{2,7,3}`, "
+                 , "or a Version object."
+                 ])
+  =#> functionResult pushVersion "Version" "New Version object."
+
+mkSources :: DocumentedFunction PandocError
+mkSources = defun "Sources"
+  ### pure
+  <#> parameter peekSources "string|{string,...}|table" "srcs"
+        "sources"
+  =#> functionResult pushSources "{Source,...}" "new Sources object"
+  #?
+    "Creates a new Sources element, i.e., a list of [[Source]] items.\n\
+    \\n\
+    \ Pandoc's text readers expect the input text to be paired\
+    \ with information on where the text originated, e.g., a\
+    \ file name. This abstraction is provided via the `Sources` type.\n\
+    \\n\
+    \Pandoc accepts a range of objects wherever a *Sources* list is\
+    \ expected:\n\
+    \\n\
+    \  - a list of [[Source]] items;\n\
+    \  - a simple string, which becomes an unnamed source;\n\
+    \  - a list of table objects, where each table contains the fields\n\
+    \    `name` (the filepath) and `text` (the file contents)\n\
+    \\n\
+    \A Sources list can be converted to a string via the default `tostring`\
+    \ Lua function. This will concatenate all source items."
diff --git a/pandoc-lua-engine/test/lua/module/pandoc-types.lua b/pandoc-lua-engine/test/lua/module/pandoc-types.lua
index d9c9f82ac..893d23479 100644
--- a/pandoc-lua-engine/test/lua/module/pandoc-types.lua
+++ b/pandoc-lua-engine/test/lua/module/pandoc-types.lua
@@ -1,5 +1,7 @@
 local tasty = require 'tasty'
+local system = require 'pandoc.system'
 local types = require 'pandoc.types'
+local Sources = types.Sources
 local Version = types.Version
 
 local assert = tasty.assert
@@ -7,6 +9,32 @@ local test = tasty.test_case
 local group = tasty.test_group
 
 return {
+  group 'Sources' {
+    group 'constructor' {
+      test('has type `table`', function ()
+        assert.are_same(type(Sources ""), 'table')
+      end),
+      test('accepts a single string', function ()
+        assert.are_same(type(Sources('a')), 'table')
+      end),
+      test('accepts a list of strings', function ()
+        local srcs = Sources{'first text\n', 'second text\n'}
+        assert.are_equal(srcs[1].name, '')
+        assert.are_equal(srcs[1].text, 'first text\n')
+      end),
+      test('accepts list of filepath/content tuples', function ()
+        local srcs = Sources{{'test.txt', 'semi-random content'}}
+        assert.are_equal(srcs[1].name, 'test.txt')
+        assert.are_equal(srcs[1].text, 'semi-random content\n')
+      end),
+      test('accepts lists of Source-like tables', function ()
+        local srcs = Sources{{name = 'test.txt', text = 'semi-random content'}}
+        assert.are_equal(srcs[1].name, 'test.txt')
+        assert.are_equal(srcs[1].text, 'semi-random content\n')
+      end),
+    },
+  },
+
   group 'Version' {
 
     group 'constructor' {
diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua
index e74fb22aa..d26542f5f 100644
--- a/tools/update-lua-module-docs.lua
+++ b/tools/update-lua-module-docs.lua
@@ -100,6 +100,8 @@ local known_types = {
   ReaderOptions = 'type-readeroptions',
   Row = 'type-row',
   SimpleTable = 'type-simpletable',
+  Source = 'type-pandoc.types.Source',
+  Sources = 'pandoc.types.Sources',
   Span = 'type-span',
   Str = 'type-str',
   Table = 'type-table',