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


-- | Template haskell utilities for constructing records with default values
--   
--   If you have a datatype with a lot of default-able fields, e.g.
--   
--   <pre>
--   data Foo =
--     { fld1 :: Maybe Int
--     , fld2 :: Maybe Char
--     , fld3 :: Word
--     }
--   </pre>
--   
--   and you want to avoid the the boilerplate of writing all the default
--   values every time you construct a record of this type, you could write
--   a "default value" of this type:
--   
--   <pre>
--   defaultFoo :: Foo
--   defaultFoo = Foo { fld1 = Nothing, fld2 = Nothing, fld3 = 0 }
--   </pre>
--   
--   You could then use record modification syntax to make necessary
--   changes to this value. But perhaps you can't / don't want to provide
--   default values for <i>all</i> of the fields, but only some of them?
--   You could implement a "default smart constructor" that would take the
--   non-optional arguments and then fill in the optional ones like so:
--   
--   <pre>
--   defaultFoo :: Word -&gt; Foo
--   defaultFoo x = Foo { fld1 = Nothing, fld2 = Nothing, fld3 = x }
--   </pre>
--   
--   But then you lose the benefit of record syntax: you can't name the
--   fields you're providing values for.
--   
--   This package reconciles the two problems: with only a little bit of
--   Template Haskell it provides a way to construct a record with optional
--   fields while also letting you refer to the names of those fields. You
--   make two splices:
--   
--   <pre>
--   mkToPartial ''Foo
--     -- defines 'mkfld1', 'mkfld2', 'mkfld3'
--   mkFromPartial "mkFoo" [t|Foo|] [|Foo { fld1 = Nothing, fld2 = Nothing }
--     |]
--     -- defines 'mkFoo'
--   </pre>
--   
--   And then you can use them like so:
--   
--   <pre>
--   val :: Foo
--   val = mkFoo
--     $ mkfld3 123
--     ? mkfld1 (Just 456)
--   -- val = Foo { fld1 = Just 456, fld2 = Nothing, fld3 = 123 }
--   </pre>
--   
--   The Template Haskell splice lets you define default values for a
--   subset of the fields, and those defaults will be used when you call
--   <tt>mkFoo</tt>. You can list fields in any order, but if you omit a
--   mandatory field (one that doesn't have a default), that would be a
--   type error at compile time.
--   
--   You can make multiple <a>Data.Partial.TH.mkFromPartial</a> splices,
--   this is occasionally useful for parameterized types, for example:
--   
--   <pre>
--   data Bar a =
--     { bar1 :: Maybe Int
--     , bar2 :: a
--     }
--   mkToPartial ''Bar
--   mkFromPartial "mkBar" [t|forall a. Bar a|]
--     [|Bar { bar1 = Nothing }
--     |]
--     -- mkBar :: ... -&gt; Bar a, and bar2 is a required field
--   mkFromPartial "mkBarMaybe" [t|forall a. Bar (Maybe a)|]
--     [|Bar { bar1 = Nothing, bar2 = Nothing }
--     |]
--     -- mkBarMaybe :: ... -&gt; Bar (Maybe a), and bar2 is an optional field
--   </pre>
@package partial-records
@version 0.2.2.0


-- | If you have a datatype with a lot of default-able fields, e.g.
--   
--   <pre>
--   data Foo =
--     { fld1 :: Maybe Int
--     , fld2 :: Maybe Char
--     , fld3 :: Word
--     }
--   </pre>
--   
--   and you want to avoid the the boilerplate of writing all the default
--   values every time you construct a record of this type, you could write
--   a "default value" of this type:
--   
--   <pre>
--   defaultFoo :: Foo
--   defaultFoo = Foo { fld1 = Nothing, fld2 = Nothing, fld3 = 0 }
--   </pre>
--   
--   You could then use record modification syntax to make necessary
--   changes to this value. But perhaps you can't/don't want to provide
--   default values for <i>all</i> of the fields, but only some of them?
--   You could implement a "default smart constructor" that would take the
--   non-optional arguments and then fill in the optional ones like so:
--   
--   <pre>
--   defaultFoo :: Word -&gt; Foo
--   defaultFoo x = Foo { fld1 = Nothing, fld2 = Nothing, fld3 = x }
--   </pre>
--   
--   But then you lose the benefit of record syntax: you can't name the
--   fields you're providing values for.
--   
--   This package reconciles the two problems: with only a little bit of
--   Template Haskell it provides a way to construct a record with optional
--   fields while also letting you refer to the names of those fields. You
--   make two splices:
--   
--   <pre>
--   <a>mkToPartial</a> ''Foo
--     -- defines mkfld1, mkfld2, mkfld3
--   <a>mkFromPartial</a> "mkFoo" [t|Foo|] [|Foo { fld1 = Nothing, fld2 = Nothing }|]
--     -- defines mkFoo
--   </pre>
--   
--   And then you can use them like so:
--   
--   <pre>
--   val :: Foo
--   val = mkFoo
--     $ mkfld3 123
--     <a>?</a> mkfld1 (Just 456)
--   -- val = Foo { fld1 = Just 456, fld2 = Nothing, fld3 = 123 }
--   </pre>
--   
--   The Template Haskell splice lets you define default values for a
--   subset of the fields, and those defaults will be used when you call
--   <tt>mkFoo</tt>. You can list fields in any order, but if you omit a
--   mandatory field (one that doesn't have a default), that would be a
--   type error at compile time.
--   
--   You can make multiple <a>mkFromPartial</a> splices, this is
--   occasionally useful for parameterized types, for example:
--   
--   <pre>
--   data Bar a =
--     { bar1 :: Maybe Int
--     , bar2 :: a
--     }
--   <a>mkToPartial</a> ''Bar
--   <a>mkFromPartial</a> "mkBar" [t|forall a. Bar a|]
--     [|Bar { bar1 = Nothing }|]
--     -- mkBar :: ... -&gt; Bar a, and bar2 is a required field
--   <a>mkFromPartial</a> "mkBarMaybe" [t|forall a. Bar (Maybe a)|]
--     [|Bar { bar1 = Nothing, bar2 = Nothing }|]
--     -- mkBarMaybe :: ... -&gt; Bar (Maybe a), and bar2 is an optional field
--   </pre>
module Data.Partial

-- | <tt>Partial T '[b1, b2, ...]</tt> is a partial version of the datatype
--   <tt>T</tt> where the first field's presence is indicated by <tt>b1 ::
--   Bool</tt>, second field's presence is indicated by <tt>b2</tt> and so
--   on. Instances of this would be generated by <a>mkToPartial</a>.
data family Partial (a :: *) :: [Bool] -> *

-- | A "graded semigroup": if we have two partial structures with only some
--   of the fields, we can merge them to obtain a partial structure with
--   the union of the fields. Prefers to take fields from the left hand
--   side. Instances of this would be generated by <a>mkToPartial</a>.
class Graded a
(?) :: Graded a => Partial a b1 -> Partial a b2 -> Partial a (b1 <||> b2)
type family (b1 :: [Bool]) <||> (b2 :: [Bool]) :: [Bool]


-- | Utility functions used by generated Template Haskell code.
module Data.Partial.Utils
data Opt b x
[Has] :: x -> Opt  'True x
[Hasn't] :: Opt  'False x
joinOpt :: Opt b1 x -> Opt b2 x -> Opt (b1 || b2) x
fromOpt :: x -> Opt b x -> x
class Require (dc :: Symbol) (fld :: Symbol) (b :: Bool)
unOpt :: Require dc fld b => p dc -> p fld -> Opt b x -> x
instance Data.Partial.Utils.Require dc fld 'GHC.Types.True
instance (TypeError ...) => Data.Partial.Utils.Require dc fld 'GHC.Types.False


-- | Template Haskell utilities for constructing records with default
--   values.
module Data.Partial.TH

-- | Generate an instance of the <a>Partial</a> family and the
--   <a>Graded</a> class. Takes a data constructor name. For example:
--   
--   <pre>
--   data Foo a = Foo a { fld1 :: Int, fld2 :: a }
--   mkToPartial ''Foo
--   </pre>
--   
--   expands to:
--   
--   <pre>
--   data instance <a>Partial</a> (Foo a) bs where
--     Partial_Foo :: forall a b1 b2.
--       <a>Opt</a> b1 Int -&gt; <a>Opt</a> b2 a -&gt; Partial (Foo a) '[b1, b2]
--   {-# INLINE mkfld1 #-}
--   mkfld1 :: Int -&gt; <a>Partial</a> (Foo a) '[ 'True, 'False]
--   mkfld1 x = Partial_Foo (<a>Has</a> x) <a>Hasn't</a>
--   {-# INLINE mkfld2 #-}
--   mkfld2 :: a -&gt; <a>Partial</a> (Foo a) '[ 'False, 'True]
--   mkfld2 x = Partial_Foo <a>Hasn't</a> (<a>Has</a> x)
--   instance <a>Graded</a> (Foo a) where
--     {-# INLINE (<a>?</a>) #-}
--     Partial_Foo x1 x2 <a>?</a> Partial_Foo y1 y1
--       = Partial_Foo (<a>joinOpt</a> x1 y1) (<a>joinOpt</a> x2 y2)
--   </pre>
mkToPartial :: Name -> Q [Dec]

-- | Generate a function that turns a <a>Partial</a> into a value of the
--   actual datatype. Takes a name for the function to be defined, as well
--   as the type the result should have (can include type variables but all
--   of them must be quantified), as well as the "default values": a record
--   construction specifying just those fields that you want, with their
--   default values. For example:
--   
--   <pre>
--   data Foo a = Foo a { fld1 :: Int, fld2 :: a }
--   mkFromPartial "mkFoo" [t|forall a. Foo (Maybe a)|] [|Foo { fld2 = Nothing }|]
--   </pre>
--   
--   expands to:
--   
--   <pre>
--   {-# INLINE mkFoo #-}
--   mkFoo :: forall a b1 b2.
--     ( <a>Require</a> "Foo" "fld1" b1
--     -- ^ Assert that b1 ~ 'True but generate a nice error message if not
--     )
--     =&gt; <a>Partial</a> (Foo (Maybe a)) '[b1, b2] -&gt; Foo (Maybe a)
--   mkFoo (Partial_Foo x1 x2) = Foo (<a>unOpt</a> x1) (<a>fromOpt</a> Nothing x2)
--   </pre>
mkFromPartial :: String -> Q Type -> Q Exp -> Q [Dec]

-- | The default procedure for generating field constructors from field
--   names is prepending <tt>"mk"</tt>. You can override this behavior by
--   passing a custom field name generating function to this function.
mkToPartialWith :: (String -> String) -> Name -> Q [Dec]