templates_intro.tex

\newpage
\phantomsection
\part*{Introduction}\label{intro} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\addcontentsline{toc}{part}{Introduction}

Templates are a central feature of D, giving you powerful compile-time code generation abilities that'll make your code cleaner, more flexible and even more efficient. They are used everywhere in \href{http://www.dlang.org/phobos/}{Phobos}\index{Phobos} --- D standard library --- and therefore any D user should know about them. But, based on C++\index{C++}'s templates as they are, D templates can be a bit daunting at first. The \href{http://www.dlang.org}{D Programming Language} website's \href{http://www.dlang.org/template.html}{documentation} is a good start, though its description of templates is spread among many different files and (as it's a language reference) its material doesn't so much \emph{teach} you how to use templates as \emph{show} you their syntax and semantics.

This document aims to be a kind of tutorial on D templates, to show the beginning D coder what can be achieved with them. When I was doing C++\index{C++}, I remember \emph{never} using templates for more than \emph{containers-of-T} stuff, and considered Boost-level\footnote{ The \href{http://www.boost.org}{Boost}\index{Boost} C++ library collection makes heavy use of templates.} metaprogramming the kind of code I could never understand, never mind produce. Well, D's sane syntax for templates and nifty features such as \D{static if}, \D{alias} or tuples cured me of that impression. I hope this document will help you, too.

\section*{What's in This Document}\label{content}
\addcontentsline{toc}{section}{What's in This Document}

\autoref{basics} deals with the very basics: how to declare and instantiate a template, the standard `building blocks' you'll use in almost all your templates, along with function (\ref{functiontemplates}), struct (\ref{structtemplates}) and class (\ref{classtemplates}) templates. Throughout the text, examples will present applications of these concepts. 

\autoref{advanced} is about more advanced topics a D template user will probably use, but not on a daily basis, like template constraints (\ref{constraints}), mixin templates (\ref{mixintemplates}) or operator overloading (\ref{operatoroverloading}). 

\autoref{around} presents other meta\-pro\-gram\-ming tools: string mixins (\ref{stringmixins}), compile-time function evaluation (\ref{ctfe}), and \D{\_\_traits} (\ref{traits}). These are seen from a \mbox{template-y} point of view: how they can interact with templates and what you can build with them in conjunction with templates.

\autoref{examples} presents more developed examples of what can be done with templates, based on real needs I had at some time and that could be fulfilled with templates.

Finally, an appendix (\autoref{isexpression}) on the ubiquitous \D{is} expression  and another (\ref{resources}) giving resources and further reading advice complete this document.

\section*{Conventions}\label{conventions}
\addcontentsline{toc}{section}{Conventions}

To make this document more easily readable, I'll use standard coding books conventions, by highlighting parts of the text. Mainly, in this doc:

\begin{itemize}
\item D keywords will be marked like this: \D{int}, \D{static if}, \D{\_\_traits}.
\item Symbols and names used in code samples and cited in the text will be written like this: \DD{myFunc}, \DD{flatten}.
\item internal links will be in red, like this (\ref{basics}).
\item external links will be in blue, like \href{http://www.dlang.org}{this}.
\item Syntax-highlighted code samples are shown like this:
\end{itemize}

\begin{ndcode}
/**
 * This is a doc comment.
 */
module intro;

import std.stdio;

void main()
{
    int times = 10;
    // This is a comment
    foreach(i; 0..times) 
        writeln("Hello, Word!");
}
\end{ndcode}

Numbered lines will be used only when necessary. The code lines may be wider than the main text, but that's to get about 80-chars-long lines. For the time being I'll just respect the standard \LaTeX\ text width, unless many people complain about it.

For those of you interested by \LaTeX, this document uses the \href{http://code.google.com/p/minted/}{minted}\index{minted (LaTex package)@\DD{minted} (\LaTeX\ package)} package for the code samples. 

I will sometimes make a little explanatory detour, discussing a small piece of info too small to be in its own section but of interest to the reader nonetheless. These will be marked so:

\aparte{Semi-Literate Programming}
{Most code samples presented in this document will compile with a reasonably recent D compiler. In the \DD{utils} directory, there is a small D script called \DD{codesamples.d} that extracts code samples from the \LaTeX\ files.

Samples with a \D{module }\DD{name;} declaration will be extracted, a file called \DD{name.d} will be created and compiled (possibly with a stub \DD{main()} if none exists). The previous code sample creates a file called \DD{intro.d} and so on. The compilation results are put in a file called \DD{result.txt}. Samples that depend on other samples just import them (yeah for D modularity, no need for specific mark-up to weave code together). Samples with a name ending in \DD{\_error} will \emph{not} compile, as expected: they are there to show errors, mistakes and gotchas. Anonymous samples are not extracted: I use them to show small snippets not intended to stand by themselves, or just to show D-ish pseudocode.

All in all, you can see this entire document as a gigantic D package, describing hundreds of small modules.}

Finally, some sections in this doc are not finished yet. The sections I consider unfinished will begin with a friendly red frame:

\unfinished{Hey, now I've added a Thanks section. But as long as I'm adding new parts in the document, new appendices, and new section, this intro will not be finished.}

I probably forgot some `unfinished' tags, do not hesitate to tell me so.

\section*{How to Get This Document}\label{howtoget}
\addcontentsline{toc}{section}{How to Get This Document}

This doc is just a bunch of \LaTeX documents \href{http://github.com/PhilippeSigaud/D-templates-tutorial}{hosted on GitHub}. Don't hesitate to fork it or (even better for me) to make pull requests! For those of you reading this on paper, the address is:

\vspace{8pt}
\url{http://github.com/PhilippeSigaud/D-templates-tutorial}

\section*{Thanks}\label{thanks}
\addcontentsline{toc}{section}{Thanks}

As soon as I publicly released this document, D community members gave me help, suggestions, corrections, and code samples. This is cool to see a D network emerge and people participating in common projects. The following people helped me:

Andrej Mitrovic, Justin Whear, Zachary Lund, Jacob Carlborg, Timon Gehr, Simen Kj\ae r\r{a}s, Andrei Alexandrescu, Bj\"{o}rn Lietz-Spendig.

\vspace{8pt}
Thanks guys!