path: root/Master/texmf-dist/doc/latex/algpseudocodex/documentation.tex

%% documentation.tex
%% Copyright 2020 Christian Matt
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Christian Matt.
%
% This work consists of the files algpseudocodex.sty and documentation.tex.

\documentclass[11pt,a4paper,USenglish]{article}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage[utf8]{inputenc}
\usepackage[margin=1.0in]{geometry}
\usepackage{microtype}
\usepackage{xcolor}
\usepackage{algpseudocodex}

\usepackage[colorlinks,allcolors=blue!70!black]{hyperref}
\usepackage[capitalise,nameinlink,noabbrev,compress]{cleveref}

\title{\bf{Algpseudocodex Package Documentation}}
\author{Christian Matt \\ \url{https://github.com/chrmatt/algpseudocodex}}
\date{\today\\v1.0}

\begin{document}

\maketitle

\begin{abstract}
	This package allows typesetting pseudocode in \LaTeX. It is based on \texttt{algpseudocode} from the \texttt{algorithmicx} package and uses the same syntax, but adds several new features and improvements. Notable features include customizable indent guide lines and the ability to draw boxes around parts of the code for highlighting differences. This package also has better support for long code lines spanning several lines and improved comments.
\end{abstract}

\newpage

\tableofcontents

\newpage

\section{Basic Usage}
To use the package, load it in your preamble:
\begin{verbatim}
	\usepackage{algpseudocodex}
\end{verbatim}

Basic usage is identical to \texttt{algpseudocode} from the \texttt{algorithmicx} package. Pseudocode written for that package should also be compatible with \texttt{algpseudocodex}.

\subsection{Algorithmic Block}
Pseudocode can be typeset inside a algorithmic blocks:
\begin{verbatim}
	\begin{algorithmic}[line numbering]
	    ...
	\end{algorithmic}
\end{verbatim}
The optional argument specifies how lines are numbered. $0$ means no numbering, $n > 0$ means every $n$th line gets a number. The default is $0$, i.e., no line numbers will be typeset if no optional argument is provided.

\subsection{Simple Statements and Commands}
Statements start with \verb|\State|. The command \verb|\Statex| can be used to start a new line that does not get a new line number.

The commands \verb|\Return| and \verb|\Output| can be used for return values of functions and outputs. They do not start a new line on their own, so they need to be used together with \verb|\State|.

The \verb|\Call| command is used for procedure calls. It takes two arguments: The first one is the name of the procedure and the second one are the arguments.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\begin{algorithmic}[1]
		    \State first line
		    \Statex continuing first line
		    \State \Call{Proc}{a1, a2}
		    \State \Output Hello World!
		\end{algorithmic}
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}[1]
		\State first line
		\Statex continuing first line
		\State \Call{Proc}{a1, a2}
		\State \Output Hello World!
	\end{algorithmic}
\end{minipage}


\subsection{Blocks}
Blocks are used for loops, conditional statements, and functions. Blocks can also be nested within other blocks.

\subsubsection{While Loop}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\While{condition}
		    \State body
		\EndWhile
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\While{condition}
		    \State body
		\EndWhile
	\end{algorithmic}
\end{minipage}


\subsubsection{For Loop}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\For{$n = 1, \dots, 10$}
		    \State body
		\EndFor
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\For{$n = 1, \dots, 10$}
		    \State body
		\EndFor
	\end{algorithmic}
\end{minipage}

\subsubsection{For-All Loop}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\ForAll{$n \in \{1, \dots, 10\}$}
		    \State body
		\EndFor
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\ForAll{$n \in \{1, \dots, 10\}$}
		    \State body
		\EndFor
	\end{algorithmic}
\end{minipage}

\subsubsection{Loop}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\Loop
		    \State body
		\EndLoop
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\Loop
		    \State body
		\EndLoop
	\end{algorithmic}
\end{minipage}

\subsubsection{Repeat-Until Loop}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\Repeat
		    \State body
		\Until{$n > 10$}
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\Repeat
		    \State body
		\Until{$n > 10$}
	\end{algorithmic}
\end{minipage}

\subsubsection{If Statement}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\If{condition}
		    \State body
		\ElsIf{condition}
		    \State body
		\Else
		    \State body
		\EndIf
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\If{condition}
		    \State body
		\ElsIf{condition}
		    \State body
		\Else
		    \State body
		\EndIf
	\end{algorithmic}
\end{minipage}

\bigskip
The \verb|\ElsIf| and \verb|\Else| parts are optional.


\subsubsection{Procedure}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\Procedure{name}{parameters}
		    \State body
		\EndProcedure
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\Procedure{name}{parameters}
		    \State body
		\EndProcedure
	\end{algorithmic}
\end{minipage}


\subsubsection{Function}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\Function{name}{parameters}
		    \State body
		\EndFunction
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\Function{name}{parameters}
		    \State body
		\EndFunction
	\end{algorithmic}
\end{minipage}


\subsection{Require and Ensure}
To specify conditions on the inputs and outputs of an algorithm, \verb|\Require| and \verb|\Ensure| can be used.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\begin{algorithmic}[1]
		    \Require $x \in \{0,1\}$
		    \Ensure $y \in \{1,2\}$
		    \State $y \gets x+1$
		    \State \Return $y$
		\end{algorithmic}
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}[1]
		\Require $x \in \{0,1\}$
		\Ensure $y \in \{1,2\}$
		\State $y \gets x+1$
		\State \Return $y$
	\end{algorithmic}
