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


-- | Typeclass for builders of linear data structures
--   
@package buildable
@version 0.1.0.3


-- | Various linear data structures can be expensive to construct in a
--   repetitive fashion. For example, to append a single value to the end
--   of a list is <tt>O(n)</tt>, and as such doing so repeatedly is
--   recommended against.
--   
--   As such, to efficiently construct such structures we have the notion
--   of a <i>builder</i>. This can be used to more efficiently prepend and
--   append values, and at the end we "run" the builder to construct the
--   overall value.
--   
--   This module provides an abstraction over various builders for specific
--   data structures. It also aims to minimise the number of functions
--   required to add various values to the builder by using a typeclass and
--   newtype wrappers.
--   
--   To construct a value from it's builder:
--   
--   <ol>
--   <li>Start with either <tt><a>mempty</a></tt> for an empty
--   <a>Builder</a>, or if you have an initial value use
--   <tt><a>fromValue</a></tt>.<ol><li>Add initial values to the front or
--   back using <a>prepend</a> / <a>&lt;|</a> or <a>append</a> /
--   <a>|&gt;</a> respectively.</li><li>Once you've finished constructing
--   your builder, create your final value with
--   <a>build</a>.</li></ol></li>
--   </ol>
--   
--   <i>Note</i>: all instances are defined for both strict and lazy
--   <tt>ByteString</tt> and <tt>Text</tt> values.
module Data.Buildable

-- | A linear data structure <tt>a</tt> is buildable if we can prepend and
--   append both values of the data structure in question and its
--   constituent elements to the builder.
class (BuildFrom (Builder a) a, BuildFrom (Builder a) (Unit a)) => Buildable a where type family Unit a type family Builder a
build :: Buildable a => Builder a -> a

-- | Which values can be built from other values?
--   
--   Minimal complete definition:
--   
--   <ul>
--   <li><pre>fromValue</pre></li>
--   </ul>
class Monoid b => BuildFrom b a where prepend a b = fromValue a <> b append b a = b <> fromValue a
fromValue :: BuildFrom b a => a -> b
prepend :: BuildFrom b a => a -> b -> b
append :: BuildFrom b a => b -> a -> b

-- | <tt>CanBuildFrom b a</tt> states that we can build a value of type
--   <tt>b</tt> with values of type <tt>a</tt>.
type CanBuildFrom b a = (Buildable b, BuildFrom (Builder b) a)
singleton :: CanBuildFrom b a => a -> b

-- | An alias for <a>prepend</a>.
--   
--   Mnemonic: the arrow points to the new value.
(<|) :: BuildFrom b a => a -> b -> b

-- | An alias for <a>append</a>.
--   
--   Mnemonic: the arrow points to the new value.
(|>) :: BuildFrom b a => b -> a -> b

-- | An explicit chunkified representation of a Builder. If we have a
--   polymorphic expression <tt>buildValue</tt> that can be used to build
--   something of type <tt>b</tt>, then the following are equivalent:
--   
--   <pre>
--   'build' buildValue == mconcat . unChunk $ build buildValue
--   </pre>
newtype Chunked a
Chunks :: [a] -> Chunked a
unChunk :: Chunked a -> [a]

-- | You probably won't actually need to use this type; it's defined solely
--   to be the <a>Builder</a> for <a>Chunked</a>.
newtype ChunkedBuilder a
CB :: DList a -> ChunkedBuilder a
unCB :: ChunkedBuilder a -> DList a

-- | Explicitly state that a number should be encoded in big-endian format.
newtype BigEndian a
BE :: a -> BigEndian a
unBE :: BigEndian a -> a

-- | Explicitly state that a number should be encoded in little-endian
--   format.
newtype LittleEndian a
LE :: a -> LittleEndian a
unLE :: LittleEndian a -> a

-- | Encode a number as its decimal representation with ASCII-encoded
--   characters.
newtype Dec a
Dec :: a -> Dec a
unDec :: Dec a -> a

