-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Pretty printing with indentation, mixfix operators, and automatic line breaks.
--   
--   Pretty printing library supporting indentation, parenthesis-elision
--   according to fixity and associativity, and automatic line breaks after
--   text width exceedance.
@package printcess
@version 0.1.0.3

module Printcess.PrettyPrinting

-- | Render a <a>Pretty</a> printable <tt>a</tt> to <a>String</a> using a
--   <a>Config</a>, that specifies how the <tt>a</tt> should be rendered.
--   For example
--   
--   <pre>
--   pretty defConfig (1 :: Int)  -- evaluates to "1"
--   </pre>
pretty :: Pretty a => State Config () -> a -> String

-- | Render a <a>Pretty</a> printable <tt>a</tt> to <tt>stdout</tt> using a
--   <a>Config</a>, that specifies how the <tt>a</tt> should be rendered.
--   
--   Convenience function, defined as:
--   
--   <pre>
--   prettyPrint c = liftIO . putStrLn . pretty c
--   </pre>
prettyPrint :: (MonadIO m, Pretty a) => State Config () -> a -> m ()

-- | A <a>Config</a> allows to specify various pretty printing options,
--   e.g. the maximum line width.
--   
--   As the rendering functions, like <tt>pretty</tt>, take updates to an
--   internal default <a>Config</a>, only the lenses of the <a>Config</a>
--   fields are exported.
--   
--   A custom <a>Config</a> can be specified as in the following example:
--   
--   <pre>
--   foo :: String
--   foo = pretty config "foo bar baz"
--     where config :: State Config ()
--           config = do cMaxLineWidth      .= Just 6
--                       cInitIndent        .= 2
--                       cIndentAfterBreaks .= 0
--   </pre>
data Config

-- | When a line gets longer, it is broken after the latest space, that
--   still allows the line to remain below this maximum.
--   
--   If there is no such space, an over-long line with a single indented
--   word is printed.
--   
--   This guarantees both progress and not to break identifiers into parts.
--   
--   Default: <tt>Just 80</tt>
cMaxLineWidth :: Lens' Config (Maybe Int)

-- | The character used for indentation. Usually <tt>' '</tt> for spaces or
--   <tt>'\t'</tt> for tabs.
--   
--   Default: <tt>' '</tt>
cIndentChar :: Lens' Config Char

-- | How many <a>cIndentChar</a> characters for one indentation level.
--   
--   Default: <tt>2</tt>
cIndentDepth :: Lens' Config Int

-- | How many <a>cIndentChar</a> characters to indent additionally, when a
--   line break occurs, because <a>cMaxLineWidth</a> was exceeded.
--   
--   Assuming the line to print has to be broken multiple times, the
--   indentation of all resulting lines, except the first one, is increased
--   by this amount. For example
--   
--   <pre>
--   pretty (do cMaxLineWidth .= Just 8; cIndentAfterBreaks .= 4) "foo bar baz boo"
--   </pre>
--   
--   evaluates to
--   
--   <pre>
--   foo bar
--       baz
--       boo
--   </pre>
--   
--   Default: <tt>4</tt>
cIndentAfterBreaks :: Lens' Config Int

-- | Indentation level to start pretty printing with.
--   
--   Default: <tt>0</tt>
cInitIndent :: Lens' Config Int

-- | Precendence level to start pretty printing with.
--   
--   Default: <tt>(-1)</tt>
cInitPrecedence :: Lens' Config Int

-- | Leaves the default <tt>Config</tt> unchanged and returns <tt>()</tt>.
--   
--   Convenience function defined as:
--   
--   <pre>
--   defConfig = pure ()
--   </pre>
--   
--   See example in <tt>pretty</tt>.
defConfig :: State Config ()

-- | Instanciating this class for a type, declares how values of that type
--   should be pretty printed.
--   
--   As pretty printing may depend on some context, e.g. the current
--   indentation level, a <a>State</a> monad for pretty printing
--   (<a>PrettyM</a>) is used.
--   
--   A default implementation is provided copying behavior from a
--   <a>Show</a> instance. This can be convenient for deriving
--   <a>Pretty</a>, e.g. for base types or debugging. The default
--   implementation is defined by <tt>pp = pp . show</tt>.
class Pretty a where pp = pp . show

-- | Pretty print an <tt>a</tt> as a <a>PrettyM</a> action.
pp :: Pretty a => a -> PrettyM ()

-- | Pretty print an <tt>a</tt> as a <a>PrettyM</a> action.
pp :: (Pretty a, Show a) => a -> PrettyM ()

-- | The <a>PrettyM</a> monad is run in the pretty printing process, e.g.
--   in <a>pretty</a> or <a>prettyPrint</a>.
--   
--   <a>PrettyM</a> is internally a <a>State</a> monad manipulating a
--   <a>Config</a> and a list of pretty printed lines.
--   
--   Most of the combinators from this library take values of <a>Pretty</a>
--   printable types, convert them to <tt><a>PrettyM</a> ()</tt> actions
--   using <a>pp</a>, and combine the actions in some way resulting in a
--   new <tt><a>PrettyM</a> ()</tt> action.
data PrettyM a

