Lua: add function pandoc.utils.text (#7710)

The function converts a string to `Inlines`, treating interword spaces
as `Space`s or `SoftBreak`s. If you want a `Str` with literal spaces,
use `pandoc.Str`.

Closes: #7709

doc/lua-filters.md

@@ -3082,6 +3082,24 @@ Usage:
     -- outputs "Moin"
     print(pandoc.utils.stringify(inline))
 
+### text {#pandoc.utils.text}
+
+`text (words)`
+
+Converts a string to `Inlines`, treating interword spaces as
+`Space`s or `SoftBreak`s. If you want a single `Str` with literal
+spaces, use `pandoc.Str`.
+
+Parameters:
+
+`words`
+:  markup-less text (string)
+
+Returns:
+
+-   List of inline elements split into words (Inlines)
+
+
 ### to\_roman\_numeral {#pandoc.utils.to_roman_numeral}
 
 `to_roman_numeral (integer)`

src/Text/Pandoc/Lua/Marshaling/AST.hs

@@ -44,6 +44,7 @@ module Text.Pandoc.Lua.Marshaling.AST
   , pushBlock
   , pushCitation
   , pushInline
+  , pushInlines
   , pushListAttributes
   , pushMeta
   , pushMetaValue

src/Text/Pandoc/Lua/Module/Utils.hs

@@ -29,8 +29,8 @@ import Text.Pandoc.Definition
 import Text.Pandoc.Error (PandocError)
 import Text.Pandoc.Lua.Marshaling ()
 import Text.Pandoc.Lua.Marshaling.AST
-  ( peekBlock, peekInline, peekPandoc, pushBlock, pushInline, pushPandoc
-  , peekAttr, peekMeta, peekMetaValue)
+  ( peekBlock, peekInline, peekPandoc, pushBlock, pushInline, pushInlines
+  ,  pushPandoc, peekAttr, peekMeta, peekMetaValue)
 import Text.Pandoc.Lua.Marshaling.ListAttributes (peekListAttributes)
 import Text.Pandoc.Lua.Marshaling.List (pushPandocList)
 import Text.Pandoc.Lua.Marshaling.SimpleTable
@@ -122,6 +122,14 @@ documentedModule = Module
       <#> parameter peekAstElement "AST element" "elem" "some pandoc AST element"
       =#> functionResult pushText "string" "stringified element"
 
+    , defun "text"
+      ### liftPure (B.toList . B.text)
+      <#> parameter peekText "string" "words" "markup-less inlines text"
+      =#> functionResult pushInlines "Inlines" "list of inline elements"
+      #? ("Converts a string to `Inlines`, treating interword spaces as " <>
+          "`Space`s or `SoftBreak`s.  If you want a `Str` with literal " <>
+          "spaces, use `pandoc.Str`.")
+
     , defun "from_simple_table"
       ### from_simple_table
       <#> parameter peekSimpleTable "SimpleTable" "simple_tbl" ""

test/lua/module/pandoc-utils.lua

@@ -82,6 +82,34 @@ return {
     end)
   },
 
+  group 'text' {
+    test('string is converted to inlines', function ()
+      local expected = {
+        pandoc.Str 'Madness', pandoc.Space(), pandoc.Str '-', pandoc.Space(),
+        pandoc.Str 'Our', pandoc.Space(), pandoc.Str 'House'
+      }
+      assert.are_same(pandoc.utils.text('Madness - Our House'), expected)
+    end),
+    test('tabs are treated as space', function ()
+      local expected = {
+        pandoc.Str 'Linkin', pandoc.Space(), pandoc.Str 'Park', pandoc.Space(),
+        pandoc.Str '-', pandoc.Space(), pandoc.Str 'Papercut'
+      }
+      assert.are_same(pandoc.utils.text('Linkin Park\t-\tPapercut'), expected)
+    end),
+    test('newlines are treated as softbreaks', function ()
+      local expected = {
+        pandoc.Str 'Porcupine', pandoc.Space(), pandoc.Str 'Tree',
+        pandoc.SoftBreak(), pandoc.Str '-', pandoc.SoftBreak(),
+        pandoc.Str 'Blackest',  pandoc.Space(), pandoc.Str 'Eyes'
+      }
+      assert.are_same(
+        pandoc.utils.text('Porcupine Tree\n-\nBlackest Eyes'),
+        expected
+      )
+    end),
+  },
+
   group 'to_roman_numeral' {
     test('convertes number', function ()
       assert.are_equal('MDCCCLXXXVIII', utils.to_roman_numeral(1888))