\end{minipage}


\subsection{Comments}
There are two ways to typeset code comments: The command \verb|\Comment| can be used to add shorts comments to the end of the current line. The command \verb|\LComment| can be used to typeset long comments that can span multiple lines. Comments with \verb|\LComment| start on a new line.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\begin{algorithmic}[1]
		    \State $x \gets y^2$
		    \LComment{The next two lines
		        increment both $x$ and $y$.}
		    \State $x \gets x + 1$
		    \Comment{Increment $x$.}
		    \State $y \gets y + 1$
		    \Comment{Increment $y$.}
		\end{algorithmic}
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}[1]
		\State $x \gets y^2$
		\LComment{The next two lines
			increment both $x$ and $y$.}
		\State $x \gets x + 1$
		\Comment{Increment $x$.}
		\State $y \gets y + 1$
		\Comment{Increment $y$.}
	\end{algorithmic}
\end{minipage}


\section{Boxes}
A unique feature of the \texttt{algpseudocodex} package is the ability to draw boxes around pieces of code. There are two different methods to do so: One for drawing boxes around multiple lines of code, and another one for drawing a box around a string on a single line of code.

\subsection{Boxes Around Multiple Lines of Code}
The command \verb|\BeginBox[style]| is used to set the beginning of the box. The optional argument determines the style of the drawn box. The boxes are drawn using TikZ, so any TikZ style can be used. The default style can be changed as described in \cref{sec:defBoxStyle}.
The command \verb|\EndBox| is used to set the end of the last started box. Boxes can be nested arbitrarily, but every \verb|\BeginBox| needs a matching \verb|\EndBox|.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\begin{algorithmic}
		    \BeginBox
		        \State first line
		        \BeginBox[fill=yellow]
		            \State second line
		            \State another line
		        \EndBox
		    \EndBox
		    \BeginBox[draw=blue,dashed]
		        \State last line
		    \EndBox
		\end{algorithmic}
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\BeginBox
			\State first line
			\BeginBox[fill=yellow]
				\State second line
				\State another line
			\EndBox
		\EndBox
		\BeginBox[draw=blue,dashed]
			\State last line
		\EndBox
	\end{algorithmic}
\end{minipage}


\subsection{Boxes Inside Single Line}
The command \verb|\BoxedString[style]{text}| is used to typeset text with a box around it. The optional argument determines the style of the box, as in \verb|\BeginBox|. The default style is the same as for \verb|\BeginBox|.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\begin{verbatim}
		\begin{algorithmic}
		    \State first line
		    \State second line with
		    \BoxedString[fill=yellow]{box}
		    \State last line
		\end{algorithmic}
	\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\begin{algorithmic}
		\State first line
		\State second line with
		\BoxedString[fill=yellow]{box}
		\State last line
	\end{algorithmic}
\end{minipage}


\section{Package Options}
When loading \texttt{algpseudocodex} the options describe in this section can be set. They syntax for setting \verb|option1| to \verb|value1| and \verb|option2| to \verb|value2| is:
\begin{verbatim}
	\usepackage[option1=value1,option2=value2]{algpseudocodex}
\end{verbatim}

\subsection{noEnd}
\begin{description}
	\item[possible values:] \verb|true|, \verb|false|
	\item[default:] \verb|true|
