%! Author = Jander Moreira %! Email = moreira.jander@gmail.com \documentclass[a4paper, 11pt]{article} \usepackage[T1]{fontenc} \usepackage[presets]{packdoc} \usepackage[ brazilian, language = english, ]{algxpar} \usepackage{needspace} \begin{filecontents}[overwrite, nosearch, noheader]{algxpar-lzw.tex} \begin{algorithmic}[1] \Description LZW Compression using a table with all known sequences of bytes. \Input A flow of bytes \Output A flow of bits with the compressed representation of the input bytes \Statex \Statep{Initialize a table with all byte values}[each table position holds a single byte] \Statep{Initialize \Id{sequence} with the first byte from the input stream} \While{there are bytes in the input}[wait until all bytes have been processed] \Statep{Retrieve a single byte from the input and store it in \Id{byte}} \If{the concatenation of \Id{sequence} and \Id{byte} exists in the table} \Statep{Set \Id{sequence} to $\Id{sequence} + \Id{byte}$}[concatenate without generating any output] \Else \Statep{Output the code for \Id{sequence}}[i.e., the binary representation of its index in the table] \Statep{Add the concatenation of \Id{sequence} and \Id{byte} to the table}[the table learns a new, longer sequence] \Statep{Set \Id{sequence} to \Id{byte}}[begin a new sequence with the remaining byte] \EndIf \EndWhile \Statep{Output the code for \Id{sequence}}[the remaining bit sequence] \end{algorithmic} \end{filecontents} %% Repetitive text \NewDocumentCommand{\MacroOptionsText}{}{% Any \Argument{options} specified apply only to this macro.% } \NewDocumentCommand{\BlockOptionsText}{}{% Any \Argument{options} specified in this macro will impact this command and all items within the inner block, propagating up to and including the closing macro.% } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \title{% The \PackageName{algxpar} package\\\normalsize\AlgVersion } \author{Jander Moreira -- \texttt{moreira.jander@gmail.com}} \date{\AlgDate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{document} \maketitle \begin{abstract} The \PackageName{algxpar} package is an extension of the \PackageName{algorithmicx}\footnote{\url{https://ctan.org/pkg/algorithmicx}.}/\PackageName{algpseudocode} package to handle multi-line text with proper indentation and provide a number of other improvements. \end{abstract} \tableofcontents \PDNewVersion{0.9}{2019-11-12} \PDAddChange{0.9}{ description = Initial version., no box, no page, }% \PDNewVersion{0.91}{2020-08-01} \PDNewVersion{0.99}{2023-06-28} \PDAddChange{0.99}{ description = The code was reviewd and almost entirely rewritten., no box, no page, }. \PDNewVersion{0.99.1}{2024/05/05} \PDNewVersion{0.99.2}{2024/10/23} \PDAddChange{0.99.2}{ description = Part of the code was rewritten using \PackageName{etoolbox}., no box, no page, } \PDNewVersion{0.99.2a}{2025/07/31} \PDAddChange{0.99.2a}{ description = {Fixed length computation in non-commented lines to consider the token length.}, no box, no page, } \begin{figure} \tcbinputlisting{example, listing file = algxpar-lzw.tex, listing only} \vspace{3em} \tcbinputlisting{example, listing file = algxpar-lzw.tex, text only} \end{figure} \PDPrintChanges \section{Introduction} I teach algorithms and programming, and for writing my algorithms, I've adopted the \PackageName{algorithmicx} package (\PackageName{algpseudocode}). It allows me to create pseudocode that's both clear and easy to read, requiring minimal effort to ensure it looks visually appealing. Teaching algorithms involves a different approach to pseudocode compared to its typical use in scientific papers, where solutions are often presented in a more formal, concise manner. Students typically work with abstract algorithms before learning a specific programming language, so the focus is more on the logic of the solution than on the variables themselves. Additionally, teaching strategies that emphasize refinement and iteration call for a less programmatic and more descriptive style of code. For instance, instead of writing something like ``${s \gets s + c}$,'' we might say, ``\emph{accumulate current expenses in the total sum of costs},'' as the latter provides a clearer explanation of the logic without requiring students to understand the specifics of variable manipulation. However, this more verbose approach often results in longer sentences that can span multiple lines. Given that pseudocode places a premium on visual clarity—particularly in control structures and indentation—it became necessary to create a package that accommodates multi-line statements while maintaining readability. The \PackageName{algorithmicx} and \PackageName{algpseudocode} packages do not natively support multi-line statements. Therefore, this package extends several macros to manage multi-line code properly, adding new commands and features to improve its functionality. \needspace{3cm} \section{Package usage and options}\label{sec:package-usage-and-options} This package depends on the following packages: \begin{center} \begin{tabular}{ll} \PackageName{algorithmicx} & (\url{https://ctan.org/pkg/algorithmicx}) \\ \PackageName{algpseudocode} & (\url{https://ctan.org/pkg/algorithmicx}) \\ \PackageName{amssymb} & (\url{https://ctan.org/pkg/amsfonts}) \\ \PackageName{etoolbox} & (\url{https://ctan.org/pkg/etoolbox}) \\ % \PackageName{fancyvrb} & (\url{https://ctan.org/pkg/fancyvrb}) \\ \PackageName{pgfmath} & (\url{https://ctan.org/pkg/pgf}) \\ \PackageName{pgfopts} & (\url{https://ctan.org/pkg/pgf}) \\ \PackageName{ragged2e} & (\url{https://ctan.org/pkg/ragged2e}) \\ % \PackageName{tcolorbox} & (\url{https://www.ctan.org/pkg/tcolorbox}) \\ \PackageName{varwidth} & (\url{https://www.ctan.org/pkg/varwidth}) \\ \PackageName{xcolor} & (\url{https://www.ctan.org/pkg/xcolor}) \\ \end{tabular} \end{center} \medskip To use the package, simply request its use in the preamble of the document. \begin{Macro*}{usepackage}{\OArg{package options list}\PArg{algxpar}}{} \end{Macro*} Currently, the list of package options includes the following. \begin{Option*}{\Argument{language name}}{}{} Algorithm keywords are typically created in English by default, with the English keyword set always being loaded. When available, one can use keyword sets in other languages by specifying the desired language. Currently supported languages: \begin{itemize} \item \OptionInd{english} (default language, always loaded) \item \OptionInd{brazilian} Brazilian Portuguese \end{itemize} \end{Option*} \begin{PDListing} % Loads Brazilian keyword set and sets it as default \usepackage[brazilian]{algxpar} \end{PDListing} \begin{Optiondef}{language}{\Argument{language name}}{} This option selects the keyword set corresponding to \Argument{language name} as the document's default. It is available as a general option (see \OptionRef{language}). This option is useful when other languages are loaded. \end{Optiondef} \begin{PDListing} % Loads Brazilian keyword set but keeps English as default \usepackage[brazilian, language = english]{algxpar} \end{PDListing} \begin{Optiondef}{noend}{\PDInline{true} | \PDInline{false}}{Default: \PDInline{true}; initially: \PDInline{true}} The \Option{noend} option suppresses the line marking the end of a block, while preserving the indentation. See more information in \OptionRef{end} and \OptionRef{noend} options. \end{Optiondef} \begin{PDListing} % Suppresses all end-lines that close a block \usepackage[noend]{algxpar} \end{PDListing} \section{Writting pseudocode} Algorithms, following the structure of the \PackageName{algorithmicx} package, are written within the \PDInline{algorithmic} environment. The option to use a number to determine line numbering is preserved from the original version. An algorithm consists of instructions, control structures like conditionals and loops, as well as documentation and comments. \begin{PDExample} \begin{algorithmic} \Description Calculation of the factorial of a natural number \Input $n \in \mathbb{N}$ \Output $n!$ \Statex \Statep{\Read $n$} \Statep{$\Id{factorial} \gets 1$}[$0! = 1! = 1$] \For{$k \gets 2$ \To $n$}[from 2 up] \Statep{$\Id{factorial} \gets \Id{factorial} \times k$}[$(k-1)! \times k$] \EndFor \Statep{\Write \Id{factorial}} \end{algorithmic} \end{PDExample} \subsection{A preamble on comments}\label{sec:a-preamble-on-comments} This is Euclid's algorithm as shown in the \PackageName{algorithmicx} package documentation\footnote{A label has been suppressed here.}. \begingroup %! formatter = off \AlgSet{comment font = {}} \begin{PDExample} \begin{algorithmic}[1] \Procedure{Euclid}{$a,b$} \Comment{The g.c.d. of a and b} \State $r\gets a\bmod b$ \While{$r\not=0$} \Comment{We have the answer if r is 0} \State $a\gets b$ \State $b\gets r$ \State $r\gets a\bmod b$ \EndWhile \State \textbf{return} $b$\Comment{The gcd is b} \EndProcedure \end{algorithmic} \end{PDExample} %! formatter = on \endgroup Comments are added \textit{in loco} with the \MacroRef{Comment} macro, which makes them appear along the right margin. The \PackageName{algxpar} package embeded comments as part of the commands themselves in order to add multi-line support. Until \PackageName{algxpar} v0.95, they could be added as an optional parameter before the text, in the style of most \LaTeX\ macros. %! formatter = off \begingroup \AlgSet{comment font = {}} \begin{PDExample} \begin{algorithmic}[1] \Procedure[The g.c.d. of a and b]{Euclid}{$a,b$} % <-- Comment \State $r\gets a\bmod b$ \While[We have the answer if r is 0]{$r\not=0$} % <-- Comment \State $a\gets b$ \State $b\gets r$ \State $r\gets a\bmod b$ \EndWhile \Statep[The gcd is b]{\Keyword{return} $b$} % <-- Comment \EndProcedure \end{algorithmic} \end{PDExample} \endgroup %! formatter = on Using the comment before the text always bothered me somewhat, as it seemed more natural to put it after. \PDAddChange{ type = new, version = 0.99, description = Optional comments may be specified after the command }% Thus, as of v0.99, the comment can be placed after the text (as the second parameter of the macro), certainly making writing algorithms more user-friendly. To maintain backward compatibility, the use of comments before text is still supported, although it is discouraged. \PDAddChange{ type = new, version = 0.99, description = Lines that closes blocks can have comments }% In addition to this change, the use of comments in the new format has been extended to most pseudocode macros, such as \MacroRef{EndWhile} for example. %! formatter = off \begingroup \AlgSet{comment font = {}} \begin{PDExample} \begin{algorithmic}[1] \Procedure{Euclid}{$a,b$}[The g.c.d. of a and b] % <-- Comment \State $r\gets a\bmod b$ \While{$r\not=0$}[We have the answer if r is 0] % <-- Comment \State $a\gets b$ \State $b\gets r$ \State $r\gets a\bmod b$ \EndWhile[end of the loop] % <-- Comment \Statep{\Keyword{return} $b$}[The gcd is b] % <-- Comment \EndProcedure \end{algorithmic} \end{PDExample} \endgroup %! formatter = on Using \MacroRef{Comment} still produces the expected result, although it may break automatic tracking of longer lines. Throughout this documentation, former style comments are denoted as \Argument{comment*}, while the new format uses \Argument{comment}. See more about comments in \cref{sec:comments}. \subsection{A preamble on options}\label{sec:a-preamble-on-options} \PDAddChange{0.99}{ description = {The ``look and feel'' of the pseudocode can be set in the \Macro{begin}\PDInline{{algorithmic}}}, no box, }% As of version 0.99, a list of options can be added to each command, changing some algorithm presentation settings. These settings are optional and must be entered using angle brackets at the end of the command. %! formatter = off \begin{PDExample} \begin{algorithmic} \If{$a > b$}[check conditions] \While{$a > 0$} \Statep{\Call{Process}{$a$}}[process current data] \EndWhile \EndIf \end{algorithmic} \end{PDExample} %! formatter = on There is a lot of additional information about options and how they can be used. See discussion and full list in \cref{sec:customization-and-fine-tunning}. \subsection{Statements}\label{sec:statements} The macros \Macro{State} and \Macro{Statex} defined in \PackageName{algorithmicx} can still be used for single statements and have the same general behaviour. For automatic handling of comments and multi-line text, the \Macro{Statep} macro is available, which should be used instead of \Macro{State}. \begin{Macrodef}{Statep}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} The \Macro{Statep} macro corresponds to an statement that can extrapolate a single line. The continuation of each line is indented from the baseline and this indentation is based on the value indicated in the \OptionRef{statement indent} option. \MacroOptionsText \end{Macrodef} % As an example, observe lines~\ref{alg:lzw:output} and \ref{alg:lzw:add-to-table} of the LZW compression algorithm on \cpageref{alg:lzw:add-to-table}. \subsection{Flow Control Blocks}\label{sec:flow-control-blocks} Flow control is essentially based on conditionals and loop. \subsubsection{The \Keyword{if} block} This block is the standard \textit{if} block. \begin{PDExample} \begin{algorithmic} \State \Read $v$ \If{$v < 0$}[is it negative?] \Statep{$v \gets -v$}[make it positive] \EndIf \end{algorithmic} \end{PDExample} \begin{Macrodef}{If}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} \Macro{If} shows \Argument{text} (the condition) and must be closed with an \MacroRef{EndIf}, creating a block of nested commands. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndIf}{\OArg{comment}\AArg{options}}{} \Macro{EndIf} closes its respective \MacroRef{If}. \MacroOptionsText \end{Macrodef} \begin{Macrodef}{Else}{\OArg{comment}\AArg{options}}{} This macro defines the \Keyword{else} part of the \MacroRef{If} statement. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{Elsif}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} \Macro{ElsIf} defines the \MacroRef{If} chaining. The argument \Argument{text} is the new condition. \BlockOptionsText \end{Macrodef} \subsubsection{The \Keyword{switch} block} %! formatter = off \begin{PDExample} \begin{algorithmic} \Statep{Get \Id{Optiondef}} \Switch{\Id{Optiondef}} \Case{1}[inserts new record] \Statep{\Call{Insert}{\Id{record}}} \EndCase \Case{2}[deletes a record] \Statep{\Call{Delete}{\Id{key}}} \EndCase \Otherwise \Statep{Print ``invalid option''} \EndOtherwise \EndSwitch \end{algorithmic} \end{PDExample} %! formatter = on \begin{Macrodef}{Switch}{\OArg{comment*}\MArg{expression}\OArg{comment}\AArg{options}}{} The \Macro{Switch} is closed by a matching \MacroRef{EndSwitch}. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndSwitch}{\OArg{comment}\AArg{options}}{} This macro closes a \MacroRef{Switch} block. \MacroOptionsText \end{Macrodef} \begin{Macrodef}{Case}{\OArg{comment*}\MArg{constant-list}\OArg{comment}\AArg{options}}{} When the result of the \Keyword{switch} expression matches one of the constants in \Argument{constants-list}, then the \Keyword{case} is executed. Usually the \Argument{constant-list} is a single constant, a comma-separated list of constants or some kind of range specification. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndCase}{\OArg{comment}\AArg{options}}{} This macro closes a corresponding \MacroRef{Case} statement. \MacroOptionsText \end{Macrodef} \begin{Macrodef}{Otherwise}{\OArg{comment}\AArg{options}}{} A \Keyword{switch} structure can optionally use an \Keyword{otherwise} clause, which is executed when no previous \Keyword{case}s had a hit. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndOtherwise}{\OArg{comment}\AArg{options}}{} This macro closes a corresponding \MacroRef{Otherwise} statement. \MacroOptionsText \end{Macrodef} \subsubsection{The \Keyword{for} block} The \Keyword{for} loop uses \Macro{For} and is also flavored with two variants: \Keyword{foreach} (\Macro{ForEach}) and \Keyword{forall} (\Macro{ForAll}). %! parser = off \begin{PDExample} \begin{algorithmic} \For{$i \gets 0$ \To $n$} \Statep{Do something with $i$} \EndFor \ForAll{$\Id{item} \in C$} \Statep{Do something with \Id{item}} \EndFor \ForEach{\Id{item} in queue $Q$} \Statep{Do something with \Id{item}} \EndFor \end{algorithmic} \end{PDExample} %! parser = on \begin{Macrodef}{For}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} The \Argument{text} is used to establish the loop scope. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndFor}{\OArg{comment}\AArg{Optiondef}}{} This macro closes a corresponding \MacroRef{For}, \MacroRef{ForEach} or \MacroRef{ForAll}. \MacroOptionsText \end{Macrodef} \begin{Macrodef}{ForEach}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} Same as \MacroRef{For}. \end{Macrodef} \begin{Macrodef}{ForAll}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} Same as \MacroRef{For}. \end{Macrodef} \subsubsection{The \Keyword{while} block} \Macro{While} is the loop with testing condition at the top. \begin{PDExample} \begin{algorithmic} \While{$n > 0$} \Statep{Do something} \Statep{$n \gets n - 1$} \EndWhile \end{algorithmic} \end{PDExample} \begin{Macrodef}{While}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} In \Argument{text} is the boolean expression that, when \False, will end the loop. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndWhile}{\OArg{comment}\AArg{options}}{} This macro closes a matching \MacroRef{While} block. \MacroOptionsText \end{Macrodef} \subsubsection{The \Keyword{repeat}-\Keyword{until} block} The loop with testing condition at the bottom is the \Macro{Repeat}/\Macro{Until} block. \begin{PDExample} \begin{algorithmic} \Repeat \Statep{Do something} \Statep{$n \gets n - 1$} \Until{$n \leq 0$} \end{algorithmic} \end{PDExample} \begin{Macrodef}{Repeat}{\OArg{comment}\AArg{options}}{} This macro starts the \Keyword{repeat} loop, which is closed with \MacroRef{Until}. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{Until}{\OArg{comment*}\MArg{text}\OArg{comment}\AArg{options}}{} In \Argument{text} is the boolean expression that, when \MacroRef{True}, will end the loop. \MacroOptionsText \end{Macrodef} \subsubsection{The \Keyword{loop} block} A generic loop is build with \Macro{Loop}. \begin{PDExample} \begin{algorithmic} \Loop \Statep{Do something} \Statep{$n \gets n + 1$} \If{$n$ is multiple of 5} \Statep{\Continue}[restarts loop] \EndIf \Statep{Do something else} \If{$n \leq 0$} \Statep{\Break}[ends loop] \EndIf \Statep{Keep working} \EndLoop \end{algorithmic} \end{PDExample} \begin{Macrodef}{Loop}{\OArg{comment}\AArg{options}}{} The generic loop starts with \Macro{Loop} and ends with \MacroRef{EndLoop}. Usually the infinite loop is interrupted by and internal \MacroDef{Break} or restarted with \MacroDef{Continue}. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndLoop}{\OArg{comment}\AArg{options}}{} \Macro{EndLoop} closes a matching \MacroRef{Loop} block. \MacroOptionsText \end{Macrodef} \subsection{Constants and Identifiers}\label{sec:constants-and-identifiers} A few macros for well known constants were defined: \MacroDef{True} (\True), \MacroDef{False} (\False), and \MacroDef{Nil} (\Nil). The macro \Macro{Id} was created to handle ``program-like'' named identifiers, such as \Id{sum}, \Id{word_counter} and so on. \begin{Macrodef}{Id}{\MArg{identifier}}{} \PDAddChange{0.91}{ update, description = {\Macro{Id} has been recoded to work in both text and math modes, preventing hyphenation}, no box, }% \PDAddChange{0.99.2a}{ update, description = {\MacroRef{Id} updated to natively handle the underscore character without escaping.}, }% Identifiers are emphasised: \PDInline!\Id{my_value}! is \Id{my_value}. Its designed to work in both text and math modes: \PDInline!$\Id{offer}_k$! is $\Id{offer}_k$. \end{Macrodef} \subsection{Assignments and I/O}\label{sec:assignments-and-i/o} To support teaching-like, basic pseudocode writing, the macros \MacroDef{Read} and \MacroDef{Write} are provided. \begin{PDExample} \begin{algorithmic} \Statep{\Read $v_1, v_2$} \Statep{$\Id{mean} \gets \dfrac{v_1 + v_2}{2}$}[calculate] \Statep{\Write \Id{mean}} \end{algorithmic} \end{PDExample} The \Macro{Set} macro, although obsolete, can be used for assignments. \begin{Macrodef}{Set}{\MArg{lvalue}\MArg{expression}}{} \PDAddChange{0.91}{ description = \Macro{Set} can be used for assignments., no box, }% \PDAddChange{0.99}{ deprecation, description = {\Macro{Set} is deprecated and will no longer be supported}, }% This macro expands to \MacroRef{Id}\PDInline!{#1} \gets #2!. It will no longer be supported but will be retained as-is for backward compatibility. Since proper handling of text and math modes is needed and its usage offers no clear benefit, there is no justification to keep it. \end{Macrodef} \PDAddChange{0.99}{ removal, title = \Macro{Setl}, description = {\Macro{Setl} has been removed from the package}, }% The macro \MacroRefInd{Setl} has been removed. \subsection{Procedures and Functions}\label{sec:procedures-and-functions} Modularization uses \Macro{Procedure} or \Macro{Function}. %! formatter = off \begin{PDExample} \begin{algorithmic} \Procedure{SaveNode}{\Id{node}}[saves a B\textsuperscript{+}-tree node to disk] \If{\Id{node}.\Id{is_modified}} \If{$\Id{node}.\Id{address} = -1$} \Statep{Set file writting position after file's last byte}[creates a new node on disk] \Else \Statep{Set file writting position to \Id{node}.\Id{address}}[updates the node] \EndIf \Statep{Write \Id{node} to disk} \Statep{$\Id{node}.\Id{is_modified} \gets \False$} \EndIf \EndProcedure \end{algorithmic} \end{PDExample} \begin{PDExample} \begin{algorithmic} \Function{Factorial}{$n$}[$n \geq 0$] \If{$n \in \{0, 1\}$} \Statep{\Return $1$}[base case] \Else \Statep{\Return $n \times \Call{Factorial}{n-1}$}[recursive case] \EndIf \EndFunction \end{algorithmic} \end{PDExample} %! formatter = on \begin{Macrodef}{Procedure}{\MArg{name}\MArg{argument list}\OArg{comment}\AArg{options}}{} This macro creates a \Keyword{procedure} block that must be ended with \MacroRef{EndProcedure}. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndProcedure}{\OArg{comment}\AArg{optons}}{} This macro closes the \MacroRef{Procedure} block. \MacroOptionsText \end{Macrodef} \begin{Macrodef}{Function}{\MArg{name}\MArg{argument list}\OArg{comment}\AArg{options}}{} This macro creates a \Keyword{function} block that must be ended with \MacroRef{EndFunction}. A \MacroDef{Return} is defined. \BlockOptionsText \end{Macrodef} \begin{Macrodef}{EndFunction}{\OArg{comment}\AArg{optons}}{} This macro closes the \MacroRef{Function} block. \MacroOptionsText \end{Macrodef} For calling a procedure or function, \Macro{Call} should be used. \begin{Macrodef}{Call}{\MArg{name}\MArg{arguments}\AArg{options}}{} \label{call} \Macro{Call} is used to state a function or procedure call. The module's \Argument{name} and \Argument{arguments} are mandatory. \MacroOptionsText \end{Macrodef} \subsection{Comments}\label{sec:comments} The \Macro{Comment} macro, as defined by the \PackageName{algorithmicx} package, retains its original behavior and has been redefined to support styling options. \begin{Macrodef}{Comment}{\MArg{text}\AArg{options}}{} The updated \Macro{Comment} can be used with \Macro{State}, \Macro{Statex}, and \MacroRef{Statep}. When used with \MacroRef{Statep}, it should be enclosed within the text braces, though multi-line statements may function differently than expected. \MacroOptionsText \end{Macrodef} %! formatter = off \begin{PDExample} \begin{minipage}{7.5cm} \begin{algorithmic} % for viewing purposes only \State Assign the value zero to the variable $x$\Comment{first assignment} \Statep{Assign the value zero to the variable $x$\Comment{first assignment}} \Statep{Assign the value zero to the variable $x$}[first assignment]% best choice \end{algorithmic} \end{minipage} \end{PDExample} %! formatter = on \begin{Macrodef}{Commentl}{\MArg{text}\AArg{options}}{} While \MacroRef{Comment} pushes text to the end of the line, the \Macro{Commentl} macro is ``local'' -- it simply places a comment without altering the line structure. Local comments follows regular text and no line changes are checked. \MacroOptionsText \end{Macrodef} \begin{PDExample} \begin{algorithmic} \If{$a > 0$~~\Commentl{special case}\\ or\\ $a < b$~~\Commentl{general case}\\} \Statep{Process data~~\Commentl{may take a while}} \EndIf \end{algorithmic} \end{PDExample} \begin{Macrodef}{CommentIn}{\MArg{text}\AArg{options}}{} \Macro{CommentIn} is an alternative to \textit{line comments}, which typically extend to the end of the line. This macro defines a comment with both a beginning and an end. A comment starts with \CommentSymbol\ and ends with \CommentSymbolRight. \MacroOptionsText \end{Macrodef} \begin{PDExample} \begin{algorithmic} \If{$a > 0$ \CommentIn{special case} or $a < b$ \CommentIn{general case}} \Statep{Process data~~\Commentl{may take a while}} \EndIf \end{algorithmic} \end{PDExample} \subsection{Documentation}\label{sec:documentation} A series of macros are defined to provide the header documentation for a pseudocode. \begin{PDExample} \begin{algorithmic} \Description Calculation of the factorial of a natural number through successive multiplications \Require $n \in \mathbb{N}$ \Ensure $f = n!$ \end{algorithmic} \end{PDExample} \begin{Macrodef}{Description}{~\Argument{description text}}{} The \Macro{Description} is intended to hold the general description of the pseudocode. \end{Macrodef} \begin{Macrodef}{Require}{~\Argument{pre-conditions}}{} The required initial state that the code relies on. These are \textit{pre-conditions}. \end{Macrodef} \begin{Macrodef}{Ensure}{~\Argument{post-conditions}}{} The final state produced by the code. These are \textit{post-conditions}. \end{Macrodef} \begin{PDExample} \begin{algorithmic} \Description Calculation of the factorial of a natural number through successive multiplications \Input $n$ (integer) \Output $n!$ (integer) \end{algorithmic} \end{PDExample} \begin{Macrodef}{Input}{~\Argument{inputs}}{} This works as an alternative to \MacroRef{Require}, presenting \Keyword{input}. \end{Macrodef} \begin{Macrodef}{Output}{~\Argument{outputs}}{} This works as an alternative to \MacroRef{Ensure}, presenting \Keyword{output}. \end{Macrodef} \section{Customization and Fine Tunning}\label{sec:customization-and-fine-tunning} Starting from version 0.99 of \PackageName{algxpar}, a set of options has been introduced to customize the presentation of algorithms. For instance, colors and fonts specific to keywords can now be specified, offering a more convenient way to tailor each algorithm. The \MacroRef{AlgSet} macro fulfills this purpose. \begin{Macrodef}{AlgSet}{\MArg{options list}}{} This macro sets algorithmic settings as specified in the \Argument{options list}, which is key/value comma-separated list. All settings will be applied to the entire document from the point where the macro is called. To limit the scope of a definition made with \MacroRef{AlgSet} to a specific part of the document, simply enclose it in a \TeX\ group. \end{Macrodef} \begingroup \begin{PDExample} \AlgSet{algorithmic indent = 1.5cm} \begin{algorithmic} \Statep{\Read $k$} \If{$k < 0$} \Statep{$k \gets -k$} \EndIf \Statep{\Write $k$} \end{algorithmic} \end{PDExample} \endgroup% ends the scope If the settings are only applied to a single algorithm and not a group of algorithms in a text section, the easiest way is to include the options in the \texttt{algorithmicx} environment. %! formatter = off \begin{PDExample} \begin{algorithmic} \Statep{\Read $k$} \If{$k < 0$} \Statep{$k \gets -k$} \EndIf \Statep{\Write $k$} \end{algorithmic} \end{PDExample} %! formatter = on Named styles can also be defined using the \PackageName{pgfkeys} syntax. %! formatter = off \begin{PDExample} \AlgSet{ fancy/.style = { text color = green!40!black, keyword color = blue!75!black, comment color = brown!80!black, comment symbol = \texttt{//}, } } \begin{algorithmic} \Statep{\Commentl{Process $k$}} \Statep{\Read $k$} \If{$k < 0$} \Statep{$k \gets -k$}[back to positive] \EndIf \Statep{\Write $k$} \end{algorithmic} \end{PDExample} %! formatter = on Sometimes some settings need to be applied exclusively to one command, for example to highlight a segment of the algorithm. %! formatter = off \begin{PDExample} \AlgSet{ highlight/.style = { text color = red!60!black, keyword color = red!60!black, } } \begin{algorithmic} \Statep{\Commentl{Process $k$}} \Statep{\Read $k$} \If{$k < 0$} \Statep{$k \gets -k$}[back to positive] \EndIf \Statep{\Write $k$} \end{algorithmic} \end{PDExample} %! formatter = on \subsection{Options}\label{sec:options} \PDAddChange{0.99}{ description = {Added support to style the main components of the pseudocode, such as keywords, comments and text and widths.}, no box, }% This section presents the options that can be specified for the algorithms, either using \MacroRef{AlgSet} or the \Argument{options} parameter of the various macros. \begin{Optiondef}{indent lines}{\PDInline{true} | \PDInline{false}}{Default: \PDInline{true}; initially: \PDInline{false}} \PDAddChange{0.99.1}{ description = Added experimental support to show vertical indentantion lines, }% The \Option{indent lines} option displays vertical indentation lines in the pseudocode. This feature works properly only if the start and end of the block are on the same page. Additionally, at least two compilation steps are needed for the lines to be correctly positioned. To change the style for the lines, use \OptionRef{line style} \textit{This feature is still experimental and incomplete.} \end{Optiondef} %! formatter = off \begin{PDExample} \begin{algorithmic} \For{$i \gets 0$ \To $N - 1$} \For{$j \gets$ \To $N - 1$} \If{$m_{ij} < 0$} \Statep{$m_{ij} \gets 0$} \EndIf \EndFor \EndFor \end{algorithmic} \begin{algorithmic} \For{$i \gets 0$ \To $N - 1$} \For{$j \gets$ \To $N - 1$} \If{$m_{ij} < 0$} \Statep{$m_{ij} \gets 0$} \EndIf \EndFor \EndFor \end{algorithmic} \end{PDExample} %! formatter = on \begin{Optiondef}{line style}{\Argument{style}}{} \PDAddChange{0.99.1}{ description = {\Option{line style} option added to style indent lines.}, }% Almost anything Ti\emph{k}Z can apply to a line can be used to set the indentation lines. To show indentation lines in algorithms, \OptionRef{indent lines} must be set to true. \end{Optiondef} %! formatter = off \begin{PDExample} \begin{algorithmic} \For{$i \gets 0$ \To $N - 1$} \For{$j \gets$ \To $N - 1$} \If{$m_{ij} < 0$} \Statep{$m_{ij} \gets 0$} \EndIf \EndFor \EndFor \end{algorithmic} \end{PDExample} %! formatter = on \begin{Optiondef}{language}{\Argument{language}}{} This key is used to select the keyword language set for the current scope. The language keyword set should have already been loaded via the package options (see \cref{sec:package-usage-and-options}). \end{Optiondef} \begin{Optiondef}{noend}{} Structured algorithms use blocks to define their structures, marking both the beginning and the end. In pseudocode, it is common to use a line to indicate the end of a block. The \Option{end} option suppresses this line. The result resembles a program written in Python. \end{Optiondef} \begin{Optiondef}{end}{} This option reverses the behaviour of \OptionRef{noend}, and the closing line of a block presented. \end{Optiondef} %! formatter = off \begin{PDExample} \begin{algorithmic} \For{$i \gets 0$ \To $N - 1$} \For{$j \gets$ \To $N - 1$} \If{$m_{ij} < 0$} \Statep{$m_{ij} \gets 0$} \EndIf \EndFor \EndFor \end{algorithmic} \end{PDExample} %! formatter = on \begin{Optiondef}{keywords}{\Argument{list of keywords assignments}}{} This option allows you to modify an existing keyword or define a new one. For more information on keywords and translations, see \cref{sec:languages-and-translations}. \end{Optiondef} %! formatter = off \begin{PDExample} \begin{algorithmic} < keywords = { terminate = Terminate, % new keyword then = \{, % redefined endif = \}, % redefined while = whilst, % redefined } > \While{\True} \If{$t < 0$} \Statep{Run the \Keyword{terminate} module} \EndIf \EndWhile \end{algorithmic} \end{PDExample} %! formatter = on \begin{Optiondef}{algorithmic indent}{\Argument{width}}{Initially: \PDInline{1.5em}} The algorithmic indent is the amount of horizontal space used for indentation inner commands. This option actually sets the \PackageName{algorithmicx}'s \Macro{algorithmicindent}. \end{Optiondef} \begin{Optiondef}{comment symbol}{\Argument{symbol}}{Initially: \PDInline{$\triangleright$}} The default symbol that preceeds the text in comments is \CommentSymbol, as used by \PackageName{algorithmicx}, and can be changed with this key. The current comment symbol is available with \MacroDef{CommentSymbol}. Do not change this symbol by redefining \Macro{CommentSymbol}, as font, shape and color settings will no longer be respected. Always use \Option{comment symbol}. \end{Optiondef} \begin{Optiondef}{comment symbol right}{\Argument{symbol}}{Initially: \PDInline{$\triangleleft$}} This symbol closes a \MacroRef{CommentIn}. It is set to \CommentSymbolRight\ and can be accessed using the \MacroDef{CommentSymbolRight} macro. Avoid changing the symbol by redefining \Macro{CommentSymbolRight}, as this would cause font, shape, and color settings to be ignored. Always use the \Option{comment symbol right} option. \end{Optiondef} \subsubsection{Fonts, shapes and sizes} The options ins this section allows setting font family, shape, weight and size for several parts of an algorithm. Notice that color are handled separately (see \cref{sec:colors}) and using \Macro{color} with font options will tend to break the document. \begin{Optiondef}{text font}{\Argument{font, shape and size}}{Initially: empty} This setting corresponds to the font family, its shape and size and applies to the \Argument{text} field in each of the commands. \end{Optiondef} % \begin{Optiondef}{comment font}{\Argument{font, shape and size}}{Initially: \PDInline{\slshape}} This setting corresponds to the font family, its shape and size and applies to all comments. \end{Optiondef} \begin{Optiondef}{keyword font}{\Argument{font, shape and size}}{Initially: \PDInline{\bfseries}} This setting sets the font family, shape, and size, and applies to all keywords, such as \Keyword{function} or \Keyword{end}. \end{Optiondef} \begin{Optiondef}{constant font}{\Argument{font, shape and size}}{Initially: \PDInline{\scshape}} This setting sets the font family, shape, and size, and applies to all constants, such as \Nil, \True\ and \False. This setting also applies when \MacroRef{Constant} is used. \end{Optiondef} \begin{Optiondef}{module font}{\Argument{font, shape and size}}{Initially: \PDInline{\scshape}} This setting sets the font family, shape, and size, and applies to both procedure and function identifiers, as well as their callings with \MacroRef{Call}. \end{Optiondef} \subsubsection{Colors}\label{sec:colors} Colors are defined using the \PackageName{xcolors} package. \begin{Optiondef}{text color}{\Argument{color}}{Initially: \PDInline{.}} This setting corresponds to the color that applies to the \Argument{text} field in each of the commands. \end{Optiondef} \begin{Optiondef}{comment color}{\Argument{color}}{Initially: \PDInline{.!70}} This setting corresponds to the color that applies to all comments. \end{Optiondef} \begin{Optiondef}{keyword color}{\Argument{color}}{Initially: \PDInline{.}} This key is used to set the color for all keywords. \end{Optiondef} \begin{Optiondef}{constant color}{\Argument{color}}{Initially: \PDInline{.}} This setting corresponds to the color that applies to the defined constant (see \cref{sec:constants-and-identifiers}) and also when macro \MacroRef{Constant} is used. \end{Optiondef} \begin{Optiondef}{module color}{\Argument{color}}{Initially: \PDInline{.}} This color is applied to the identifier used in both \MacroRef{Procedure} and \MacroRef{Function} definitions, as well as module calls with \MacroRef{Call}. Notice that the arguments use \Option{text color}. \end{Optiondef} \subsubsection{Paragraphs} Multi-line support are internally handled by \Macro{parbox}es. \PDAddChange{0.99.2}{ update, description = {Wrong spacing between parboxes were fixed.}, no box, } \medskip %! formatter = off \begingroup \begin{algorithmic} \Procedure{Euclid}{$a,b$}[The g.c.d. of a and b] \Statep{$r\gets a\bmod b$} \While{$r\not=0$}[We have the answer if r is 0] \Statep{$a\gets b$} \Statep{$b\gets r$} \Statep{$r\gets a\bmod b$} \EndWhile \Statep{\Keyword{return} $b$}[The g.c.d. is b] \EndProcedure \end{algorithmic} \endgroup %! formatter = on \medskip The options in this section should be used to set how these paragraphs will be presented. \begin{Optiondef}{text style}{\Argument{style}}{Initially: \PDInline{\RaggedRight}} This \Argument{style} is applied to the paragraph box that holds the \Argument{text} field in all commands. \end{Optiondef} \begin{Optiondef}{comment style}{\Argument{style}}{Initially: \PDInline{\RaggedRight}} This \Argument{style} is applied to the paragraph box that holds the \Argument{comment} field in all algorithmic commands. This setting will not be used with \MacroRef{Comment}, \MacroRef{Commentl} or \MacroRef{CommentIn}. \end{Optiondef} \begin{Optiondef}{comment separator width}{\Argument{width}}{Initially: \PDInline{1em}} The minimum space between the text box and the \Macro{CommentSymbol}. This affects the available space in a line for keywords, text and comment. \end{Optiondef} \begin{Optiondef}{statement indent}{\Argument{width}}{Initially: \PDInline{1em}} This is the \Macro{hangindent} set inside \MacroRef{Statep} statements. \end{Optiondef} \begin{Optiondef}{comment width}{\PDInline{auto}|\PDInline{nice}|\Argument{width}}{Initially: \PDInline{auto}} There are two ways to balance the lengths of \Argument{text} and \Argument{comments} on a line, each providing different visual experiences. In automatic mode (\PDInline{auto}), the balance is chosen considering the widths that the actual text and comment have, trying to reduce the total number of lines, given there is not enough space in a single line for the keywords, text , comment and comment symbol. The consequence is that each line with a comment will have its own balance. The second mode, \PDInline{nice}, sets a fixed width for the entire algorithm, maintaining consistency across all comments. In that case, longer comments will tend to span a larger number of lines. The ``nice value'' is hardcoded and sets the comment width to \PDInline{0.4\linewidth}. Also, a fixed comment \Argument{width} can be specified. \end{Optiondef} % todo: insert the parameter indent when it starts working \begin{comment} parameter indent = 0pt, \end{comment} \subsection{Languages and translations}\label{sec:languages-and-translations} \PDAddChange{0.99}{ description = {New mechanism to translation with separate files for each language}, no box, }% A simple mechanism is employed to allow keywords to be translated into other languages. %! formatter = off \begingroup \begin{PDExample} \begin{algorithmic} \Procedure{Euclid}{$a,b$} \State $r\gets a\bmod b$ \While{$r\not=0$} \State $a\gets b$ \State $b\gets r$ \State $r\gets a\bmod b$ \EndWhile \Statep{\Keyword{return} $b$} \EndProcedure \end{algorithmic} \end{PDExample} \endgroup %! formatter = on Creating a new keyword set uses the \Macro{AlgLanguageSet} macro. \begin{Macrodef}{AlgLanguageSet}{\MArg{language name}\MArg{keyword assignments}}{} This macro assigns new values to existing keywords as well as creates new ones. Once defined, keywords cannot be removed. If a default keyword is not redefined, the English version will be used. To create a new set, copy the file \FileName{algxpar-english.kw.tex} and modify it as needed. Note that there is a set of keywords for the lines that close each block. These keys are included to offer more flexibility in customizing how these lines are displayed. It is strongly recommended to use the {Keyword} macro for references to other keywords, so that font, color, and language changes can be made without issues. In translations, these \textit{compound keywords} are not necessarily required (see the file \FileName{brazilian.kw.tex}, which follows the settings in \FileName{algxpar-english.kw.tex}). However, if they are defined, there will be different versions for each language. \end{Macrodef} % \begin{figure} \tcbinputlisting{example, listing file = algxpar-english.kw.tex, listing only} % \end{figure} The mechanism behind \MacroRef{AlgLanguageSet} utilizes the \Macro{SetKeyword} macro, which is called to modify the value of a single keyword\footnote{Macros such as \Macro{algorithmicwhile} from the \PackageName{algorithmicx} package are no longer in use.}. To retrieve the value of a specific keyword, the \Macro{Keyword} macro should be used. It produces the formatted value based on the options currently applied to keywords. \begin{Macrodef}{SetKeyword}{\OArg{language}\MArg{keyword}\MArg{value}}{} The macro \MacroRef{SetKeyword} changes a given \Argument{keyword} to \Argument{value} if it exists; otherwise a new keyword is created. If \Argument{language} is omitted, the language currently in use is changed. See also the \OptionRef{keywords} option. \end{Macrodef} \begin{Macrodef}{Keyword}{\OArg{language}\MArg{keyword}}{} This macro expands to the value of a keyword in a \Argument{language} using the font, shape, size, and color determined for the keyword set. If \Argument{language} is not specified, the current language is used. \Argument{keyword} is any keyword defined for a language, including custom ones. \end{Macrodef} \begin{PDExample} \SetKeyword[german]{if}{wenn} % new Depending on the language, a keyword can take different forms: \Keyword{if} (English), \Keyword[german]{if} (German) or \Keyword[brazilian]{if} (Brazilian Portuguese). \end{PDExample} \begin{PDExample} \AlgLanguageSet{spanish}{ while = mientras, do = hacer, endwhile = fin, if = si, then = entonces, else = en otro caso, endif = fin, } \begin{algorithmic} \If{$a > b$}[check conditions] \While{$a > 0$} \Statep{\Call{Process}{$a$}}[process current data] \EndWhile \Else \Statep{\Call{Signal}{\Id{pid}}} \EndIf \end{algorithmic} \end{PDExample} \subsection{Other features} \PDAddChange{0.99}{ description = Added support to style named constants and function/procedures identifiers, no box, }% These macros were added to support the styles defined for named constants and function and procedure identifiers. \begin{Macrodef}{Constant}{\MArg{name}}{} This macro presents \Argument{name} using font, shape, size and color defined for constants. \end{Macrodef} \begin{Macrodef}{Module}{\MArg{name}}{} This macro presents \Argument{name} using font, shape, size and color defined for procedures and functions. \end{Macrodef} \section{``Forgotten'' features} \PDAddChange{0.99}{ removal, description = {Macros \Macro{TextString} and \Macro{VisibleSpace} accidentally removed.}, no box, }% Some features were forgotten from v0.91 to v.99, although it was not intentional. The macros \Macro{TextString} and \Macro{VisibleSpace} simply vanished into thin air. \section{To do} This is a \textit{todo} list: \begin{itemize} \item Add font, shape, size and color settings to a whole algorithm; \item Add font, shape, size and color settings to line numbers; \item Add font, shape, size and color settings to identifiers. \end{itemize} \section{Examples} \subsection{LZW revisited} \begingroup \begin{PDListing} \AlgSet{ comment color = purple, comment width = nice, comment style = \raggedleft, } \end{PDListing} \AlgSet{ comment color = purple, comment width = nice, comment style = \raggedleft, } \input{algxpar-lzw.tex} \endgroup \subsection{LZW revisited again} \begingroup \begin{PDListing} \AlgSet{ keyword font = \ttfamily, keyword color = green!40!black, text font = \itshape, comment font = \footnotesize, algorithmic indent = 1.5em, indent lines, noend, } \end{PDListing} \AlgSet{ keyword font = \ttfamily, keyword color = green!40!black, text font = \itshape, comment font = \footnotesize, algorithmic indent = 1.5em, indent lines, noend, } \noindent% \begin{minipage}{\linewidth} \input{algxpar-lzw.tex} \end{minipage} \endgroup % Index \printindex \end{document} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%