-- | Print two <a>Pretty</a> printable things in sequence.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ "x" +&gt; 1  -- ↪ "x1"
--   </pre>
--   
--   Convenience function, defined as
--   
--   <pre>
--   a +&gt; b = pp a &gt;&gt; pp b
--   </pre>
(+>) :: (Pretty a, Pretty b) => a -> b -> PrettyM ()
infixr 5 +>

-- | Print two <a>Pretty</a> printable things in sequence, separated by a
--   space.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ "x" ~&gt; 1  -- ↪ "x 1"
--   </pre>
--   
--   Convenience function, defined as
--   
--   <pre>
--   a ~&gt; b = a +&gt; " " +&gt; b
--   </pre>
(~>) :: (Pretty a, Pretty b) => a -> b -> PrettyM ()
infixr 4 ~>

-- | Print two <a>Pretty</a> printable things in sequence, separated by a
--   newline.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ "x" \&gt; 1  -- ↪ "x
--                                      1"
--   </pre>
--   
--   Convenience function, defined as
--   
--   <pre>
--   a \&gt; b = a +&gt; "\n" +&gt; b
--   </pre>
(\>) :: (Pretty a, Pretty b) => a -> b -> PrettyM ()
infixr 3 \>

-- | Print an <tt>a</tt> with indentation increased by a certain amount of
--   <a>cIndentChar</a> characters.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $
--     "while (true) {" \&gt;
--     indentedByChars 2 ("f();" \&gt; "g();") \&gt;
--     "}"
--   -- ↪ "while (true) {
--   --      f();
--   --      g();
--   --    }"
--   </pre>
indentedByChars :: Pretty a => Int -> a -> PrettyM ()

-- | Same as <a>indentedByChars</a> but increases indentation in
--   <a>cIndentDepth</a> steps.
indentedBy :: Pretty a => Int -> a -> PrettyM ()

-- | Convenience function defined as:
--   
--   <pre>
--   indented = indentedBy 1
--   </pre>
indented :: Pretty a => a -> PrettyM ()

-- | Print a <tt>[a]</tt> as a block, meaning that the indentation level is
--   increased, and each <tt>a</tt> is printed on a single line.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ "do" ~&gt; block ["putStrLn hello", "putStrLn world"]
--   -- ↪ "do
--   --      putStrLn hello
--   --      putStrLn world"
--   </pre>
block :: Pretty a => [a] -> PrettyM ()

-- | Same as <a>block</a>, but starts the block on the current line.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ "do" ~&gt; block' ["putStrLn hello", "putStrLn world"]
--   -- ↪ "do putStrLn hello
--   --       putStrLn world"
--   </pre>
block' :: Pretty a => [a] -> PrettyM ()

-- | Print an <tt>a</tt> as a left-associative operator of a certain
--   fixity.
assocL :: Pretty a => Int -> a -> PrettyM ()

-- | Print an <tt>a</tt> as a right-associative operator of a certain
--   fixity.
assocR :: Pretty a => Int -> a -> PrettyM ()

-- | Print an <tt>a</tt> as a non-associative operator of a certain fixity.
assocN :: Pretty a => Int -> a -> PrettyM ()

-- | Print an <tt>a</tt> as the left argument of a mixfix operator.
left :: Pretty a => a -> PrettyM ()

-- | Print an <tt>a</tt> as the right argument of a mixfix operator.
right :: Pretty a => a -> PrettyM ()

-- | Print an <tt>a</tt> as an inner argument of a mixfix operator.
inner :: Pretty a => a -> PrettyM ()

-- | The constructors of this type can be used as short forms of
--   <a>left</a>, <a>right</a>, and <a>inner</a>.
data AssocAnn a

-- | Print an <tt>a</tt> as the left argument of a mixfix operator (behaves
--   like <a>left</a>).
L :: a -> AssocAnn a

-- | Print an <tt>a</tt> as the right argument of a mixfix operator
--   (behaves like <a>right</a>).
R :: a -> AssocAnn a

-- | Print an <tt>a</tt> as the inner argument of a mixfix operator
--   (behaves like <a>inner</a>).
I :: a -> AssocAnn a

-- | Print an <tt>a</tt> between each <tt>b</tt>.
--   
--   Examples:
--   
--   <pre>
--   pretty defConfig $ "," `betweenEach` []          -- ↪ ""
--   pretty defConfig $ "," `betweenEach` ["x"]       -- ↪ "x"
--   pretty defConfig $ "," `betweenEach` ["x", "y"]  -- ↪ "x,y"
--   </pre>
betweenEach :: (Pretty a, Pretty b) => a -> [b] -> PrettyM ()
infixl 6 `betweenEach`

