
\documentclass{article}

%include polycode.fmt

\usepackage[margin=1.7in]{geometry}
\usepackage{xcolor}
\usepackage{listings}
\usepackage{ghci}

\usepackage{tabularx}

\usepackage{hyperref}

\usepackage[most]{tcolorbox}
\tcbuselibrary{listingsutf8}

\newtcolorbox{latexbox}{
  enhanced,
  colback=white,
  colframe=black,
  fonttitle=\bfseries,
  listing only,
  listing options={
    basicstyle=\ttfamily\small,
    breaklines=true,
    columns=fullflexible,
    escapeinside={(*@}{@*)},
    language=[LaTeX]TeX
  },
  sharp corners,
  boxrule=0.8pt,
  breakable
}

\lstset{%
  language=[AlLaTeX]TeX,
  alsolanguage=MetaPost,
  texcsstyle=\color{blue},
  moretexcs={hask },
  basicstyle=\ttfamily,
    alsoother={0123456789$_$},%
}

\newtcolorbox{warningbox}{
  colback=yellow!10,
  colframe=orange!40,
  coltitle=black,
  title=\faExclamationTriangle\quad Warning,
  fonttitle=\bfseries,
  sharp corners,
  boxrule=1pt,
  left=1em,
  right=1em,
  top=0.8em,
  bottom=0.8em,
  breakable
}


\newtcolorbox{infobox}{
  colback=blue!10,
  colframe=blue!80!black,
  coltitle=black,
  title=\faInfoCircle\quad Information,
  fonttitle=\bfseries,
  sharp corners,
  boxrule=1pt,
  left=1em,
  right=1em,
  top=0.8em,
  bottom=0.8em,
  breakable
}

\newtcolorbox{tipbox}{
  colback=green!7,
  colframe=green!80!black!40,
  coltitle=black,
  title=\faLightbulbO\quad Tip,
  fonttitle=\bfseries,
  sharp corners,
  boxrule=1pt,
  left=1em,
  right=1em,
  top=0.8em,
  bottom=0.8em,
  breakable
}


\usepackage{fontawesome} % for \faExclamationTriangle icon

\def\version{v0.1}

\date{\today \\[0.5em]\normalsize \texttt{\version}}
%format ghci4luatex = "\text{GHCi for Lua\TeX}"
%format luatex = "\text{Lua\TeX}"

\title{|ghci4luatex| \\ \vspace{0.4em}
  \large A persistent ghci session in |luatex|}

\author{Alice Rixte}

\begin{document}

\maketitle
\tableofcontents

\newpage

\section{Introduction}


|ghci4luatex| provides a persistent GHCi session within a \LaTeX\ document. Using the \texttt{ghci} package via \texttt{\textbackslash \tex {\color{blue} usepackage}\{ghci\}}, it mainly provides the \texttt{ghci} environment and the \texttt{hask} command which can be used as follows:

\begin{latexbox}
  \begin{lstlisting}{language=[AlLaTeX]TeX}
\begin{ghci}
x :: Int
x = 4

y :: Int
y = 5
\end{ghci}

The sum of $x$ and $y$ when $x = \hask{x}$
and $y = \hask{y}$ is $\hask{x + y}$.

\end{lstlisting}
\end{latexbox}

\section{Getting started}

