{-# LANGUAGE FlexibleInstances    #-}
{-# LANGUAGE LambdaCase           #-}
{-# LANGUAGE OverloadedStrings    #-}
{-# LANGUAGE ScopedTypeVariables  #-}
{-# LANGUAGE TypeApplications     #-}
{-# OPTIONS_GHC -fno-warn-orphans #-}
{-|
Module      : HsLua.Module.DocLayout
Copyright   : © 2020-2022 Albert Krewinkel
License     : MIT
Maintainer  : Albert Krewinkel <albert+hslua@zeitkraut.de>

Provides a Lua module which wraps @'Text.DocLayout'@. The @Doc'
type is specialized to @'Text'@.

This module defines orphan instances for @Doc Text@.
-}
module HsLua.Module.DocLayout (
  -- * Module
    documentedModule
  , pushModule
  , preloadModule
  , description
  , fields
  , functions

  -- * Doc constructors and combinators
  , after_break
  , before_non_blank
  , blankline
  , blanklines
  , braces
  , brackets
  , cblock
  , chomp
  , concat
  , cr
  , double_quotes
  , empty
  , flush
  , hang
  , inside
  , lblock
  , literal
  , nest
  , nestle
  , nowrap
  , parens
  , prefixed
  , quotes
  , rblock
  , space
  , vfill

  -- * Rendering
  , render

  -- * Document Querying
  , is_empty
  , height
  , min_offset
  , offset
  , real_length
  , update_column

  -- * Marshaling
  , peekDoc
  , pushDoc
  )
where

import Prelude hiding (concat)
import Data.List (intersperse)
import Data.Text (Text)
import HsLua as Lua hiding (concat)
import Text.DocLayout (Doc, (<+>), ($$), ($+$))

import qualified Data.Text as T
import qualified Text.DocLayout as Doc

--
-- Module
--

-- | Textual description of the "doclayout" module.
description :: Text
description :: Text
description = Text
"Plain-text document layouting."

-- | Self-documenting module.
documentedModule :: LuaError e => Module e
documentedModule :: forall e. LuaError e => Module e
documentedModule = Module
  { moduleName :: Name
moduleName = Name
"doclayout"
  , moduleFields :: [Field e]
moduleFields = forall e. LuaError e => [Field e]
fields
  , moduleDescription :: Text
moduleDescription = Text
description
  , moduleFunctions :: [DocumentedFunction e]
moduleFunctions = forall e. LuaError e => [DocumentedFunction e]
functions
  , moduleOperations :: [(Operation, DocumentedFunction e)]
moduleOperations = []
  , moduleTypeInitializers :: [LuaE e Name]
moduleTypeInitializers = [forall e a itemtype.
LuaError e =>
DocumentedTypeWithList e a itemtype -> LuaE e Name
initType forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc]
  }

--
-- Fields
--

-- | Exposed fields.
fields :: forall e. LuaError e => [Field e]
fields :: forall e. LuaError e => [Field e]
fields =
  [ forall e. LuaError e => Field e
blankline
  , forall e. LuaError e => Field e
cr
  , forall e. LuaError e => Field e
empty
  , forall e. LuaError e => Field e
space
  ]

-- | Wrapped and documented 'Doc.blankline' value.
blankline :: forall e. LuaError e => Field e
blankline :: forall e. LuaError e => Field e
blankline = Field
  { fieldName :: Text
fieldName = Text
"blankline"
  , fieldDescription :: Text
fieldDescription = Text
"Inserts a blank line unless one exists already."
  , fieldType :: TypeSpec
fieldType = forall e fn a itemtype. UDTypeWithList e fn a itemtype -> TypeSpec
udTypeSpec @e forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc
  , fieldPushValue :: LuaE e ()
fieldPushValue = forall e. LuaError e => Pusher e (Doc Text)
pushDoc forall a. Doc a
Doc.blankline
  }

-- | Wrapped and documented 'Doc.cr' value.
cr :: forall e. LuaError e => Field e
cr :: forall e. LuaError e => Field e
cr = Field
  { fieldName :: Text
fieldName = Text
"cr"
  , fieldDescription :: Text
fieldDescription = Text
"A carriage return. Does nothing if we're at " forall a. Semigroup a => a -> a -> a
<>
                       Text
"the beginning of a line; " forall a. Semigroup a => a -> a -> a
<>
                       Text
"otherwise inserts a newline."
  , fieldType :: TypeSpec
fieldType = forall e fn a itemtype. UDTypeWithList e fn a itemtype -> TypeSpec
udTypeSpec @e forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc
  , fieldPushValue :: LuaE e ()
fieldPushValue = forall e. LuaError e => Pusher e (Doc Text)
pushDoc forall a. Doc a
Doc.cr
  }

-- | Wrapped and documented 'Doc.empty' value.
empty :: forall e. LuaError e => Field e
empty :: forall e. LuaError e => Field e
empty = Field
  { fieldName :: Text
fieldName = Text
"empty"
  , fieldDescription :: Text
fieldDescription = Text
"The empty document."
  , fieldType :: TypeSpec
fieldType = forall e fn a itemtype. UDTypeWithList e fn a itemtype -> TypeSpec
udTypeSpec @e forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc
  , fieldPushValue :: LuaE e ()
fieldPushValue = forall e. LuaError e => Pusher e (Doc Text)
pushDoc forall a. Doc a
Doc.empty
  }

-- | Wrapped and documented 'Doc.space' value.
space :: forall e. LuaError e => Field e
space :: forall e. LuaError e => Field e
space = Field
  { fieldName :: Text
fieldName = Text
"space"
  , fieldDescription :: Text
fieldDescription = Text
"A breaking (reflowable) space."
  , fieldType :: TypeSpec
fieldType = forall e fn a itemtype. UDTypeWithList e fn a itemtype -> TypeSpec
udTypeSpec @e forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc
  , fieldPushValue :: LuaE e ()
fieldPushValue = forall e. LuaError e => Pusher e (Doc Text)
pushDoc forall a. Doc a
Doc.space
  }

--
-- Functions
--

-- | Exposed module functions.
functions :: LuaError e => [DocumentedFunction e]
functions :: forall e. LuaError e => [DocumentedFunction e]
functions =
  [ -- Constructors
    forall e. LuaError e => DocumentedFunction e
after_break
  , forall e. LuaError e => DocumentedFunction e
before_non_blank
  , forall e. LuaError e => DocumentedFunction e
blanklines
  , forall e. LuaError e => DocumentedFunction e
braces
  , forall e. LuaError e => DocumentedFunction e
brackets
  , forall e. LuaError e => DocumentedFunction e
cblock
  , forall e. LuaError e => DocumentedFunction e
chomp
  , forall e. LuaError e => DocumentedFunction e
concat
  , forall e. LuaError e => DocumentedFunction e
double_quotes
  , forall e. LuaError e => DocumentedFunction e
flush
  , forall e. LuaError e => DocumentedFunction e
hang
  , forall e. LuaError e => DocumentedFunction e
inside
  , forall e. LuaError e => DocumentedFunction e
lblock
  , forall e. LuaError e => DocumentedFunction e
literal
  , forall e. LuaError e => DocumentedFunction e
nest
  , forall e. LuaError e => DocumentedFunction e
nestle
  , forall e. LuaError e => DocumentedFunction e
nowrap
  , forall e. LuaError e => DocumentedFunction e
parens
  , forall e. LuaError e => DocumentedFunction e
prefixed
  , forall e. LuaError e => DocumentedFunction e
quotes
  , forall e. LuaError e => DocumentedFunction e
rblock
  , forall e. LuaError e => DocumentedFunction e
vfill
    -- rendering
  , forall e. LuaError e => DocumentedFunction e
render
    -- querying
  , forall e. LuaError e => DocumentedFunction e
is_empty
  , forall e. LuaError e => DocumentedFunction e
height
  , forall e. LuaError e => DocumentedFunction e
min_offset
  , forall e. LuaError e => DocumentedFunction e
offset
  , forall e. DocumentedFunction e
real_length
  , forall e. LuaError e => DocumentedFunction e
update_column
  ]

typeDoc :: LuaError e => DocumentedType e (Doc Text)
typeDoc :: forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc = forall e a.
LuaError e =>
Name
-> [(Operation, DocumentedFunction e)]
-> [Member e (DocumentedFunction e) a]
-> DocumentedType e a
deftype Name
"Doc"
      [ forall e.
Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
Add    forall a b. (a -> b) -> a -> b
$ forall {e}.
LuaError e =>
(Doc Text -> Doc Text -> Doc Text) -> Text -> DocumentedFunction e
binaryOp forall a. Doc a -> Doc a -> Doc a
(<+>)
        Text
"Concatenated docs, with breakable space between them."
      , forall e.
Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
Concat forall a b. (a -> b) -> a -> b
$ forall {e}.
LuaError e =>
(Doc Text -> Doc Text -> Doc Text) -> Text -> DocumentedFunction e
binaryOp forall a. Semigroup a => a -> a -> a
(<>) Text
"Concatenation of the input docs"
      , forall e.
Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
Div    forall a b. (a -> b) -> a -> b
$ forall {e}.
LuaError e =>
(Doc Text -> Doc Text -> Doc Text) -> Text -> DocumentedFunction e
binaryOp forall a. Doc a -> Doc a -> Doc a
($$) Text
"Puts a above b"
      , forall e.
Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
Eq     forall a b. (a -> b) -> a -> b
$ forall a e. a -> HsFnPrecursor e a
lambda
        ### liftPure2 (==)
        forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"a"
        forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"b"
        forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. Text -> FunctionResults e Bool
boolResult Text
"whether the two Docs are equal"
      , forall e.
Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
Idiv   forall a b. (a -> b) -> a -> b
$ forall {e}.
LuaError e =>
(Doc Text -> Doc Text -> Doc Text) -> Text -> DocumentedFunction e
binaryOp forall a. Doc a -> Doc a -> Doc a
($+$) Text
"Puts a above b"
      , forall e.
Operation
-> DocumentedFunction e -> (Operation, DocumentedFunction e)
operation Operation
Tostring forall a b. (a -> b) -> a -> b
$ forall a e. a -> HsFnPrecursor e a
lambda
        ### liftPure (Doc.render Nothing)
        forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
        forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. Text -> FunctionResults e Text
textResult Text
"Rendered Doc without reflowing."
      ]
      [ forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
before_non_blank
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
braces
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
brackets
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
cblock
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
chomp
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
double_quotes
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
is_empty
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
flush
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
hang
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
height
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
inside
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
lblock
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
min_offset
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
nest
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
nestle
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
nowrap
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
offset
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
parens
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
prefixed
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
quotes
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
rblock
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
render
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
update_column
      , forall e a.
DocumentedFunction e -> Member e (DocumentedFunction e) a
method forall e. LuaError e => DocumentedFunction e
vfill
      ]
  where
    binaryOp :: (Doc Text -> Doc Text -> Doc Text) -> Text -> DocumentedFunction e
binaryOp Doc Text -> Doc Text -> Doc Text
op Text
descr = forall a e. a -> HsFnPrecursor e a
lambda
      ### liftPure2 op
      forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"a"
      forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"b"
      forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
descr

-- | Render a @'Doc'@. The text is reflowed on breakable spaces
-- to match the given line length. Text is not reflowed if the
-- line length parameter is omitted or nil.
render :: LuaError e => DocumentedFunction e
render :: forall e. LuaError e => DocumentedFunction e
render = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"render"
  ### liftPure2 (flip Doc.render)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e a. Parameter e a -> Parameter e (Maybe a)
opt (forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"colwidth" Text
"planned maximum line length")
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e a. Pusher e a -> TypeSpec -> Text -> FunctionResults e a
functionResult forall e. Pusher e Text
pushText TypeSpec
"Doc" Text
"rendered doc"
  #? ("Render a @'Doc'@. The text is reflowed on breakable spaces" <>
      "to match the given line length. Text is not reflowed if the" <>
      "line length parameter is omitted or nil.")

--
-- Querying
--

-- | @True@ iff the document is empty.
is_empty :: LuaError e => DocumentedFunction e
is_empty :: forall e. LuaError e => DocumentedFunction e
is_empty = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"is_empty"
  ### liftPure Doc.isEmpty
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. Text -> FunctionResults e Bool
boolResult Text
"`true` iff `doc` is the empty document, `false` otherwise."
  #? "Checks whether a doc is empty."

-- | Returns the width of a @'Doc'@.
offset :: LuaError e => DocumentedFunction e
offset :: forall e. LuaError e => DocumentedFunction e
offset = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"offset"
  ### liftPure Doc.offset
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall a e. (Integral a, Show a) => Text -> FunctionResults e a
integralResult Text
"doc width"
  #? "Returns the width of a `Doc` as number of characters."

-- | Returns the minimal width of a @'Doc'@ when reflowed at
-- breakable spaces.
min_offset :: LuaError e => DocumentedFunction e
min_offset :: forall e. LuaError e => DocumentedFunction e
min_offset = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"min_offset"
  ### liftPure Doc.minOffset
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall a e. (Integral a, Show a) => Text -> FunctionResults e a
integralResult Text
"minimal possible width"
  #? ("Returns the minimal width of a `Doc` when reflowed at " <>
      "breakable spaces.")

-- | Returns the column that would be occupied by the last laid
-- out character.
update_column :: LuaError e => DocumentedFunction e
update_column :: forall e. LuaError e => DocumentedFunction e
update_column = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"update_column"
  ### liftPure2 Doc.updateColumn
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"i" Text
"start column"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall a e. (Integral a, Show a) => Text -> FunctionResults e a
integralResult Text
"column number"
  #? ("Returns the column that would be occupied by the last " <>
      "laid out character.")

-- | Returns the height of a block or other Doc.
height :: LuaError e => DocumentedFunction e
height :: forall e. LuaError e => DocumentedFunction e
height = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"height"
  ### liftPure Doc.height
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall a e. (Integral a, Show a) => Text -> FunctionResults e a
integralResult Text
"doc height"
  #? "Returns the height of a block or other Doc."


-- | Returns the real length of a string in a monospace font: 0
-- for a combining character, 1, for a regular character, 2 for
-- an East Asian wide character.
real_length :: DocumentedFunction e
real_length :: forall e. DocumentedFunction e
real_length = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"real_length"
  ### liftPure Doc.realLength
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. Text -> Text -> Parameter e Text
textParam Text
"str" Text
"UTF-8 string to measure"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall a e. (Integral a, Show a) => Text -> FunctionResults e a
integralResult Text
"text length"
  #? ("Returns the real length of a string in a monospace font: " <>
      "0 for a combining chaeracter, 1 for a regular character, " <>
      "2 for an East Asian wide character.")

--
-- Constructors
--

-- | Creates a @'Doc'@ which is conditionally included only if it
-- comes at the beginning of a line.
after_break :: LuaError e => DocumentedFunction e
after_break :: forall e. LuaError e => DocumentedFunction e
after_break = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"after_break"
  ### liftPure Doc.afterBreak
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. Text -> Text -> Parameter e Text
textParam Text
"text" Text
"content to include when placed after a break"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"new doc"
  #? ("Creates a `Doc` which is conditionally included only if it " <>
      "comes at the beginning of a line.\n\n" <>
      "An example where this is useful is for escaping line-initial " <>
      "`.` in roff man.")

-- | Conditionally includes the given @'Doc'@ unless it is
-- followed by a blank space.
before_non_blank :: LuaError e => DocumentedFunction e
before_non_blank :: forall e. LuaError e => DocumentedFunction e
before_non_blank = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"before_non_blank"
  ### liftPure Doc.beforeNonBlank
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"conditional doc"
  #? ("Conditionally includes the given `doc` unless it is " <>
      "followed by a blank space.")

