thaskell-cs.tex

%% thaskell-cs.tex
%
% Copyright 2015  Rudy Matela
%
% This text is available under (at your option):
%   * Creative Commons Attribution-ShareAlike 3.0 Licence
%   * GNU Free Documentation License version 1.3 or Later
%

\documentclass{refcard}
\usepackage[T1]{fontenc}
\usepackage{rotating}
\usepackage{amssymb}

\renewcommand{\familydefault}{\sfdefault}
\newcommand{\la}{\textbackslash}
\newcommand{\F}{\I{f}}
\newcommand{\X}{\I{x}}
\newcommand{\Y}{\I{y}}
\newcommand{\Z}{\I{z}}
\newcommand{\W}{\I{w}}
\newcommand{\XS}{\I{xs}}

\newcommand{\mtype}[1]{\multicolumn{2}{@{}C}{#1}}
\newcommand{\longtype}[1]{\multicolumn{3}{@{}C}{#1}}
\newcommand{\Longtype}[1]{\multicolumn{4}{@{}C}{#1}}
\newcommand{\longcall}[1]{\multicolumn{3}{@{}R@{\s$\equiv$\s}}{#1}}



\title{Template Haskell Cheat Sheet}

\cright{
	Copyright 2015, Rudy Matela --
	Compiled on \today{} \\
	Upstream: \texttt{https://github.com/rudymatela/concise-cheat-sheets}
}{
	This text is available under
	the Creative Commons Attribution-ShareAlike 3.0 Licence, \\
	\textbf{or} (at your option), the GNU Free Documentation License version 1.3 or Later.
}
\version[~\\]{0.1}


\begin{document}

\maketitle

% This section might eventually disappear
% if we get enough info to fill two pages.
\section{Notes}

This documents Template Haskell 2.10.0.0 as provided in GHC 7.10.2.
Usually, there are minor differences between versions.

While using Template Haskell, GHC will bark at you,
	saying you cannot splice this here and there,
	or that it needs a \C{SomethingQ} instead of a \C{[Something]}.
Take a deep breath, if you keep fighting the compiler,
	things will eventually typecheck.  Tips:
\begin{itemize}
\item
Some things aren't really allowed in TH:
	when it is not possible to splice,
	you should manipulate TH data constructors directly.

\item
Take time to think wether you need a
	\C{Name}, \C{Type} or \C{TypeQ}
	-- three different things
	that might \emph{refer} to a single thing.

\item
You should be familiar with Haskell Monads.
\end{itemize}

\section{Pre-requisites}

\subsubsection{Activating}

\begin{ldesc}
	\li[command line] \$ ghc[i] -XTemplateHaskell
	\li[GHCi]         > :set -XTemplateHaskell
	\li[pragma]       \{-\# LANGUAGE TemplateHaskell \#-\}
\end{ldesc}


\subsubsection{Imports}

\begin{ldesc}
	\li[most functions]   import Language.Haskell.TH
	\li[other (optional)] import Language.Haskell.TH.Lib \li
	                      import Language.Haskell.TH.Ppr \li
	                      import Language.Haskell.TH.PprLib \li
	                      import Language.Haskell.TH.Quote \li
	                      import Language.Haskell.TH.Syntax
\end{ldesc} \\
NOTE: You probably just need the first import.


\section{Types, Quasi-quoting and Splicing}

\begin{tabularlc}{lCCCC}
	\li         \N{Type}&\N{Synonym}&\N{Quoting} &\N{Splicing}
	\li[Expression]   Q Exp   & ExpQ  & [|...|]  & \$(...)
	\li[Type]         Q Type  & TypeQ & [t|...|] & \$(...)
	\li[Pattern]      Q Pat   & PatQ  & [p|...|] & \$(...)
	\li[Declarations] Q [Dec] & DecsQ & [d|...|] & ...~\N{(top level)}
\end{tabularlc} \\ \indent
          i.e.:  \C{[d|~...~|]~::~DecsQ} \\ \indent
\hphantom{i.e.:} \C{[p|~...~|]~::~Q Pat}

\vspace{3ex}
Brackets can be ommited when splicing an atomic expression.\\
Assume:
\begin{verbatim}
        one = litE (IntegerL 1)
\end{verbatim}
Then:
\begin{verbatim}
        $one
\end{verbatim}

\subsubsection{Identities}

\begin{tabularlc}{R@{\C{~~$\equiv$~~}}C}
\$( [| \I{haskell\_expression} |] ) & \I{haskell\_expression} \\
\$( [t| \I{haskell\_type} |] )      & \I{haskell\_type} \\
{}[| \$( \I{qexp} ) |]                & \I{qexp} \\
{}[t| \$( \I{qtype} ) |]              & \I{qtype} \\
\end{tabularlc}

\section{Printing and Pretty-printing}

\begin{ldesc}
	\li[print valid haskell] putStrLn \$(stringE . pprint =<{<} \I{qq})
	\li[show constructors]   putStrLn \$(stringE . show =<{<} \I{qq})
\end{ldesc} \\[1ex]

For \emph{simple expressions} (e.g.: that do not reify) on GHCi: \\
\begin{ldesc}
	\li[unreliable -- show constructors]  runQ \I{qexp}
\end{ldesc}


\section{Constructors names}

\subsubsection{Trailing capital letter}

For all constructors of types
	\I{Exp}, \I{Type}, \I{Pat} and \I{Dec},
the trailing letter indicates the type. \\[1ex]
\begin{ldesc}
	\li[Expression constructor]  \I{FooE}
	\li[Type constructor]        \I{FooT}
	\li[Pattern constructor]     \I{FooP}
	\li[Declaration constructor] \I{FooD}
\end{ldesc} \\[2ex]
Examples: \\[1ex]
\begin{ldesc}
	\li[Type application]                   AppT \I{type1} \I{type2}
	\li[Function (expression) application]  AppE \I{expr1} \I{expr2}
	\li[Expression variable]                VarE \I{name}
	\li[Pattern variable]                   VarP \I{name}
\end{ldesc}


\subsubsection{Captalization -- \C{SomeX} and \C{someX}}

For all constructors of types
	\I{Exp}, \I{Type} and \I{Pat}
there are equivalent lowercase versions that return
	\I{ExpQ}, \I{TypeQ} and \I{PatQ}.
Examples: \\[1ex]
\begin{tabular}{C@{\C{$~\equiv~ $}}C}
	return (VarE \I{name}) & varE \I{name} \\
	return (ConE \I{name}) & conE \I{name} \\
%	return (LitE \I{lit})  & litE \I{lit} \\
	return (AppE \I{expr1} \I{expr2}) & appE \I{expr1} \I{expr2} \\
	return (AppT \I{type1} \I{type2}) & appT \I{type1} \I{type2} \\
\end{tabular}


\newpage
\section{Conversions: Haskell $\Leftrightarrow$ Explicit constructors}

The conversion \textbf{from Haskell} almost always return an \textbf{invalid}
expression. To copy-paste it, you have to introduce \C{mkName}, \C{'} and
\C{'{'}} where appropriate.

\noindent
The conversion \textbf{to Haskell} almost always return \textbf{valid Haskell.}
You can safely copy-paste the Haskell code.


\subsubsection{Haskell $\Rightarrow$ explicit constructors}

\begin{verbatim}
> putStrLn $(stringE . show =<< [d| inc :: Int -> Int
>                                   inc x = x + 1 |])
[ SigD inc_1 (AppT (AppT ArrowT (ConT GHC.Types.Int))
                   (ConT GHC.Types.Int))
, FunD inc_1 [ Clause [VarP x_2]
                      (NormalB (AppE (AppE (VarE GHC.Num.+)
                                           (VarE x_2))
                                     (LitE (IntegerL 1))))
                      []
             ]
]
\end{verbatim}

\subsubsection{Explicit constructors $\Rightarrow$ Haskell}
\begin{verbatim}
> putStrLn $(stringE . pprint $
>              [ ValD (VarP (mkName "inc"))
>                     (NormalB (AppE (VarE '(+))
>                              (LitE (IntegerL 1))))
>                     [] ])
inc = (GHC.Num.+) 1
\end{verbatim}


\section{Impossible splices}

\begin{ldesc}
\li[Instance \I{context}s]
instance \$\I{context}~=>~\I{Cl} \I{Ty} \li
~~where \I{function} = \I{expr}
\lI[Type sign. declaration \I{name}s]
\$\I{name} ::~\I{Ty}
\lI[and many others cases...]
\end{ldesc} \\[1ex]
Those might become possible in future versions of TH.

\end{document}