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


-- | Tangible Values -- composable interfaces
--   
--   TV is a library for composing <i>tangible values</i> ("TVs"), i.e.,
--   values that carry along external interfaces. Values and interfaces are
--   <i>combined and separable</i>, which makes TVs ready to use and to
--   reuse.
--   
--   Try out the examples in <tt>src/Examples.hs</tt>.
--   
--   For more information, including examples, please see the project wiki
--   page <a>http://haskell.org/haskellwiki/TV</a>
--   
--   This page and the module documentation pages have links to colorized
--   source code and to wiki pages where you can read and contribute /user
--   comments/. Enjoy!
--   
--   © 2006-2012 by Conal Elliott; BSD3 license.
@package TV
@version 0.4.9


-- | Inputs -- means of obtaining values
module Interface.TV.Input

-- | An <i>Input</i> describes a way to obtain a functional value from a
--   user. Used in <tt>Output</tt> for making function visualizations. The
--   constructors: primitive, pairing, and title.
data Input src :: * -> *
IPrim :: src a -> Input src a
IPair :: Input src a -> Input src b -> Input src (a, b)
ITitle :: String -> Input src a -> Input src a
input :: (Pair src, Title_f src) => Input src t -> src t

-- | Input primitive
iPrim :: src a -> Input src a

-- | Input a pair
iPair :: Input src a -> Input src b -> Input src (a, b)

-- | Title (label) an input
iTitle :: String -> Input src a -> Input src a

-- | Dissect a pair-valued input into two inputs. Loses outer
--   <a>iTitle</a>s. Must be a (possibly titled) pair-style input.
asIPair :: Input src (a, b) -> (Input src a, Input src b)
instance Functor src => Functor (Input src)
instance Pair (Input src)
instance Show (Input src a)
instance Title_f (Input src)


-- | Outputs (interfaces) -- means of presenting values
module Interface.TV.Output

-- | An <i>Output</i> describes a way to present a functional value,
--   perhaps interactively. It is the user-interface half of a tangible
--   value. The constructors: primitive, function, pairing, and title.
data Output src snk :: * -> *
OPrim :: snk a -> Output src snk a
OLambda :: Input src a -> Output src snk b -> Output src snk (a -> b)
OPair :: Output src snk a -> Output src snk b -> Output src snk (a, b)
OTitle :: String -> Output src snk a -> Output src snk a
output :: (Pair src, Pair snk, Lambda src snk, Title_f src, Title_f snk) => Output src snk t -> snk t

-- | Output primitive
oPrim :: snk a -> Output src snk a

-- | Visualize a function. Akin to <i>lambda</i>
oLambda :: Input src a -> Output src snk b -> Output src snk (a -> b)

-- | Visualize a pair
oPair :: Output src snk a -> Output src snk b -> Output src snk (a, b)

-- | Title (label) an output
oTitle :: String -> Output src snk a -> Output src snk a

-- | Dissect a function-valued output into input &amp; output. Loses outer
--   <a>oTitle</a>s. Must be a (possibly titled) pair-style input.
asOLambda :: Output src snk (a -> b) -> (Input src a, Output src snk b)
asOPair :: Output src snk (a, b) -> (Output src snk a, Output src snk b)
instance ContraFunctor snk => ContraFunctor (Output src snk)
instance Lambda (Input src) (Output src snk)
instance Pair (Output src snk)
instance Show (Output src snk a)
instance Title_f (Output src snk)


-- | <a>Output</a> transformations, as a deep arrow.
module Interface.TV.OFun

-- | Output functions.
type OX dom ran a b = Output dom ran a -> Output dom ran b

-- | Output functions as a <a>DeepArrow</a>
data OFun dom ran a b

-- | Like <tt>wrapF</tt>, but for outputs and reversed orientation.
--   Specialization of <tt>wrapAO</tt>.
wrapO :: (Functor dom, ContraFunctor ran) => (b' -> b) -> (a -> a') -> OX dom ran (a -> b) (a' -> b')
instance FunArr (OFun dom ran) (Output dom ran)
instance DeepArrow (OFun dom ran)
instance Arrow (OFun dom ran)
instance Category (OFun dom ran)


-- | Tangible values -- interface (output) and value, combined &amp;
--   separable
module Interface.TV.Tangible

-- | Tangible values (TVs).
type TV src snk = Output src snk :*: Id

-- | Arrow on <a>TV</a>s
type TVFun src snk = OFun src snk ::*:: (->)

-- | Make a <a>TV</a>
tv :: Output src snk a -> a -> TV src snk a

-- | Dissect a <a>TV</a>
unTv :: TV src snk a -> (Output src snk a, a)

-- | Useful to define disambiguating type-specializations of <a>runTV</a>
type RunTV src snk = forall a. TV src snk a -> IO ()

-- | Run a <a>TV</a>
runTV :: (Title_f snk, Title_f src, Lambda src snk, Pair snk, Pair src, ToOI snk) => RunTV src snk


-- | Some common interaction vocabulary
module Interface.TV.Common

-- | This class captures some useful operations available in some input
--   types, and allows definition of some "<tt>Common</tt>" <a>Input</a>s
class CommonIns src where getBool = getRead
getString :: CommonIns src => String -> src String
getRead :: (CommonIns src, Show a, Read a) => a -> src a
getBool :: CommonIns src => Bool -> src Bool

