View source for Tangible Value

[[Category:User interfaces]]
[[Category:Arrow]]
[[Category:Libraries]]
[[Category:Packages]]

== Abstract ==

'''TV''' is a library for composing ''tangible values'' ("TVs"), i.e., values that carry along external interfaces.  In particular, TVs can be composed to create new TVs, ''and'' they can be directly executed with a friendly GUI, a process that reads and writes character streams, or many other kinds interfaces.  Values and interfaces are ''combined'' for direct use, and ''separable'' for composition.  This combination makes for software that is ''ready to use and ready to reuse''.

TV can be thought of as a simple functional formulation of the Model-View-Controller pattern.  (My thanks to an anonymous ICFP referee for pointing out this connection.)  The value part of a TV is the ''model'', and the "interface" part, or "output" as it is called below, is the ''viewer''.  Outputs are built up compositionally from other outputs and from inputs (the ''controllers''), as described below.

Besides this wiki page, here are more ways to learn about TV:
* Visit the [http://hackage.haskell.org/package/TV Hackage page] for library documentation.
* Install with <tt>cabal install TV</tt>.

As of version 0.2, I have moved the GUI functionality out of TV and into a small new package [[GuiTV]].  I moved it out to eliminate the dependency of core TV on [[Phooey]] and hence on [[wxHaskell]], as the latter can be difficult to install.  The GUI examples below require [[GuiTV]].

GuiTV (better named "wxTV") is bit-rotten.  There is also a very similar [http://hackage.haskell.org/package/GtkTV package to generate Gtk-based GUIs].

I'd love to hear your comments at the [[Talk:TV]] page.

== First Example ==

Here is a tangible reverse function:

<haskell>
reverseT :: CTV (String -> String)
reverseT = tv (oTitle "reverse" defaultOut) reverse
</haskell>

The <hask>tv</hask> function combines an interface and a value.  In this example, the interface is the default for string functions, wrapped with the title "reverse".

TV "interfaces" are more than just GUIs.  Here are two different renderings of <hask>reverseT</hask>.  (User input is shown <tt><b><i>in italics</i></b></tt> in the <hask>runIO</hask> version).

Running:
<blockquote>
{| class="wikitable"
! <hask>runUI reverseT</hask> !! <hask>runIO reverseT</hask> 
|- 
| style="padding:20px;" | [[Image:reverseT.png]]
| style="padding:20px;" |
 *Examples> runIO reverseT
 reverse: <b><i>Hello, reversible world.</i></b>
 .dlrow elbisrever ,olleH
 *Examples> 
|}
</blockquote>

We'll see [[#The_general_story|later]] that "<hask>runUI</hask>" and "<hask>runIO</hask>" are both type-specialized synonyms for a more general function.

== Outputs ==

What I've been calling an "interface" is a value of type <hask>COutput a</hask> for a type <hask>a</hask>.  For instance, for <hask>reverseT</hask>, <hask>a</hask> is <hask>String->String</hask>.  The reason for the <hask>C</hask> prefix is explained below.  At the heart of TV is a small algebra for constructing these outputs.  Weve already seen one output function, <hask>oTitle</hask>.  Another one is <hask>showOut</hask>, which is an output for all <hask>Show</hask> types.  For instance,

<haskell>
total :: Show a => COutput a
total = oTitle "total" showOut
</haskell>

== Inputs and function-valued outputs ==

Just as an output is a way to ''deliver'' (or ''consume'') a value, an "input" is a way to ''obtain'' (or ''produce'') a value.  For example, here are two inputs, each specifying an initial value and a value range, and each given a title.

<haskell>
apples, bananas :: CInput Int
apples  = iTitle "apples"  defaultIn
bananas = iTitle "bananas" defaultIn
</haskell>

Now for the fun part.  Let's combine the <hask>apples</hask> and <hask>bananas</hask> inputs and the <hask>total</hask> output to make a ''function-valued'' output.

<haskell>
shoppingO :: COutput (Int -> Int -> Int)
shoppingO = oTitle "shopping list" $
            oLambda apples (oLambda bananas total)
</haskell>

And a TV:
<haskell>
shopping :: CTV (Int -> Int -> Int)
shopping = tv shoppingO (+)
</haskell>

Running:
<blockquote>
{| class="wikitable"
! <hask>runUI shopping</hask> !! <hask>runIO shopping</hask> 
|- 
| style="padding:20px;" | [[Image:shopping.png]]
| style="padding:20px;" |
 shopping list: apples: <b><i>8</i></b>
 bananas: <b><i>5</i></b>
 total: 13
|}
</blockquote>

== A variation ==

Here is an uncurried variation:

<haskell>
shoppingPr :: CTV ((Int,Int) -> Int)
shoppingPr = tv ( oTitle "shopping list -- uncurried" $ 
                  oLambda (iPair apples bananas) total )
                (uncurry (+))
</haskell>
However, there's a much more elegant formulation, using <hask>uncurryA</hask> and <hask>$$</hask> from [[DeepArrow]]:
<haskell>
shoppingPr = uncurryA $$ shopping
</haskell>

Running:
<blockquote>
{| class="wikitable"
! <hask>runUI shoppingPr</hask> !! <hask>runIO shoppingPr</hask> 
|- 
| style="padding:20px;" | [[Image:shoppingPr.png]]
| style="padding:20px;" |
 shopping list -- uncurried: apples: <b><i>8</i></b>
 bananas: <b><i>5</i></b>
 total: 13
|}
</blockquote>

== The general story ==

TVs, outputs, and inputs are not restricted to GUIs and IO.  In general, they are parameterized by the mechanics of "transmitting values", i.e., delivering ("sinking") output and gathering ("sourcing") input.

<haskell>
data Input  src     a
data Output src snk a
type TV     src snk a
</haskell>

The "sources" will be [[applicative functor]]s (AFs), and the "sinks" will be contravariant functors.

In the examples above, we've used two different mechanisms, namely [[Phooey]]'s <hask>UI</hask> AF and <hask>IO</hask>.  The sinks are counterparts <hask>IU</hask> and <hask>OI</hask>.

The functions <hask>runUI</hask> and <hask>runIO</hask> used in examples above are simply type-specialized synonyms for [http://hackage.haskell.org/package/TV/latest/doc/html/Interface-TV.html#v%3ArunTV <hask>runTV</hask>].
<haskell>
runUI :: TV UI IU a -> IO ()
runUI = runTV

runIO :: TV IO OI a -> IO ()
runIO = runTV
</haskell>

== Common Ins and Outs ==

The examples <hask>reverseT</hask> and <hask>shoppingT</hask> above used not only the generic <hask>Output</hask> and <hask>Input</hask> operations, but also some operations that apply to AFs having a few methods for sourcing and sinking a few common types (strings, readables, showables, and booleans).   The type constructors <hask>CInput</hask>, <hask>COutput</hask>, and <hask>CTV</hask> are universally quantified over sources and sinks having the required methods.

<haskell>
type CInput a = forall src.
  (CommonIns src)                 => Input  src     a
type COutput a = forall src snk.
  (CommonIns src, CommonOuts snk) => Output src snk a
type CTV a = forall src snk.
  (CommonIns src, CommonOuts snk) => TV     src snk a
</haskell>

== Sorting examples ==

Here's a sorting TV (see [http://hackage.haskell.org/packages/archive/TV/latest/doc/html/Interface-TV-Common.html#v:interactLineRS <hask>interactLineRS</hask>]), tested with <hask>runUI</hask>:

<blockquote>
{| class="wikitable"
 | style="padding-right:2em;" |
<haskell>
sortT :: (Read a, Show a, Ord a) => CTV ([a] -> [a])
sortT = tv (oTitle "sort" $ interactLineRS []) sort
</haskell>
|- 
| style="padding:20px;text-align:center;" | [[Image:sortT.png]]
|}
</blockquote>

Note that <hask>sortT</hask> is polymorphic in value, and the type variable <hask>a</hask> as defaulted to <hask>Int</hask>.  You could instead type-annotate its uses, e.g.,

: <hask>runUI (sortT :: CTV ([String] -> [String]))</hask>

== Composition of TVs ==

So far, we done a little composition of interfaces and combined them with values to construct TVs.  Now let's look at composition of TVs.

First, wrap up the <hask>words</hask> and <hask>unwords</hask> functions:

<blockquote>
{| class="wikitable"
 | style="padding-right:2em;" |
<haskell>
wordsT :: CTV (String -> [String]) 
wordsT = tv ( oTitle "function: words" $
                oLambda (iTitle "sentence in" defaultIn)
                        (oTitle "words out"   defaultOut))
              words
</haskell>
|- 
| style="padding:20px;text-align:center;" | [[Image:wordsT.png]]
|}
</blockquote>

<blockquote>
{| class="wikitable"
 | style="padding-right:2em;" |
<haskell>
unwordsT :: CTV ([String] -> String) 
unwordsT = tv ( oTitle "function: unwords" $
                  oLambda (iTitle "words in"     defaultIn)
                          (oTitle "sentence out" defaultOut))
              unwords
</haskell>
|- 
| style="padding:20px;text-align:center;" | [[Image:unwordsT.png]]
|}
</blockquote>

Finally, compose <hask>wordsT</hask>, <hask>unwordsT</hask>, and <hask>sortT</hask>

<haskell>
sortWordsT :: CTV (String -> String)
sortWordsT = wordsT ->| sortT ->| unwordsT
</haskell>

Running:
<blockquote>
{| class="wikitable"
! <hask>runUI sortWordsT</hask> !! <hask>runIO sortWordsT</hask> 
|- 
| style="padding:20px;" | [[Image:sortWordsT.png]]
| style="padding:20px;" |
 sentence in: <b><i>The night Max wore his wolf suit</i></b>
 sentence out: Max The his night suit wolf wore
|}
</blockquote>

The operator "[http://hackage.haskell.org/package/DeepArrow/latest/doc/html/Control-Arrow-DeepArrow.html#v%3A-%3E%7C <hask>->|</hask>]" is part of a general approach to value composition from [[DeepArrow]].

== Transmission-specific interfaces ==

While some interfaces can be implemented for different means of transmission, others are more specialized.

=== GUIs ===

Here are inputs for our shopping example above that specifically work with [[Phooey]]'s UI applicative functor.
<haskell>
applesU, bananasU :: Input UI Int
applesU  = iTitle "apples"  (islider 3 (0,10))
bananasU = iTitle "bananas" (islider 7 (0,10))

shoppingUO :: Output UI (Int -> Int -> Int)
shoppingUO = oTitle "shopping list" $ oLambda applesU (oLambda bananasU total)
</haskell>

We can then make curried and uncurried TVs:
<blockquote>
{| class="wikitable"
! code !! runUI rendering 
|-
| style="padding:20px;" align=right| <hask>tv shoppingUO (+)</hask>
| style="padding:20px;" align="center" | [[Image:shoppingU.png]]
|-
| style="padding:20px;" align=right | <hask>uncurryA $$ tv shoppingUO (+)</hask>
| style="padding:20px;" align="center" | [[Image:shoppingPrU.png]]
|}
</blockquote>

'''Note''': We could define other type classes, besides <hask>CommonInsOuts</hask>.  For instance,  <hask>islider</hask> could be made a method of a <hask>GuiArrow</hask> class, allowing it to be rendered in different ways with different GUI toolkits or even using HTML and Javascript.

=== IO ===

We can use <hask>IO</hask> operations in TV interfaces.  The corresponding sink is <hask>OI</hask>, defined in [[TypeCompose]].  TV provides a few functions in its [http://hackage.haskell.org/package/TV/latest/doc/html/Interface-TV-IO.html <hask>IO</hask> module], including a close counterpart to the standard <hask>interact</hask> function.
<haskell>
interactOut :: Output IO OI (String -> String)
interactOut = oLambda contentsIn stringOut
</haskell>

Assuming we have a file <tt>"test.txt"</tt> containing some lines of text, we can use it to test string transformations.
<haskell>
testO :: Output IO OI (String -> String)
testO = oLambda (fileIn "test.txt") defaultOut
</haskell>

First, let's define higher-order functions that apply another function to the lines or on the words of a string.
<haskell>
onLines, onWords :: ([String] -> [String]) -> (String -> String)
onLines f = unlines . f . lines
onWords f = unwords . f . words
</haskell>
Next, specializations that operate on ''each'' line or word:
<haskell>
perLine,perWord :: (String -> String) -> (String -> String)
perLine f = onLines (map f)
perWord f = onWords (map f)
</haskell>

Some examples:

<blockquote>
{| class="wikitable"
! string function <hask>f</hask> !! <hask>runIO (tv test0 f)</hask>
|-
| style="padding:20px;" align=right| <hask>id</hask>
| style="padding:20px;" align="center" |
 To see a World in a Grain of Sand
 And a Heaven in a Wild Flower, 
 Hold Infinity in the palm of your hand
 And Eternity in an hour.
     - William Blake
|-
| style="padding:20px;" align=right| <hask>reverse</hask>
| style="padding:20px;" align="center" |

 ekalB mailliW -    
 .ruoh na ni ytinretE dnA
 dnah ruoy fo mlap eht ni ytinifnI dloH
  ,rewolF dliW a ni nevaeH a dnA
 dnaS fo niarG a ni dlroW a ees oT
|-
| style="padding:20px;" align=right| <hask>onLines reverse</hask>
| style="padding:20px;" align="center" |
     - William Blake
 And Eternity in an hour.
 Hold Infinity in the palm of your hand
 And a Heaven in a Wild Flower, 
 To see a World in a Grain of Sand
|-
| style="padding:20px;" align=right| <hask>perLine reverse</hask>
| style="padding:20px;" align="center" |
 dnaS fo niarG a ni dlroW a ees oT
  ,rewolF dliW a ni nevaeH a dnA
 dnah ruoy fo mlap eht ni ytinifnI dloH
 .ruoh na ni ytinretE dnA
 ekalB mailliW -    
|-
| style="padding:20px;" align=right| <hask>perLine (perWord reverse)</hask>
| style="padding:20px;" align="center" |
 oT ees a dlroW ni a niarG fo dnaS
 dnA a nevaeH ni a dliW ,rewolF
 dloH ytinifnI ni eht mlap fo ruoy dnah
 dnA ytinretE ni na .ruoh
 - mailliW ekalB
|}
</blockquote>

There are more examples [http://code.haskell.org/~conal/code/TV/src/Examples.hs in the TV repository] and in the [http://code.haskell.org/~conal/code/GuiTV/src/Examples.hs in the GuiTV repository].  See also "[http://journal.conal.net/#%5B%5Bseparating%20IO%20from%20logic%20--%20example%5D%5D separating IO from logic -- example]".