-- | Encode a number as its hexadecimal representation with ASCII-encoded
--   (lower-case) characters using the shortest possible representation.
--   For fixed-width encoding use <a>HexFixed</a> instead.
newtype Hex a
Hex :: a -> Hex a
unHex :: Hex a -> a

-- | Encode a number as its hexadecimal representation with ASCII-encoded
--   (lower-case) characters using a fixed number of hexadecimal digits.
--   For shortest-width encoding use <a>Hex</a> instead.
newtype HexFixed a
HexFixed :: a -> HexFixed a
unHexFixed :: HexFixed a -> a

-- | Unicode codepoints are truncated to 7 bits and prefixed with a leading
--   0. For the codepoints 0-127 this corresponds to the ASCII encoding.
newtype Char7 a
Char7 :: a -> Char7 a
unChar7 :: Char7 a -> a

-- | Unicode codepoints are truncated to 8 bits. For the codepoints 0-255
--   this corresponds to the ISO/IEC 8859-1 (aka Latin-1) encoding.
newtype Char8 a
Char8 :: a -> Char8 a
unChar8 :: Char8 a -> a

-- | Encode a textual value using UTF-8.
newtype Utf8 a
Utf8 :: a -> Utf8 a
unUtf8 :: Utf8 a -> a

-- | Encode a textual value using UTF-16.
--   
--   Needs to be used with either <a>BigEndian</a> or <a>LittleEndian</a>.
newtype Utf16 a
Utf16 :: a -> Utf16 a
unUtf16 :: Utf16 a -> a