\end{description}
If \verb|false|, the end of blocks are marked with the expression ``end'' followed by the name of the block.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|noEnd=false|:
	\begin{algorithmic}
		\makeatletter
		\setbool{algpx@noEnd}{false}%
		\algtext{EndIf}{\algpx@endIndent\algpx@startCodeCommand\algorithmicend\ \algorithmicif%
			\algpx@startIndent% \EndIf ends another indent. Start fake one here to handle that.
		}
		\makeatother
		\If{$x > 0$}
			\State $x \gets x - 1$
		\EndIf
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|noEnd=true|:
	\begin{algorithmic}
		\If{$x > 0$}
			\State $x \gets x - 1$
		\EndIf
	\end{algorithmic}
\end{minipage}


\subsection{indLines}
\begin{description}
	\item[possible values:] \verb|true|, \verb|false|
	\item[default:] \verb|true|
\end{description}
If \verb|true|, indent guide lines are drawn. The style of the lines can be customized as described in \cref{sec:indStyle}.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|indLines=false|:
	\begin{algorithmic}
		\makeatletter
		\setbool{algpx@indLines}{false}%
		\makeatother
		\If{$x > 0$}
			\State $x \gets x - 1$
		\EndIf
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|indLines=true|:
	\begin{algorithmic}
		\If{$x > 0$}
			\State $x \gets x - 1$
		\EndIf
	\end{algorithmic}
\end{minipage}


\subsection{spaceRequire}
\begin{description}
	\item[possible values:] \verb|true|, \verb|false|
	\item[default:] \verb|true|
\end{description}
If \verb|true|, vertical space is added before every \verb|\Require| except the one on the first line. This is useful for specifying different behaviors depending on the provided input.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|spaceRequire=false|:
	\begin{algorithmic}
		\makeatletter
		\setbool{algpx@spaceRequire}{false}%
		\makeatother
		\Require $x \in \{0,1\}$
		\State \Return $x$
		\Require $x \in \{1,2\}$
		\State \Return $x-1$
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|spaceRequire=true|:
	\begin{algorithmic}
		\Require $x \in \{0,1\}$
		\State \Return $x$
		\Require $x \in \{1,2\}$
		\State \Return $x-1$
	\end{algorithmic}
\end{minipage}


\subsection{italicComments}
\begin{description}
	\item[possible values:] \verb|true|, \verb|false|
	\item[default:] \verb|true|
\end{description}
If \verb|true|, all comments are typeset in italic font. If \verb|false|, comments are typeset in roman font.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|italicComments=false|:
	\begin{algorithmic}
		\makeatletter
		\setbool{algpx@italicComments}{false}%
		\makeatother
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|italicComments=true|:
	\begin{algorithmic}
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}


\subsection{rightComments}
\begin{description}
	\item[possible values:] \verb|true|, \verb|false|
	\item[default:] \verb|true|
\end{description}
If \verb|true|, comments typeset with \verb|\Comment| are right justified on the current line. If a comment does not fit on the current line, no justification is applied. If \verb|false|, all comments are typeset right after the end of the current line.

Does not affect long comments typeset with \verb|\LComment|.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|rightComments=false|:
	\begin{algorithmic}
		\makeatletter
		\setbool{algpx@rightComments}{false}%
		\makeatother
		\LComment{No effect on long comments.}
		\State $x \gets 0$ \Comment{Short comment.}
		\State $x \gets x^2$ \Comment{Does not fit on the current line and is thus not justified.}
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|rightComments=true|:
	\begin{algorithmic}
		\LComment{No effect on long comments.}
		\State $x \gets 0$ \Comment{Short comment.}
		\State $x \gets x^2$ \Comment{Does not fit on the current line and is thus not justified.}
	\end{algorithmic}
\end{minipage}


\subsection{commentColor}
\begin{description}
	\item[possible values:] Any color that can be used in \verb|\textcolor|.
	\item[default:] \verb|gray|
\end{description}
Defines the color in which comments are typeset.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|commentColor=black|:
	\begin{algorithmic}
		\makeatletter
		\renewcommand{\algpx@commentColor}{black}%
		\makeatother
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|commentColor=blue|:
	\begin{algorithmic}
		\makeatletter
		\renewcommand{\algpx@commentColor}{blue}%
		\makeatother
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}


\subsection{beginComment and endComment}
\begin{description}
	\item[possible values:] Any string that can be typeset in text mode.
	\item[default:] \verb|$\triangleright$~| and (empty)
