From 6c25d02e31b277f1af10c76c6faca3603f269692 Mon Sep 17 00:00:00 2001
From: Albert Krewinkel <albert@zeitkraut.de>
Date: Thu, 29 Dec 2022 12:23:24 +0100
Subject: [PATCH] Add a `nontext` function for texts with custom widths

---
 README.md                     | 16 ++++++++++++++++
 src/HsLua/Module/DocLayout.hs | 21 ++++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4d32485..3234238 100644
--- a/README.md
+++ b/README.md
@@ -239,6 +239,22 @@ Parameters:
 
 Removes leading blank lines from a `Doc`.
 
+#### nontext
+
+`nontext (str[, width])`
+
+Parameters:
+
+`str`
+:   non-textual string
+
+`width`
+:   effective width; defaults to 0
+
+Creates a `Doc` value that contains the raw string and behaves as
+if it had the specified width. A typical use-case are in-band
+formatting commands.
+
 #### nowrap
 
 `nowrap (doc)`
diff --git a/src/HsLua/Module/DocLayout.hs b/src/HsLua/Module/DocLayout.hs
index ff0c47f..4ae7bed 100644
--- a/src/HsLua/Module/DocLayout.hs
+++ b/src/HsLua/Module/DocLayout.hs
@@ -44,6 +44,7 @@ module HsLua.Module.DocLayout (
   , literal
   , nest
   , nestle
+  , nontext
   , nowrap
   , parens
   , prefixed
@@ -171,6 +172,7 @@ functions =
   , literal
   , nest
   , nestle
+  , nontext
   , nowrap
   , parens
   , prefixed
@@ -444,7 +446,7 @@ literal :: LuaError e => DocumentedFunction e
 literal = defun "literal"
   ### liftPure Doc.literal
   <#> textParam "text" "literal value"
-  =#> docResult "doc contatining just the literal string"
+  =#> docResult "doc containing just the literal string"
   #? "Creates a `Doc` from a string."
 
 -- | Indents a @'Doc'@ by the specified number of spaces.
@@ -464,6 +466,23 @@ nestle = defun "nestle"
   =#> docResult "`doc` with leading blanks removed"
   #? "Removes leading blank lines from a `Doc`."
 
+-- | Create a @Doc@ value that contains in-band formatting commands or
+-- similar information. The width of such commands can be specified
+-- explicitly.
+nontext :: LuaError e => DocumentedFunction e
+nontext = defun "nontext"
+  ### (liftPure2 $ \text -> \case
+          Nothing    -> Doc.Text 0 text
+          Just width -> Doc.Text width text)
+  <#> textParam "str" "non-textual string"
+  <#> opt (integralParam "width" "effective width; defaults to 0")
+  =#> docResult "The literal string, treated as having the given width."
+  #? T.unlines
+     [ "Creates a `Doc` value that contains the raw string and behaves as"
+     , "if it had the specified width. A typical use-case are in-band"
+     , "formatting commands."
+     ]
+
 -- | Makes a @'Doc'@ non-reflowable.
 nowrap :: LuaError e => DocumentedFunction e
 nowrap = defun "nowrap"