In order to execute the Haskell code, the \texttt{ghci4luatex} server must be running. If you are concerned with security issues, you are encouraged to verify the source code at \href{https://github.com/AliceRixte/ghci4luatex/}{github.com/AliceRixte/ghci4luatex/}. In particular, you can make sure that

\begin{itemize}
  \item  the \texttt{ghci.sty} package can only connect to the local address \texttt{127.0.0.1} and will not attempt to connect to any external service
  \item the \texttt{ghci4luatex} server only processes the commands sent by \texttt{ghci.sty}
\end{itemize}

\subsection{Installing the \texttt{ghci4luatex} server}

You can install \texttt{ghci4luatex} either using Cabal, Stack, or directly from source. In all cases, you must have Haskell installed as well as cabal or stack.

To check that \texttt{ghci4luatex} is properly installed, run

\begin{verbatim}
  ghci4luatex --version
\end{verbatim}
Modulo the version, this should produce de following output \texttt{ghci4luatex v0.1, (C) Alice Rixte}

\paragraph{Using \href{https://www.haskell.org/cabal/}{cabal}}

\begin{verbatim}
  cabal install ghci4luatex
\end{verbatim}

\paragraph{Using \href{https://docs.haskellstack.org/en/stable/}{stack}}

\begin{verbatim}
  stack install ghci4luatex
\end{verbatim}

\paragraph{From  \href{https://github.com/AliceRixte/ghci4luatex/}{source}}

\begin{verbatim}
  git clone https://github.com/AliceRixte/ghci4luatex.git
  cd ghci4luatex
  stack install
\end{verbatim}

\paragraph{Verifying the installation was successful}
To check that \texttt{ghci4luatex} is properly installed, run

\begin{verbatim}
  ghci4luatex --version
\end{verbatim}
Modulo the version, this should produce the following output

\begin{verbatim}
  ghci4luatex v0.1, (C) Alice Rixte
\end{verbatim}
\subsection{Installing the \texttt{ghci} package}

To install the \texttt{ghci} package for Lua\TeX, you can use either your package manager or install it from source.

\paragraph{Using TeX Live (not yet supported).}
\begin{verbatim}
  tlmgr install ghci
\end{verbatim}
\paragraph{Using MiKTeX (not yet supported). }
\begin{verbatim}
  mpm --admin --install=ghci
\end{verbatim}
\paragraph{From source}
Copy both \texttt{ghci.sty} and \texttt{dkjson.lua} inside the root directory of the Latex file you want to use \texttt{ghci4luatex} in.

Both these files can be found at the root of the \texttt{ghci4luatex} repository: \href{https://github.com/AliceRixte/ghci4luatex/}{github.com/AliceRixte/ghci4luatex/}

\subsection{Running the \texttt{ghci4luatex} server}

Once both \texttt{ghci4luatex} and the \texttt{ghci} package are installed, simply run the following in the same directory you will use LuaTeX:

\begin{verbatim}
  ghci4luatex
\end{verbatim}

The server should remain active while you are working on your file. You should not close it between consecutive compilations as it performs memoization to make the compilation faster.

\begin{tipbox}
Always have a terminal with \texttt{ghci4luatex} running, it will give you clearer error messages from GHCi, and will show you which Haskell expressions are recomputed and which are not.
\end{tipbox}


Once \texttt{ghci4luatex} is running, you can execute LuaTeX with

\begin{verbatim}
  lualatex -shell-escape myFile.tex
\end{verbatim}

or use \texttt{latexmk} using the luatex option:

\begin{verbatim}
  latexmk -lualatex -shell-escape myFile.tex
\end{verbatim}

\begin{warningbox}
  Without the \texttt{-shell-escape} option, the compilation will fail, complaining about not finding the \texttt{'socket'} file.
\end{warningbox}

\section{The \texttt{ghci4luatex} server}

The  \texttt{ghci4luatex} provides a few options that can be listed by invoking \texttt{ghci4luatex --help}. In particular:

\begin{description}
  \item[--command] Allows using cabal or stack to run GHCi. For instance, you can run \begin{itemize}
    \item \texttt{ghci4luatex --command="cabal repl"}
    \item \texttt{ghci4luatex --command="stack ghci"}
  \end{itemize}
  \item[--verbose] This will show which commands were memoized.
  \item[--quiet] Except for errors due to the server (not GHCi error dumps), \texttt{ghci4luatex} will be completely silent.
  \item[--host and --port] Change the host address and port. Notice that this requires you to also change the host and port in \texttt{ghci.sty}. Using these options is discouraged.
\end{description}


\section{The \texttt{ghci.sty} package}

The \texttt{ghci} package can both execute Haskell code snippets and GHCi commands thanks to the \texttt{ghci} environment and print the result to LaTeX with the \texttt{\textbackslash hask} command.

\subsection{Running Haskell code: the \texttt{ghci} environment}

To execute some Haskell code without printing anything to LaTeX, you can use the \texttt{ghci} environment. \texttt{ghci4luatex} will always surround the code between \texttt{\textbackslash \tex {\color{blue} begin}\{ghci\}} and  \texttt{\textbackslash \tex {\color{blue} end}\{ghci\}} by \texttt{:\{} and \texttt{:\}} so that GHCi knows this is a multiple line command.

\begin{latexbox}
\begin{lstlisting}{language=[AlLaTeX]TeX}
\begin{ghci}
x :: Int
x = 4

y :: Int
y = 5
\end{ghci}
\end{lstlisting}
\end{latexbox}

\paragraph{Using GHCi commands} You can also send GHCi commands (i.e. starting with `:`), for instance to load extensions:

  \begin{lstlisting}{language=[AlLaTeX]TeX}
  \begin{ghci}
  :set -XOverloadedStrings
  \end{ghci}
  \end{lstlisting}

\begin{warningbox}
  Since the code is always enclosed within \texttt{:\{} and \texttt{:\}}, this means you can only give one GHCi command (i.e. starting with `:`) at a time. The following will fail with the message \texttt{unrecognised flag: :set}
  \begin{lstlisting}{language=[AlLaTeX]TeX}
  \begin{ghci}
  :set -XOverloadedStrings
  :set -XOverloadedLists
  \end{ghci}
  \end{lstlisting}
\end{warningbox}


\paragraph{Importing modules}
You can use the \texttt{ghci} environment to import any module you need, it will be available throughout the whole file.

\begin{lstlisting}{language=[AlLaTeX]TeX}
\begin{ghci}
import Data.Functor
import Control.Monad
\end{ghci}
\end{lstlisting}

If you need to import modules on Hackage, you can use \texttt{:set -package some-package}. To load your own modules, use \texttt{:l}.

\begin{tipbox}
  You can directly load all the modules of your own package as well as all of the dependencies listed in your \texttt{.cabal} (or \texttt{package.yaml} file) by running \texttt{ghci4luatex --command="cabal repl"} or \texttt{ghci4luatex --command="stack ghci"}.
\end{tipbox}

\subsection{Printing the result: the \texttt{hask} command}

You can use Haskell to output LaTeX code. For instance, \texttt{\$\textbackslash \tex {\color{blue} hask}\{1+2\}\$} will print $\hask{1 + 2}$.


The result printed by GHCi can also be  LaTeX expressions. For instance,

\begin{lstlisting}{language=[AlLaTeX]TeX}
  \hask{putStrLn "\\emph{I was written by GHCi}"}.
\end{lstlisting}
\noindent
will produce \hask{putStrLn "\\emph{I was written by GHCi}"}.



\subsection{Advanced usage: managing memoization}

To reduce the compilation time of LuaTeX, the result of the execution of Haskell code snippets is stored in the server in order to avoid recomputing them. This is called \emph{memoization}.

You can see this at work in the output of the \texttt{ghci4luatex} server: if you modify your LaTeX document without changing any of the commands, the server will only print

\begin{lstlisting}{language=[AlLaTeX]TeX}
  --- New session : "main"---
\end{lstlisting}

\begin{tipbox}
  To see which results are memoized and which are recomputed, you can use the \texttt{--verbose} option when running \texttt{ghci4luatex}.
\end{tipbox}


If you modify one of the Haskell snippets, \texttt{ghci4luatex} will have to recompute all of the snippets that appear after the one you modified.

The reason for this is that if you declare a variable, for instance by writing \texttt{x = 4}, and you then modify it to \texttt{x = 5}, all the subsequent code that uses \texttt{x} has to be updated, and therefore recomputed by \texttt{ghci4luatex}.

\medskip

\paragraph{Using \texttt{\textbackslash ghcisession}}
When dealing with big documents that contain a lot of Haskell code that might generate some figures, it can become painfully slow to recompile a document when changing one of the first code snippets that appear in the document.

For this reason, you can tell \texttt{ghci4luatex} to create a new session, by using the command

\begin{lstlisting}{language=[AlLaTeX]TeX}
\ghcisession{mySession}
\end{lstlisting}

This way, if you modify any of the code snippets before you started \texttt{mySession}, the server will not recompile the code snippets that appear \emph{after} \texttt{\textbackslash ghcisession}

\begin{warningbox}
  The \texttt{ghci4luatex} server actually \emph{does not} spawn a new GHCi process for each new session.

  Instead, it only affects the memoization and there is actually only one GHCi process. This means that if you declare a variable \texttt{x = 4} then declare a new session, this variable will still be in the session scope.
\end{warningbox}

\paragraph{Using \texttt{\textbackslash ghcicontinue}} If you want to continue a previously defined session, for instance the default session \texttt{"main"} you can use

\begin{lstlisting}{language=[AlLaTeX]TeX}
\ghcicontinue{main}
\end{lstlisting}

Notice that this only affects memoization and does not actually switch between different GHCi processes.

\begin{tipbox}
  If you want to make sure to recompile all Haskell code of your document, simply kill \texttt{ghci4luatex} and start a new one.
\end{tipbox}


\section{Usage with Haskell libraries}

Any Haskell library can be used in conjunction with \texttt{ghci4luatex}. Here, we present only a selection along with common usage examples. Feel free to add your own suggestions by opening a pull request \href{https://github.com/AliceRixte/ghci4luatex/}{github.com/AliceRixte/ghci4luatex/}.


Usage for all these libraries can be found in \texttt{examples/main.tex} at the \texttt{ghci4luatex} repository.

\subsection{\href{https://hackage.haskell.org/package/lhs2tex}{lhs2TeX} and \href{https://daniel-diaz.github.io/projects/haskintex/}{HaskinTeX}}

Any preprocessor can be used in conjunction with \texttt{ghci4luatex}, since it is a proper LaTeX package and not a preprocessor itself.

Simply run the preprocessor and use \texttt{ghci4luatex} as usual.

\subsection{\href{https://hackage.haskell.org/package/HaTeX}{HaTeX}}

You can use HaTeX to generate some LaTeX code. To use it in conjunction with \texttt{ghci4luatex}, you need to print the latex code in GHCi.

A simple way to do so is to write the following:

\begin{latexbox}
  \begin{lstlisting}{language=[AlLaTeX]TeX}
\begin{ghci}
:set -XOverloadedStrings
\end{ghci}

\begin{ghci}
import Text.LaTeX

printTex = putStrLn . prettyLateX
\end{ghci}
\end{lstlisting}
\end{latexbox}

You can then use the \texttt{printTex} function with the \texttt{\textbackslash hask} command:

\begin{lstlisting}{language=[AlLaTeX]TeX}
\hask{printTex (section "A section using HaTeX")}
\end{lstlisting}

\subsection{\href{https://diagrams.github.io/}{Diagrams}}

Diagrams is a domain-specific language for drawing vector graphics. It already has a dedicated LaTeX package, \href{https://archives.haskell.org/projects.haskell.org/diagrams/doc/latex.html}{diagrams-latex} you should definitely consider using. Still, \texttt{ghci4luatex} has some advantage over \texttt{diagrams-latex}, mainly the persistency of the GHCi session. Here is a complete example with the \texttt{svg} package:

\begin{latexbox}
  \begin{lstlisting}{language=[AlLaTeX]TeX}
\begin{ghci}
{-# LANGUAGE NoMonomorphismRestriction #-}
{-# LANGUAGE FlexibleContexts          #-}
{-# LANGUAGE TypeFamilies              #-}

import Diagrams.Prelude hiding (section)
import Diagrams.Backend.SVG

myDia = circle 1 # fc green
\end{ghci}

\begin{ghci}
  renderSVG "myDia.svg" (dims2D 400 300) myDia
\end{ghci}

\begin{figure}[h]
  \centering
  \includesvg[width=0.2\textwidth]{myDia}
  \caption{A circle using Diagrams}
\end{figure}

\end{lstlisting}
\end{latexbox}



\end{document}