-- | Insert blank lines unless they exist already.
blanklines :: LuaError e => DocumentedFunction e
blanklines :: forall e. LuaError e => DocumentedFunction e
blanklines = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"blanklines"
  ### liftPure Doc.blanklines
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"n" Text
"number of blank lines"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"conditional blank lines"
  #? "Inserts blank lines unless they exist already."

-- | Puts a @'Doc'@ in curly braces.
braces :: LuaError e => DocumentedFunction e
braces :: forall e. LuaError e => DocumentedFunction e
braces = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"braces"
  ### liftPure Doc.braces
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"doc enclosed by {}."
  #? "Puts the `doc` in curly braces."

-- | Puts a @'Doc'@ in square brackets.
brackets :: LuaError e => DocumentedFunction e -- Doc Text -> Lua (Doc Text)
brackets :: forall e. LuaError e => DocumentedFunction e
brackets = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"brackets"
  ### liftPure Doc.brackets
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"doc enclosed by []."
  #? "Puts the `doc` in square brackets"

-- | Like @'lblock'@ but aligned centered.
cblock :: LuaError e => DocumentedFunction e
cblock :: forall e. LuaError e => DocumentedFunction e
cblock = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"cblock"
  ### liftPure2 (flip Doc.cblock)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"width" Text
"block width in chars"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult (Text
"doc, aligned centered in a block with max" forall a. Semigroup a => a -> a -> a
<>
                 Text
"`width` chars per line.")
  #? ("Creates a block with the given width and content, " <>
      "aligned centered.")