\end{description}
Used to indicate the beginning and end of comments typeset with \verb|\Comment|, respectively.

\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|beginComment=//~|:
	\begin{algorithmic}
		\makeatletter
		\renewcommand{\algpx@beginComment}{//~}%
		\makeatother
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\textwidth}
	\verb|beginComment=/*~|, \verb|endComment=~*/|:
	\begin{algorithmic}
		\makeatletter
		\renewcommand{\algpx@beginComment}{/*~}%
		\renewcommand{\algpx@endComment}{~*/}%
		\makeatother
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}

\subsection{beginLComment and endLComment}
\begin{description}
	\item[possible values:] Any string that can be typeset in text mode.
	\item[default:] \verb|$\triangleright$~| and \verb|~$\triangleleft$|
\end{description}
Used to indicate the beginning and end of long comments typeset with \verb|\LComment|, respectively.
\subsubsection*{Example}
\begin{minipage}[t]{0.45\textwidth}
	\verb|beginLComment=/*~|, \verb|endLComment=~*/|:
	\begin{algorithmic}
		\makeatletter
		\renewcommand{\algpx@beginLComment}{/*~}%
		\renewcommand{\algpx@endLComment}{~*/}%
		\makeatother
		\LComment{Long comment.}
		\State $x \gets 0$ \Comment{Short comment.}
	\end{algorithmic}
\end{minipage}


\section{Customization}
\subsection{Style of Indent Guide Lines}\label{sec:indStyle}
Indent guide lines are drawn using TikZ and consequently any TikZ style can be used. To set the style, use:
\begin{verbatim}
	\tikzset{algpxIndentLine/.style={style}}
\end{verbatim}
The default style is \verb|draw=gray,very thin|.

\subsubsection*{Example}
\verb|algpxIndentLine/.style={draw=blue,dashed}|:
\begin{algorithmic}
	\tikzset{algpxIndentLine/.style={draw=blue,dashed}}
	\If{$x > 0$}
		\State $x \gets x - 1$
	\EndIf
\end{algorithmic}


\subsection{Default Style of Boxes}\label{sec:defBoxStyle}
Boxes are drawn using TikZ and consequently any TikZ style can be used. To set the default style, use:
\begin{verbatim}
	\tikzset{algpxDefaultBox/.style={style}}
\end{verbatim}
The default style is \verb|draw|.


\subsection{Changing Keywords}
As in the \texttt{algorithmicx} package, keywords can be renamed using the syntax:
\begin{verbatim}
	\algrenewcommand\keyword{new name}
\end{verbatim}
The following keywords can be customized:
\begin{itemize}
	\item \verb|\algorithmicend|
	\hfill Default: \verb|\textbf{end}|
	\item \verb|\algorithmicdo|
	\hfill Default: \verb|\textbf{do}|
	\item \verb|\algorithmicwhile|
	\hfill Default: \verb|\textbf{while}|
	\item \verb|\algorithmicfor|
	\hfill Default: \verb|\textbf{for}|
	\item \verb|\algorithmicforall|
	\hfill Default: \verb|\textbf{for all}|
	\item \verb|\algorithmicloop|
	\hfill Default: \verb|\textbf{loop}|
	\item \verb|\algorithmicrepeat|
	\hfill Default: \verb|\textbf{repeat}|
	\item \verb|\algorithmicuntil|
	\hfill Default: \verb|\textbf{until}|
	\item \verb|\algorithmicprocedure|
	\hfill Default: \verb|\textbf{procedure}|
	\item \verb|\algorithmicfunction|
	\hfill Default: \verb|\textbf{function}|
	\item \verb|\algorithmicif|
	\hfill Default: \verb|\textbf{if}|
	\item \verb|\algorithmicthen|
	\hfill Default: \verb|\textbf{then}|
	\item \verb|\algorithmicelse|
	\hfill Default: \verb|\textbf{else}|
	\item \verb|\algorithmicrequire|
	\hfill Default: \verb|\textbf{Require:}|
	\item \verb|\algorithmicensure|
	\hfill Default: \verb|\textbf{Ensure:}|
	\item \verb|\algorithmicreturn|
	\hfill Default: \verb|\textbf{return}|
	\item \verb|\algorithmicoutput|
	\hfill Default: \verb|\textbf{output}|
\end{itemize}


\end{document}