-- | Encode a textual value using UTF-32.
--   
--   Needs to be used with either <a>BigEndian</a> or <a>LittleEndian</a>.
newtype Utf32 a
Utf32 :: a -> Utf32 a
unUtf32 :: Utf32 a -> a
instance [overlap ok] Eq a => Eq (Chunked a)
instance [overlap ok] Ord a => Ord (Chunked a)
instance [overlap ok] Show a => Show (Chunked a)
instance [overlap ok] Read a => Read (Chunked a)
instance [overlap ok] Monoid (Chunked a)
instance [overlap ok] Functor Chunked
instance [overlap ok] Monoid (ChunkedBuilder a)
instance [overlap ok] Functor ChunkedBuilder
instance [overlap ok] Eq a => Eq (BigEndian a)
instance [overlap ok] Ord a => Ord (BigEndian a)
instance [overlap ok] Show a => Show (BigEndian a)
instance [overlap ok] Read a => Read (BigEndian a)
instance [overlap ok] Bounded a => Bounded (BigEndian a)
instance [overlap ok] Enum a => Enum (BigEndian a)
instance [overlap ok] Num a => Num (BigEndian a)
instance [overlap ok] Integral a => Integral (BigEndian a)
instance [overlap ok] Real a => Real (BigEndian a)
instance [overlap ok] RealFloat a => RealFloat (BigEndian a)
instance [overlap ok] RealFrac a => RealFrac (BigEndian a)
instance [overlap ok] Floating a => Floating (BigEndian a)
instance [overlap ok] Fractional a => Fractional (BigEndian a)
instance [overlap ok] Eq a => Eq (LittleEndian a)
instance [overlap ok] Ord a => Ord (LittleEndian a)
instance [overlap ok] Show a => Show (LittleEndian a)
instance [overlap ok] Read a => Read (LittleEndian a)
instance [overlap ok] Bounded a => Bounded (LittleEndian a)
instance [overlap ok] Enum a => Enum (LittleEndian a)
instance [overlap ok] Num a => Num (LittleEndian a)
instance [overlap ok] Integral a => Integral (LittleEndian a)
instance [overlap ok] Real a => Real (LittleEndian a)
instance [overlap ok] RealFloat a => RealFloat (LittleEndian a)
instance [overlap ok] RealFrac a => RealFrac (LittleEndian a)
instance [overlap ok] Floating a => Floating (LittleEndian a)
instance [overlap ok] Fractional a => Fractional (LittleEndian a)
instance [overlap ok] Eq a => Eq (Dec a)
instance [overlap ok] Ord a => Ord (Dec a)
instance [overlap ok] Show a => Show (Dec a)
instance [overlap ok] Read a => Read (Dec a)
instance [overlap ok] Bounded a => Bounded (Dec a)
instance [overlap ok] Enum a => Enum (Dec a)
instance [overlap ok] Num a => Num (Dec a)
instance [overlap ok] Integral a => Integral (Dec a)
instance [overlap ok] Real a => Real (Dec a)
instance [overlap ok] RealFloat a => RealFloat (Dec a)
instance [overlap ok] RealFrac a => RealFrac (Dec a)
instance [overlap ok] Floating a => Floating (Dec a)
instance [overlap ok] Fractional a => Fractional (Dec a)
instance [overlap ok] Eq a => Eq (Hex a)
instance [overlap ok] Ord a => Ord (Hex a)
instance [overlap ok] Show a => Show (Hex a)
instance [overlap ok] Read a => Read (Hex a)
instance [overlap ok] Bounded a => Bounded (Hex a)
instance [overlap ok] Enum a => Enum (Hex a)
instance [overlap ok] Num a => Num (Hex a)
instance [overlap ok] Integral a => Integral (Hex a)
instance [overlap ok] Real a => Real (Hex a)
instance [overlap ok] RealFloat a => RealFloat (Hex a)
instance [overlap ok] RealFrac a => RealFrac (Hex a)
instance [overlap ok] Floating a => Floating (Hex a)
instance [overlap ok] Fractional a => Fractional (Hex a)
instance [overlap ok] Eq a => Eq (HexFixed a)
instance [overlap ok] Ord a => Ord (HexFixed a)
instance [overlap ok] Show a => Show (HexFixed a)
instance [overlap ok] Read a => Read (HexFixed a)
instance [overlap ok] Bounded a => Bounded (HexFixed a)
instance [overlap ok] Enum a => Enum (HexFixed a)
instance [overlap ok] Num a => Num (HexFixed a)
instance [overlap ok] Integral a => Integral (HexFixed a)
instance [overlap ok] Real a => Real (HexFixed a)
instance [overlap ok] RealFloat a => RealFloat (HexFixed a)
instance [overlap ok] RealFrac a => RealFrac (HexFixed a)
instance [overlap ok] Floating a => Floating (HexFixed a)
instance [overlap ok] Fractional a => Fractional (HexFixed a)
instance [overlap ok] Eq a => Eq (Char7 a)
instance [overlap ok] Ord a => Ord (Char7 a)
instance [overlap ok] Show a => Show (Char7 a)
instance [overlap ok] Read a => Read (Char7 a)
instance [overlap ok] Bounded a => Bounded (Char7 a)
instance [overlap ok] Enum a => Enum (Char7 a)
instance [overlap ok] Eq a => Eq (Char8 a)
instance [overlap ok] Ord a => Ord (Char8 a)
instance [overlap ok] Show a => Show (Char8 a)
instance [overlap ok] Read a => Read (Char8 a)
instance [overlap ok] Bounded a => Bounded (Char8 a)
instance [overlap ok] Enum a => Enum (Char8 a)
instance [overlap ok] Eq a => Eq (Utf8 a)
instance [overlap ok] Ord a => Ord (Utf8 a)
instance [overlap ok] Show a => Show (Utf8 a)
instance [overlap ok] Read a => Read (Utf8 a)
instance [overlap ok] Bounded a => Bounded (Utf8 a)
instance [overlap ok] Enum a => Enum (Utf8 a)
instance [overlap ok] Eq a => Eq (Utf16 a)
instance [overlap ok] Ord a => Ord (Utf16 a)
instance [overlap ok] Show a => Show (Utf16 a)
instance [overlap ok] Read a => Read (Utf16 a)
instance [overlap ok] Bounded a => Bounded (Utf16 a)
instance [overlap ok] Enum a => Enum (Utf16 a)
instance [overlap ok] Eq a => Eq (Utf32 a)
instance [overlap ok] Ord a => Ord (Utf32 a)
instance [overlap ok] Show a => Show (Utf32 a)
instance [overlap ok] Read a => Read (Utf32 a)
instance [overlap ok] Bounded a => Bounded (Utf32 a)
instance [overlap ok] Enum a => Enum (Utf32 a)
instance [overlap ok] BuildFrom (Seq a) [a]
instance [overlap ok] BuildFrom (Seq a) a
instance [overlap ok] BuildFrom (Seq a) (Seq a)
instance [overlap ok] Buildable (Seq a)
instance [overlap ok] BuildFrom Builder (Utf32 (LittleEndian ByteString))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf32 ByteString))
instance [overlap ok] BuildFrom Builder (Utf32 (BigEndian ByteString))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf32 ByteString))
instance [overlap ok] BuildFrom Builder (Utf16 (LittleEndian ByteString))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf16 ByteString))
instance [overlap ok] BuildFrom Builder (Utf16 (BigEndian ByteString))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf16 ByteString))
instance [overlap ok] BuildFrom Builder (Utf8 ByteString)
instance [overlap ok] BuildFrom Builder (Char8 ByteString)
instance [overlap ok] BuildFrom Builder (Utf32 (LittleEndian ByteString))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf32 ByteString))
instance [overlap ok] BuildFrom Builder (Utf32 (BigEndian ByteString))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf32 ByteString))
instance [overlap ok] BuildFrom Builder (Utf16 (LittleEndian ByteString))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf16 ByteString))
instance [overlap ok] BuildFrom Builder (Utf16 (BigEndian ByteString))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf16 ByteString))
instance [overlap ok] BuildFrom Builder (Utf8 ByteString)
instance [overlap ok] BuildFrom Builder (Char8 ByteString)
instance [overlap ok] BuildFrom Builder String
instance [overlap ok] BuildFrom Builder Char
instance [overlap ok] BuildFrom Builder Text
instance [overlap ok] BuildFrom Builder Text
instance [overlap ok] Buildable Text
instance [overlap ok] Buildable Text
instance [overlap ok] BuildFrom Builder (Utf32 (LittleEndian Text))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf32 Text))
instance [overlap ok] BuildFrom Builder (Utf32 (BigEndian Text))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf32 Text))
instance [overlap ok] BuildFrom Builder (Utf16 (LittleEndian Text))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf16 Text))
instance [overlap ok] BuildFrom Builder (Utf16 (BigEndian Text))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf16 Text))
instance [overlap ok] BuildFrom Builder (Utf8 Text)
instance [overlap ok] BuildFrom Builder (Utf32 (LittleEndian Text))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf32 Text))
instance [overlap ok] BuildFrom Builder (Utf32 (BigEndian Text))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf32 Text))
instance [overlap ok] BuildFrom Builder (Utf16 (LittleEndian Text))
instance [overlap ok] BuildFrom Builder (LittleEndian (Utf16 Text))
instance [overlap ok] BuildFrom Builder (Utf16 (BigEndian Text))
instance [overlap ok] BuildFrom Builder (BigEndian (Utf16 Text))
instance [overlap ok] BuildFrom Builder (Utf8 Text)
instance [overlap ok] BuildFrom Builder (Utf8 String)
instance [overlap ok] BuildFrom Builder (Char8 String)
instance [overlap ok] BuildFrom Builder (Char7 String)
instance [overlap ok] BuildFrom Builder (Utf8 Char)
instance [overlap ok] BuildFrom Builder (Char8 Char)
instance [overlap ok] BuildFrom Builder (Char7 Char)
instance [overlap ok] IsString a => IsString (Utf32 a)
instance [overlap ok] IsString a => IsString (Utf16 a)
instance [overlap ok] IsString a => IsString (Utf8 a)
instance [overlap ok] IsString a => IsString (Char8 a)
instance [overlap ok] IsString a => IsString (Char7 a)
instance [overlap ok] BuildFrom Builder (Hex Word)
instance [overlap ok] BuildFrom Builder (Dec Word)
instance [overlap ok] BuildFrom Builder (HexFixed Word64)
instance [overlap ok] BuildFrom Builder (Hex Word64)
instance [overlap ok] BuildFrom Builder (Dec Word64)
instance [overlap ok] BuildFrom Builder (LittleEndian Word64)
instance [overlap ok] BuildFrom Builder (BigEndian Word64)
instance [overlap ok] BuildFrom Builder (HexFixed Word32)
instance [overlap ok] BuildFrom Builder (Hex Word32)
instance [overlap ok] BuildFrom Builder (Dec Word32)
instance [overlap ok] BuildFrom Builder (LittleEndian Word32)
instance [overlap ok] BuildFrom Builder (BigEndian Word32)
instance [overlap ok] BuildFrom Builder (HexFixed Word16)
instance [overlap ok] BuildFrom Builder (Hex Word16)
instance [overlap ok] BuildFrom Builder (Dec Word16)
instance [overlap ok] BuildFrom Builder (LittleEndian Word16)
instance [overlap ok] BuildFrom Builder (BigEndian Word16)
instance [overlap ok] BuildFrom Builder (Dec Integer)
instance [overlap ok] BuildFrom Builder (Dec Int)
instance [overlap ok] BuildFrom Builder (HexFixed Int64)
instance [overlap ok] BuildFrom Builder (Dec Int64)
instance [overlap ok] BuildFrom Builder (LittleEndian Int64)
instance [overlap ok] BuildFrom Builder (BigEndian Int64)
instance [overlap ok] BuildFrom Builder (HexFixed Int32)
instance [overlap ok] BuildFrom Builder (Dec Int32)
instance [overlap ok] BuildFrom Builder (LittleEndian Int32)
instance [overlap ok] BuildFrom Builder (BigEndian Int32)
instance [overlap ok] BuildFrom Builder (HexFixed Int16)
instance [overlap ok] BuildFrom Builder (Dec Int16)
instance [overlap ok] BuildFrom Builder (LittleEndian Int16)
instance [overlap ok] BuildFrom Builder (BigEndian Int16)
instance [overlap ok] BuildFrom Builder (HexFixed Float)
instance [overlap ok] BuildFrom Builder (Dec Float)
instance [overlap ok] BuildFrom Builder (LittleEndian Float)
instance [overlap ok] BuildFrom Builder (BigEndian Float)
instance [overlap ok] BuildFrom Builder (HexFixed Double)
instance [overlap ok] BuildFrom Builder (Dec Double)
instance [overlap ok] BuildFrom Builder (LittleEndian Double)
instance [overlap ok] BuildFrom Builder (BigEndian Double)
instance [overlap ok] BuildFrom Builder (HexFixed Int8)
instance [overlap ok] BuildFrom Builder (Dec Int8)
instance [overlap ok] BuildFrom Builder Int8
instance [overlap ok] BuildFrom Builder (HexFixed Word8)
instance [overlap ok] BuildFrom Builder (Hex Word8)
instance [overlap ok] BuildFrom Builder (Dec Word8)
instance [overlap ok] BuildFrom Builder Word8
instance [overlap ok] BuildFrom Builder (HexFixed ByteString)
instance [overlap ok] BuildFrom Builder ByteString
instance [overlap ok] BuildFrom Builder (HexFixed ByteString)
instance [overlap ok] BuildFrom Builder ByteString
instance [overlap ok] Buildable ByteString
instance [overlap ok] Buildable ByteString
instance [overlap ok] (CanBuildFrom b a) => BuildFrom (ChunkedBuilder b) a
instance [overlap ok] Buildable b => BuildFrom (ChunkedBuilder b) (Chunked b)
instance [overlap ok] Buildable b => Buildable (Chunked b)
instance [overlap ok] BuildFrom (DList [a]) a
instance [overlap ok] BuildFrom (DList a) a
instance [overlap ok] BuildFrom (DList a) [a]
instance [overlap ok] BuildFrom [a] a
instance [overlap ok] Buildable [a]