-- | Chomps trailing blank space off of a @'Doc'@.
chomp :: LuaError e => DocumentedFunction e
chomp :: forall e. LuaError e => DocumentedFunction e
chomp = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"chomp"
  ### liftPure Doc.chomp
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"`doc` without trailing blanks"
  #? "Chomps trailing blank space off of the `doc`."

-- | Concatenates a list of @'Doc'@s.
concat :: LuaError e => DocumentedFunction e
concat :: forall e. LuaError e => DocumentedFunction e
concat = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"concat"
  ### liftPure2 (\docs optSep -> mconcat $
                  maybe docs (`intersperse` docs) optSep)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e a. Peeker e a -> TypeSpec -> Text -> Text -> Parameter e a
parameter (forall a e. LuaError e => Peeker e a -> Peeker e [a]
peekList forall e. LuaError e => Peeker e (Doc Text)
peekDoc) TypeSpec
"`{Doc,...}`" Text
"docs" Text
"list of Docs"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e a. Parameter e a -> Parameter e (Maybe a)
opt (forall e a. Peeker e a -> TypeSpec -> Text -> Text -> Parameter e a
parameter forall e. LuaError e => Peeker e (Doc Text)
peekDoc TypeSpec
"Doc" Text
"sep" Text
"separator (default: none)")
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"concatenated doc"
  #? "Concatenates a list of `Doc`s."

