%% You can build this document by:
%% 1) lhs2TeX -Pc:\ghc\hp10100\data\lhs2tex-1.15;. -o Examples.tex Examples.lhs
%% 2) pdflatex Examples.tex

\documentclass[letterpaper,final,10pt]{paper}
\setlength{\topmargin}{-1.45cm}
\setlength{\topskip}{0.75cm}     % between header and text
\setlength{\textheight}{23cm}    % height of main text
\setlength{\textwidth}{15cm}     % width of text
\setlength{\oddsidemargin}{1cm}  % odd page left margin
\setlength{\evensidemargin}{1cm} % even page left margin
\usepackage[utf8,latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{zefonts}  %%depends on your installation.
\usepackage{graphics,fancyvrb}
\usepackage[spanish]{babel}
\inputencoding{utf8}
%include polycode.fmt
\fvset{frame=single,samepage=true,fontsize=\normalsize}


\markboth{Leonel Fonseca}{Tránsito Abierto library Version 0.1}
\title{Using the Tránsito Abierto library \\
       \small {Document version 0.1.0. September 16, 2010.}}
\author{Leonel Fonseca \\
        \small Computer Sciences student, ITCR, Costa Rica.}
\pagestyle{myheadings}
\thispagestyle{empty}
\begin{document}
\maketitle

\section{Queries as seeds}

%include ./RCSdef.lhs


\section{Growing the seeds or using AST builders of queries}

%include ./Ex01.lhs


\bigskip


\section{What is generated}

As you are about to see in the following output (edited for the sake of space) that shows the dump of the splicing during the compilation process, the Tránsito Abierto library's code generator reused the names of the table's columns. Whenever clash name arises, there is the possibility of using the prefix or suffix parameters when calling the ``empalmar'' function.


\bigskip


Another thing the code generator does when prepares the definition of the ``qTwoColumns'' table is for nullable columns of type \textit{X}, yield a \textit{Maybe X} and for non nullable columns yield the equivalent type without wrapping it into a \textit{Maybe}. 

\bigskip

What are the meaning of the names below? ``ite'' stands for the iteratee function, ``gR'' for ``getResults'', ``pS'' for ``preparedStatement'' and ``xQ'' for ``executeQuery''. Nevertheless, these names are local definitions and are unknown to the rest of the program.

\pagebreak

You now actually see, how much boilerplate is generated by the Tránsito Abierto library.

\begin{Verbatim}[fontsize=\small]
Ex01.lhs:1:0:
 Ex01.lhs:1:0: Splicing declarations
    empalmar "abel" "cain" "barva" Nothing rcs01
  ======>
    Ex01.lhs:26:0-43
    data QTwoColumns
        = QTwoColumns {name :: Maybe String, value :: Maybe Int}
        deriving (Show, Read, Eq, Ord, Typeable)
    qTwoColumns bnds
        = (concatM xQ bnds `exnAt` "qTwoColumns: ")
        where
            ite a11 a12 a13 = result' ((a11, a12) GHC.Types.: a13)
            gR gRbnds
                 = Control.Monad.liftM
                     (revertir (\ (a21, a22) -> QTwoColumns a21 a22))
                     (doQuery gRbnds ite GHC.Types.[])
            pS = (prepareQuery
                $ sql
                    "select\n    *\n    /* TA Select */\nfrom\n\
                    \    twoColumns\norder by\n    value")
            xQ xQbnds
                 = withPreparedStatement
                     pS (\ boundSt -> withBoundStatement boundSt xQbnds gR)
\end{Verbatim}

\bigskip

\section{The result of executing the first example}


This is the ouput that results from executing the first example.
 
\begin{Verbatim}[fontsize=\small]
QTwoColumns {name = Just "1", value = Just 1}
QTwoColumns {name = Just "2", value = Just 2}
QTwoColumns {name = Just "3", value = Just 3}
QTwoColumns {name = Just "4", value = Just 4}
QTwoColumns {name = Just "5", value = Just 5}
QTwoColumns {name = Just "6", value = Just 6}
QTwoColumns {name = Just "7", value = Just 7}
QTwoColumns {name = Just "8", value = Just 8}
QTwoColumns {name = Just "9", value = Just 9}
QTwoColumns {name = Just "10", value = Just 10}
QTwoColumns {name = Just "11", value = Just 11}
QTwoColumns {name = Just "12", value = Just 12}
QTwoColumns {name = Just "13", value = Just 13}
QTwoColumns {name = Just "14", value = Just 14}
QTwoColumns {name = Just "15", value = Just 15}
QTwoColumns {name = Just "16", value = Just 16}
QTwoColumns {name = Just "17", value = Just 17}
QTwoColumns {name = Just "18", value = Just 18}
QTwoColumns {name = Just "19", value = Just 19}
QTwoColumns {name = Just "20", value = Just 20}
\end{Verbatim}

\bigskip

\section{Reusing seeds for program safety}

%include ./Ex02.lhs

\section{Testing what we claim}

\medskip

Let us test what we claim! First we compile and execute Ex02. It should run fine. Then, let us alter the table by adding an extra column that the compiled program would not be prepared to handle:

\medskip

\begin{Verbatim}

SQL> alter table twocolumns add (c3 varchar2(1));

\end{Verbatim}

\medskip

After that, we execute again Ex02, which handles the failure:

\begin{Verbatim}

Error: The database environment has changed!
 It doesn't match the enviroment this program expects.
 As a measure to avoid further errors, this program will finish now.

\end{Verbatim}

\medskip


\section{The two columns table}

The table used as target in this examples was created with this SQL script:

\VerbatimInput{make_twoColumns.sql}


\end{document}