-- | Print an <tt>a</tt> before each <tt>b</tt>.
--   
--   Examples:
--   
--   <pre>
--   pretty defConfig $ "," `beforeEach` []          -- ↪ ""
--   pretty defConfig $ "," `beforeEach` ["x"]       -- ↪ ",x"
--   pretty defConfig $ "," `beforeEach` ["x", "y"]  -- ↪ ",x,y"
--   </pre>
beforeEach :: (Pretty a, Pretty b) => a -> [b] -> PrettyM ()
infixl 6 `beforeEach`

-- | Print an <tt>a</tt> after each <tt>b</tt>.
--   
--   Examples:
--   
--   <pre>
--   pretty defConfig $ "," `afterEach` []          -- ↪ ""
--   pretty defConfig $ "," `afterEach` ["x"]       -- ↪ "x,"
--   pretty defConfig $ "," `afterEach` ["x", "y"]  -- ↪ "x,y,"
--   </pre>
afterEach :: (Pretty a, Pretty b) => a -> [b] -> PrettyM ()
infixl 6 `afterEach`

-- | Print a <tt>[a]</tt> similar to its <a>Show</a> instance.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ ppList [ "x", "y" ]  -- ↪ "[ x, y ]"
--   </pre>
ppList :: Pretty a => [a] -> PrettyM ()

-- | Print a list map <tt>[(k,v)]</tt> as <a>ppList</a>, but render
--   <tt>(k,v)</tt> pairs as <tt>"k → v"</tt>.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ ppListMap [ ("k1", "v1"), ("k2", "v2") ]
--   -- ↪ "[ k1 → v1, k2 → v2 ]"
--   </pre>
ppListMap :: (Pretty a, Pretty b) => [(a, b)] -> PrettyM ()

-- | Print a <tt>Data.Map</tt> in the same way as <a>ppListMap</a>.
ppMap :: (Pretty a, Pretty b) => Map a b -> PrettyM ()

-- | Print a horizontal bar consisting of a <a>Char</a> as long as
--   <a>cMaxLineWidth</a> (or 80 if it is <tt>Nothing</tt>).
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ bar '-'
--   -- ↪ "-----------------------------------------…"
--   </pre>
bar :: Char -> PrettyM ()

-- | Print a horizontal bar consisting of a <a>Char</a> as long as
--   <a>cMaxLineWidth</a> (or 80 if it is <tt>Nothing</tt>). The horizontal
--   bar has a title <a>String</a> printed at column 6.
--   
--   Example:
--   
--   <pre>
--   pretty defConfig $ titleBar '-' "Foo"
--   -- ↪ "----- Foo -------------------------------…"
--   </pre>
titleBar :: Pretty a => Char -> a -> PrettyM ()

-- | Print a newline (line break).
nl :: PrettyM ()

-- | Print a space.
sp :: PrettyM ()

-- | The <a>Pretty1</a> type class lifts <a>Pretty</a> printing to unary
--   type constructors. It can be used in special cases to abstract over
--   type constructors which are <a>Pretty</a> printable for any
--   <a>Pretty</a> printable type argument.
class Pretty1 f where pp1 = pp
pp1 :: (Pretty1 f, Pretty a) => f a -> PrettyM ()
pp1 :: (Pretty1 f, Pretty (f a)) => f a -> PrettyM ()

-- | The <a>Pretty2</a> type class lifts <a>Pretty</a> printing to binary
--   type constructors. It can be used in special cases to abstract over
--   type constructors which are <a>Pretty</a> printable for any
--   <a>Pretty</a> printable type arguments.
class Pretty2 (f :: * -> * -> *) where pp2 = pp
pp2 :: (Pretty2 f, Pretty a, Pretty b) => f a b -> PrettyM ()
pp2 :: (Pretty2 f, Pretty (f a b)) => f a b -> PrettyM ()

-- | A state monad parameterized by the type <tt>s</tt> of the state to
--   carry.
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
type State s = StateT s Identity

-- | Replace the target of a <a>Lens</a> or all of the targets of a
--   <a>Setter</a> or <a>Traversal</a> in our monadic state with a new
--   value, irrespective of the old.
--   
--   This is an infix version of <a>assign</a>.
--   
--   <pre>
--   &gt;&gt;&gt; execState (do _1 .= c; _2 .= d) (a,b)
--   (c,d)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; execState (both .= c) (a,b)
--   (c,c)
--   </pre>
--   
--   <pre>
--   (<a>.=</a>) :: <a>MonadState</a> s m =&gt; <a>Iso'</a> s a       -&gt; a -&gt; m ()
--   (<a>.=</a>) :: <a>MonadState</a> s m =&gt; <a>Lens'</a> s a      -&gt; a -&gt; m ()
--   (<a>.=</a>) :: <a>MonadState</a> s m =&gt; <a>Traversal'</a> s a -&gt; a -&gt; m ()
--   (<a>.=</a>) :: <a>MonadState</a> s m =&gt; <a>Setter'</a> s a    -&gt; a -&gt; m ()
--   </pre>
--   
--   <i>It puts the state in the monad or it gets the hose again.</i>
(.=) :: MonadState s m => ASetter s s a b -> b -> m ()
infix 4 .=