-- | Wraps a @'Doc'@ in double quotes
double_quotes :: LuaError e => DocumentedFunction e
double_quotes :: forall e. LuaError e => DocumentedFunction e
double_quotes = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"double_quotes"
  ### liftPure Doc.doubleQuotes
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"`doc` enclosed by `\"` chars"
  #? "Wraps a `Doc` in double quotes."

-- | Makes a @'Doc'@ flush against the left margin.
flush :: LuaError e => DocumentedFunction e
flush :: forall e. LuaError e => DocumentedFunction e
flush = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"flush"
  ### liftPure Doc.flush
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"flushed `doc`"
  #? "Makes a `Doc` flush against the left margin."

-- | Creates a hanging indent.
hang :: LuaError e => DocumentedFunction e
hang :: forall e. LuaError e => DocumentedFunction e
hang = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"hang"
  ### liftPure3 (\doc ind start -> Doc.hang ind start doc)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"ind" Text
"indentation width"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"start"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult (Text
"`doc` prefixed by `start` on the first line, " forall a. Semigroup a => a -> a -> a
<>
                 Text
"subsequent lines indented by `ind` spaces.")
  #? "Creates a hanging indent."

-- | Encloses a @'Doc'@ inside a start and end @'Doc'@.
inside :: LuaError e => DocumentedFunction e
inside :: forall e. LuaError e => DocumentedFunction e
inside = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"inside"
  ### liftPure3 (\contents start end -> Doc.inside start end contents)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"contents"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"start"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"end"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"enclosed contents"
  #? "Encloses a `Doc` inside a start and end `Doc`."

