Add DocBox printer for 2D layout. (#8)

Author: natefaubion

README.md

@@ -162,7 +162,14 @@ Hello,
 Dodo inserts the break and indent. "Hello, World!" on a single line would
 exceed the maximum page width, so it uses the flex default (`break`) instead.
 
+### Two-Dimensional Layouts
+
+Dodo also supports two-dimensional layouts through the `Dodo.Box` interface.
+Boxes can be joined and aligned both vertically and horizontally to create
+complex layouts such as tables or grids.
+
 ## Examples
 
 * Colorful, flexible JSON printer ([code](test/snapshots/DodoExampleJson.purs), [output](test/snapshots/DodoExampleJson.output))
 * Text paragraphs ([code](test/snapshots/DodoTextParagraph.purs), [output](test/snapshots/DodoTextParagraph.output))
+* 2D layout ([code](test/snapshots/DodoBox.purs), [output](test/snapshots/DodoBox.output))

spago.dhall

@@ -18,16 +18,19 @@ You can edit this file as you like.
   , "lists"
   , "maybe"
   , "minibench"
+  , "newtype"
   , "node-buffer"
   , "node-child-process"
   , "node-fs-aff"
   , "node-path"
   , "node-process"
   , "node-streams"
   , "parallel"
+  , "partial"
   , "posix-types"
   , "prelude"
   , "psci-support"
+  , "safe-coerce"
   , "strings"
   , "tuples"
   ]

src/Dodo.purs

@@ -29,6 +29,7 @@ module Dodo
   , foldWithSeparator
   , foldWith
   , locally
+  , withLocalOptions
   , print
   , Printer(..)
   , plainText
@@ -49,6 +50,7 @@ import Data.String as String
 import Data.String.Regex as Regex
 import Data.String.Regex.Flags (global)
 import Data.String.Regex.Unsafe (unsafeRegex)
+import Data.Tuple (Tuple(..))
 import Dodo.Internal (Doc(..), Position, LocalOptions, bothNotEmpty, isEmpty, notEmpty)
 import Dodo.Internal (Doc, Position, bothNotEmpty, isEmpty, notEmpty) as Exports
 import Dodo.Internal.Buffer (Buffer)
@@ -197,7 +199,13 @@ foldWith f = foldr (bothNotEmpty f) mempty
 -- | *EXPERIMENTAL:* modifies printing state and options locally for a document.
 -- | This may change or be removed at any time.
 locally :: forall a. (LocalOptions -> LocalOptions) -> Doc a -> Doc a
-locally = Local
+locally k doc = Local \options -> Tuple (k options) doc
+
+-- | *EXPERIMENTAL:* modifies printing state and options locally for a document.
+-- | This may change or be removed at any time. Differs from `locally` in that the
+-- | document can be responsive to options.
+withLocalOptions :: forall a. (LocalOptions -> Tuple LocalOptions (Doc a)) -> Doc a
+withLocalOptions = Local
 
 -- | Custom printers can be used to render richer documents than just plain
 -- | text.
@@ -453,7 +461,7 @@ print (Printer printer) opts = flip go initState <<< pure <<< Doc
             { annotations = ann : state.annotations
             , buffer = Buffer.modify (printer.enterAnnotation ann state.annotations) state.buffer
             }
-        Local k doc1 -> do
+        Local k -> do
           let
             prevOptions =
               { indent: state.position.indent
@@ -463,7 +471,7 @@ print (Printer printer) opts = flip go initState <<< pure <<< Doc
               , pageWidth: state.options.pageWidth
               , ribbonRatio: state.options.ribbonRatio
               }
-            localOptions = k prevOptions
+            Tuple localOptions doc1 = k prevOptions
           go (Doc doc1 : LeaveLocal prevOptions: stk) $ storeOptions state.position.indent localOptions state
         Empty ->
           go stk state