-- | Read with default value. If the input doesn't parse as a value of the
--   expected type, or it's ambiguous, yield the default value.
readD :: Read a => a -> String -> a

-- | <a>getRead</a> for <a>Functor</a>s
getReadF :: (CommonIns src, Functor src, Show a, Read a) => a -> src a

-- | This class captures some useful operations available in some arrows
--   and allows definition of some "<tt>Common</tt>" <a>Input</a>s,
--   <a>Output</a>s, and TVs.
class CommonOuts snk where putBool = putShow
putString :: CommonOuts snk => snk String
putShow :: (CommonOuts snk, Show a) => snk a
putBool :: CommonOuts snk => snk Bool
putShowC :: (CommonOuts snk, ContraFunctor snk, Show a) => snk a

-- | Inputs that work over all <tt>CommonInsOuts</tt> typecons.
type CInput a = forall src. CommonIns src => Input src a

-- | <a>CInput</a> with initial value
type CInputI a = a -> CInput a

-- | Outputs that work over all <a>CommonOuts</a> typecons.
type COutput a = forall src snk. (CommonIns src, CommonOuts snk) => Output src snk a

-- | Convenient type synonym for TVs that work over all
--   <tt>CommonInsOuts</tt> typecons.
type CTV a = forall src snk. (CommonIns src, CommonOuts snk) => TV src snk a

-- | String input with default
stringIn :: CInputI String

-- | Bool input with default
boolIn :: CInputI Bool

-- | Input a readable value. Use default when read fails.
readIn :: (Read a, Show a) => CInputI a

-- | Output a string
stringOut :: COutput String

-- | Output a bool
boolOut :: COutput Bool

-- | Output a showable value
showOut :: Show a => COutput a

-- | <a>Output</a> version of <a>interact</a>. Well, not quite, since the
--   IO version uses <a>getLine</a> instead of <a>getContents</a>. See also
--   <a>interactOut</a>
interactLine :: String -> COutput (String -> String)

-- | Handy Read+Show wrapper
readShow :: (Read a, Show b, CommonIns src, CommonOuts snk, Functor src, ContraFunctor snk) => Output src snk (String -> String) -> a -> Output src snk (a -> b)

-- | Read+Show of <a>interactLine</a>
interactLineRS :: (Read a, Show a, Show b, CommonIns src, CommonOuts snk) => a -> Output src snk (a -> b)
instance CommonOuts OI
instance CommonIns IO


-- | Default inputs and outputs
--   
--   TODO: Provide <tt>[a]</tt> instances for DefaultIn and DefaultOut
--   using the trick for Show <tt>[a]</tt>. See
--   <a>Interface.TV.DefaultsList</a> for a first attempt.
module Interface.TV.Defaults

-- | Class of types that provide a default input
class DefaultIn src a
defaultIn :: DefaultIn src a => Input src a

-- | Class of types that provide a default output
class DefaultOut src snk a
defaultOut :: DefaultOut src snk a => Output src snk a
instance [incoherent] (Show a, CommonIns src, CommonOuts snk, DefaultOut src snk a) => DefaultOut src snk [a]
instance [incoherent] (DefaultIn src a, DefaultOut src snk b) => DefaultOut src snk (a -> b)
instance [incoherent] (DefaultOut src snk a, DefaultOut src snk b) => DefaultOut src snk (a, b)
instance [incoherent] (CommonIns src, CommonOuts snk) => DefaultOut src snk String
instance [incoherent] (CommonIns src, CommonOuts snk) => DefaultOut src snk Float
instance [incoherent] (CommonIns src, CommonOuts snk) => DefaultOut src snk Double
instance [incoherent] (CommonIns src, CommonOuts snk) => DefaultOut src snk Int
instance [incoherent] (CommonIns src, CommonOuts snk) => DefaultOut src snk Bool
instance [incoherent] (Read a, Show a, CommonIns src, DefaultIn src a) => DefaultIn src [a]
instance [incoherent] (DefaultIn src a, DefaultIn src b) => DefaultIn src (a, b)
instance [incoherent] CommonIns src => DefaultIn src String
instance [incoherent] CommonIns src => DefaultIn src Float
instance [incoherent] CommonIns src => DefaultIn src Double
instance [incoherent] CommonIns src => DefaultIn src Int
instance [incoherent] CommonIns src => DefaultIn src Bool


-- | Make IO play with TV
module Interface.TV.IO

-- | <a>Input</a> version of <a>getContents</a>
contentsIn :: Input IO String

-- | <a>Input</a> version of <a>readFile</a>
fileIn :: FilePath -> Input IO String

-- | Equivalent of <a>interact</a>. See also <a>interactLine</a>
interactOut :: Output IO OI (String -> String)

-- | Read+Show of <a>interact</a>
interactRS :: (Read a, Show b) => a -> Output IO OI (a -> b)

-- | <a>Output</a> version of <a>writeFile</a>
fileOut :: FilePath -> Output IO OI String

-- | Identity function, with <a>fileIn</a> and <a>stringOut</a>
fromFile :: FilePath -> TV IO OI (String -> String)

-- | Identity function, with stringIn' and <a>fileOut</a>
toFile :: FilePath -> TV IO OI (String -> String)

-- | Type-disambiguating alias for <a>runTV</a>
runIO :: RunTV IO OI


-- | Package up the various TV modules into one. Also re-exports DeepArrow
--   modules.
module Interface.TV