-- | Creates a block with the given width and content, aligned to
-- the left.
lblock :: LuaError e => DocumentedFunction e
lblock :: forall e. LuaError e => DocumentedFunction e
lblock = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"lblock"
  ### liftPure2 (flip Doc.lblock)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"width" Text
"block width in chars"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"doc put into block with max `width` chars per line."
  #? ("Creates a block with the given width and content, " <>
      "aligned to the left.")

-- | Creates a @'Doc'@ from a string.
literal :: LuaError e => DocumentedFunction e
literal :: forall e. LuaError e => DocumentedFunction e
literal = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"literal"
  ### liftPure Doc.literal
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. Text -> Text -> Parameter e Text
textParam Text
"text" Text
"literal value"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"doc contatining just the literal string"
  #? "Creates a `Doc` from a string."

-- | Indents a @'Doc'@ by the specified number of spaces.
nest :: LuaError e => DocumentedFunction e
nest :: forall e. LuaError e => DocumentedFunction e
nest = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"nest"
  ### liftPure2 (flip Doc.nest)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"ind" Text
"indentation size"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"`doc` indented by `ind` spaces"
  #? "Indents a `Doc` by the specified number of spaces."

-- | Removes leading blank lines from a @'Doc'@.
nestle :: LuaError e => DocumentedFunction e
nestle :: forall e. LuaError e => DocumentedFunction e
nestle = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"nestle"
  ### liftPure Doc.nestle
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"`doc` with leading blanks removed"
  #? "Removes leading blank lines from a `Doc`."

-- | Makes a @'Doc'@ non-reflowable.
nowrap :: LuaError e => DocumentedFunction e
nowrap :: forall e. LuaError e => DocumentedFunction e
nowrap = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"nowrap"
  ### liftPure Doc.nowrap
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"same as input, but non-reflowable"
  #? "Makes a `Doc` non-reflowable."

-- | Puts a @'Doc'@ in parentheses.
parens :: LuaError e => DocumentedFunction e
parens :: forall e. LuaError e => DocumentedFunction e
parens = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"parens"
  ### liftPure Doc.parens
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"doc enclosed by ()."
  #? "Puts the `doc` in parentheses."


-- | Uses the specified string as a prefix for every line of the
-- inside document (except the first, if not at the beginning of
-- the line).
prefixed :: LuaError e => DocumentedFunction e
prefixed :: forall e. LuaError e => DocumentedFunction e
prefixed = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"prefixed"
  ### liftPure2 (flip Doc.prefixed)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. Text -> Text -> Parameter e String
stringParam Text
"prefix" Text
"prefix for each line"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"prefixed `doc`"
  #? ("Uses the specified string as a prefix for every line of " <>
      "the inside document (except the first, if not at the " <>
      "beginning of the line).")

-- | Wraps a @'Doc'@ in single quotes.
quotes :: LuaError e => DocumentedFunction e
quotes :: forall e. LuaError e => DocumentedFunction e
quotes = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"quotes"
  ### liftPure Doc.quotes
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"doc enclosed in `'`."
  #? "Wraps a `Doc` in single quotes."

-- | Like @'rblock'@ but aligned to the right.
rblock :: LuaError e => DocumentedFunction e
rblock :: forall e. LuaError e => DocumentedFunction e
rblock = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"rblock"
  ### liftPure2 (flip Doc.rblock)
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
"doc"
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall a e. (Read a, Integral a) => Text -> Text -> Parameter e a
integralParam Text
"width" Text
"block width in chars"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult (Text
"doc, right aligned in a block with max" forall a. Semigroup a => a -> a -> a
<>
                 Text
"`width` chars per line.")
  #? ("Creates a block with the given width and content, " <>
      "aligned to the right.")

-- | An expandable border that, when placed next to a box,
-- expands to the height of the box.  Strings cycle through the
-- list provided.
vfill :: LuaError e => DocumentedFunction e
vfill :: forall e. LuaError e => DocumentedFunction e
vfill = forall a e. Name -> a -> HsFnPrecursor e a
defun Name
"vfill"
  ### liftPure Doc.vfill
  forall e a b.
HsFnPrecursor e (a -> b) -> Parameter e a -> HsFnPrecursor e b
<#> forall e. Text -> Text -> Parameter e Text
textParam Text
"border" Text
"vertically expanded characters"
  forall e a.
HsFnPrecursor e (LuaE e a)
-> FunctionResults e a -> DocumentedFunction e
=#> forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult Text
"automatically expanding border Doc"
  #? ("An expandable border that, when placed next to a box, " <>
      "expands to the height of the box.  Strings cycle through the " <>
      "list provided.")

--
-- Marshaling
--

-- | Retrieve a @Doc Text@ value from the Lua stack. Strings are
-- converted to plain @'Doc'@ values.
peekDoc :: LuaError e => Peeker e (Doc Text)
peekDoc :: forall e. LuaError e => Peeker e (Doc Text)
peekDoc StackIndex
idx = forall e a. LuaE e a -> Peek e a
liftLua (forall e. StackIndex -> LuaE e Type
Lua.ltype StackIndex
idx) forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
  Type
Lua.TypeString   -> let stringToDoc :: Text -> Doc Text
stringToDoc Text
s = if Text -> Bool
T.null Text
s
                                          then forall a. Doc a
Doc.empty
                                          else forall a. HasChars a => a -> Doc a
Doc.literal Text
s
                      in Text -> Doc Text
stringToDoc forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall e. Peeker e Text
Lua.peekText StackIndex
idx
  Type
Lua.TypeNumber   -> forall a. HasChars a => a -> Doc a
Doc.literal forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall e. Peeker e Text
Lua.peekText StackIndex
idx
  Type
_                -> forall e a itemtype.
LuaError e =>
DocumentedTypeWithList e a itemtype -> Peeker e a
peekUD forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc StackIndex
idx

-- | Push a @Doc Text@ value to the Lua stack.
pushDoc :: LuaError e => Pusher e (Doc Text)
pushDoc :: forall e. LuaError e => Pusher e (Doc Text)
pushDoc = forall e a itemtype.
LuaError e =>
DocumentedTypeWithList e a itemtype -> a -> LuaE e ()
pushUD forall e. LuaError e => DocumentedType e (Doc Text)
typeDoc

instance Peekable (Doc Text) where
  safepeek :: forall e. LuaError e => Peeker e (Doc Text)
safepeek = forall e. LuaError e => Peeker e (Doc Text)
peekDoc

instance Pushable (Doc Text) where
  push :: forall e. LuaError e => Pusher e (Doc Text)
push = forall e. LuaError e => Pusher e (Doc Text)
pushDoc

--
-- Parameters
--

-- | @Doc@ typed function parameter.
docParam :: LuaError e => Text -> Parameter e (Doc Text)
docParam :: forall e. LuaError e => Text -> Parameter e (Doc Text)
docParam Text
name = forall e a. Peeker e a -> TypeSpec -> Text -> Text -> Parameter e a
parameter forall e. LuaError e => Peeker e (Doc Text)
peekDoc TypeSpec
"Doc" Text
name Text
"document"

--
-- Results
--

-- | Function result of type @'Doc'@.
docResult :: LuaError e
          => Text -- ^ Description
          -> FunctionResults e (Doc Text)
docResult :: forall e. LuaError e => Text -> FunctionResults e (Doc Text)
docResult = forall e a. Pusher e a -> TypeSpec -> Text -> FunctionResults e a
functionResult forall e. LuaError e => Pusher e (Doc Text)
pushDoc TypeSpec
"Doc"