sphinxcontrib-pseudocode demo¶

Features¶

Below shows various rendered algorithms, which are copied from corresponding pseudocode.js examples. The source code of those algorithms can be found here.

We can also reference any particular algorithm. For example, we can also reference each algorithm:

:numref:`quick-sort` produces Algorithm 1
:numref:`Here is my algorithm {number} <quick-sort>` produces Here is my algorithm 1
:ref:`test control blocks <test-control-blocks>` produces test control blocks

Note

We assume each pcode directive contains exactly one $\LaTeX$ algorithmic block:

\begin{algorithm}
\caption{Test atoms}
\begin{algorithmic}
\STATE my algorithm 1
\END{ALGORITHMIC}
\END{ALGORITHM}

You still can have multiple algorithmic blocks but the numbering will be messed up.

By default, each pcode is mapped to ‘Algorithm %s’ when referenced via numref. You can change this behavior by overriding the corresponding string of 'pseudocode' key in numfig_format.

             \begin{algorithmic}
 \PRINT \texttt{'hello world'}
 \end{algorithmic}

             % This quicksort algorithm is extracted from Chapter 7, Introduction to Algorithms (3rd edition)
 \begin{algorithm}
 \caption{Quicksort}
 \begin{algorithmic}
 \PROCEDURE{Quicksort}{$A, p, r$}
     \IF{$p < r$}
         \STATE $q = $ \CALL{Partition}{$A, p, r$}
         \STATE \CALL{Quicksort}{$A, p, q - 1$}
         \STATE \CALL{Quicksort}{$A, q + 1, r$}
     \ENDIF
 \ENDPROCEDURE
 \PROCEDURE{Partition}{$A, p, r$}
     \STATE $x = A[r]$
     \STATE $i = p - 1$
     \FOR{$j = p$ \TO $r - 1$}
         \IF{$A[j] < x$}
             \STATE $i = i + 1$
             \STATE exchange
             $A[i]$ with     $A[j]$
         \ENDIF
         \STATE exchange $A[i]$ with $A[r]$
     \ENDFOR
 \ENDPROCEDURE
 \end{algorithmic}
 \end{algorithm}

            \begin{algorithm}
\caption{Test text-style}
\begin{algorithmic}
\REQUIRE some preconditions
\ENSURE some postconditions
\INPUT some inputs
\OUTPUT some outputs
\PROCEDURE{Test-Declarations}{}
    \STATE font families: {\sffamily sffamily, \ttfamily ttfamily, \normalfont normalfont, \rmfamily rmfamily.}
    \STATE font weights: {normal weight, \bfseries bold, \mdseries
    medium, \lfseries lighter. }
    \STATE font shapes: {\itshape itshape \scshape Small-Caps \slshape slshape \upshape upshape.}
    \STATE font sizes: \tiny tiny \scriptsize scriptsize \footnotesize
    footnotesize \small small \normalsize normal \large large \Large Large
    \LARGE LARGE \huge huge \Huge Huge \normalsize
\ENDPROCEDURE
\PROCEDURE{Test-Commands}{}
    \STATE \textnormal{textnormal,} \textrm{textrm,} \textsf{textsf,} \texttt{texttt.}
    \STATE \textbf{textbf,} \textmd{textmd,} \textlf{textlf.}
    \STATE \textup{textup,} \textit{textit,} \textsc{textsc,} \textsl{textsl.}
    \STATE \uppercase{uppercase,} \lowercase{LOWERCASE.}
\ENDPROCEDURE
\PROCEDURE{Test-Colors}{}
% feature not implemented
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

            \begin{algorithm}
\caption{Test atoms}
\begin{algorithmic}
\STATE \textbf{Specials:} \{ \} \$ \& \# \% \_
\STATE \textbf{Bools:} \AND \OR \NOT \TRUE \FALSE
\STATE \textbf{Carriage return:} first line \\ second line
\STATE \textbf{Text-symbols:} \textbackslash
\STATE \textbf{Quote-symbols:} `single quotes', ``double quotes''
\STATE \textbf{Math:} $(\mathcal{C}_m)$, $i \gets i + 1$, $E=mc^2$, \( x^n + y^n = z^n \), $\$$, \(\$\)
\END{ALGORITHMIC}
\END{ALGORITHM}

            \begin{algorithm}
\caption{Test control blocks}
\begin{algorithmic}
\PROCEDURE{Test-If}{}
    \IF{ <cond>}
        \STATE <block>;
    \ELIF{<cond>}
        \STATE <block>;
    \ELSE
        \STATE <block>;
    \ENDIF
\ENDPROCEDURE
\PROCEDURE{Test-For}{$n$}
    \STATE $i \gets 0$
    \FOR{$i < n$}
        \PRINT $i$
        \STATE $i \gets i + 1$
    \ENDFOR
\ENDPROCEDURE
\PROCEDURE{Test-For-To}{$n$}
    \STATE $i \gets 0$
    \FOR{$i$ \TO $n$}
        \PRINT $i$
    \ENDFOR
\ENDPROCEDURE
\PROCEDURE{Test-For-DownTo}{$n$}
    \FOR{$i \gets n$ \DOWNTO $0$}
        \PRINT $i$
    \ENDFOR
\ENDPROCEDURE
\PROCEDURE{Test-For-All}{$n$}
    \FORALL{$i \in \{0, 1, \cdots, n\}$}
        \PRINT $i$
    \ENDFOR
\ENDPROCEDURE
\PROCEDURE{Test-While}{$n$}
    \STATE $i \gets 0$
    \WHILE{$i < n$}
        \PRINT $i$
        \STATE $i \gets i + 1$
    \ENDWHILE
\ENDPROCEDURE
\PROCEDURE{Test-Repeat}{$n$}
    \STATE $i \gets 0$
    \REPEAT
        \PRINT $i$
        \STATE $i \gets i + 1$
    \UNTIL{$i>n$}
\ENDPROCEDURE
\PROCEDURE{Test-Break-Continue}{$n$}
    \FOR{$i = 0$ \TO $2n$}
        \IF{$i < n/2$}
            \CONTINUE
        \ELIF{$i > n$}
            \BREAK
        \ENDIF
        \PRINT $i$
    \ENDFOR
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

            \begin{algorithm}
\caption{Test statements and comments}
\begin{algorithmic}
\PROCEDURE{Test-Statements}{}
    \STATE This line is a normal statement
    \PRINT \texttt{`this is print statement'}
    \RETURN $retval$
\ENDPROCEDURE

\PROCEDURE{Test-Comments}{} \COMMENT{comment for procedure}
    \STATE a statement \COMMENT{inline comment}
    \STATE \COMMENT{line comment}
    \IF{some condition}\COMMENT{comment for if}
        \RETURN \TRUE \COMMENT{another inline comment}
    \ELSE \COMMENT{comment for else}
        \RETURN \FALSE \COMMENT{yet another inline comment}
    \ENDIF
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

            % This quicksort algorithm is extracted from Chapter 7, Introduction
% to Algorithms (3rd edition)
\begin{algorithm}
\caption{Quicksort}
\begin{algorithmic}
\PROCEDURE{Quicksort}{$A, p, r$}
    \IF{$p < r$}
        \STATE $q = $ \CALL{Partition}{$A, p, r$}
        \STATE \CALL{Quicksort}{$A, p, q - 1$}
        \STATE \CALL{Quicksort}{$A, q + 1, r$}
    \ENDIF
\ENDPROCEDURE
\PROCEDURE{Partition}{$A, p, r$}
    \STATE $x = A[r]$
    \STATE $i = p - 1$
    \FOR{$j = p$ \TO $r - 1$}
        \IF{$A[j] < x$}
            \STATE $i = i + 1$
            \STATE exchange
            $A[i]$ with $A[j]$
        \ENDIF
        \STATE exchange $A[i]$ with $A[r]$
    \ENDFOR
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

Cross-References with `:ref:`¶

You can use RST :ref: roles inside a pcode block to link to any labeled algorithm (or any other labeled element) on the page. The role is resolved at build time and rendered as a clickable <a> link in the algorithm body.

For example, we can write

.. pcode::

   \begin{algorithm}
   \caption{A variant of Quicksort}
   \begin{algorithmic}
   \STATE Partition step is the same as in :ref:`Quicksort <quick-sort>`
   \PROCEDURE{Quicksort-Variant}{$A, p, r$}
       \IF{$p < r$}
           \STATE $q = $ \CALL{Partition}{$A, p, r$}
           \STATE \CALL{Quicksort-Variant}{$A, p, q - 1$}
           \STATE \CALL{Quicksort-Variant}{$A, q + 1, r$}
       \ENDIF
   \ENDPROCEDURE
   \end{algorithmic}
   \end{algorithm}

and the code will get rendered as

            \begin{algorithm}
\caption{A variant of Quicksort}
\begin{algorithmic}
\STATE Partition step is the same as in PCSREF0
\PROCEDURE{Quicksort-Variant}{$A, p, r$}
    \IF{$p < r$}
        \STATE $q = $ \CALL{Partition}{$A, p, r$}
        \STATE \CALL{Quicksort-Variant}{$A, p, q - 1$}
        \STATE \CALL{Quicksort-Variant}{$A, q + 1, r$}
    \ENDIF
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

The :ref: role supports both the short form :ref:`label` and the long form :ref:`display text <label>`.

Custom Macros with `\newcommand`¶

You can define your own LaTeX macros using \newcommand in three ways:

Inline Macros: Define the macro at the beginning of the pcode block. The macro will only be available for that specific block.

Note

Due to a quirk in the reStructuredText parser, a directive’s content block cannot begin with a \. To avoid issues, do not start a pcode block directly with a \newcommand. The simplest workaround is to add a comment line before the first macro definition.

For example, we can write
```
.. pcode::

   % A comment to avoid parser issues
   \newcommand{\floor}[1]{\lfloor #1 \rfloor}

   \begin{algorithm}
   \caption{Using an Inline Macro}
   \begin{algorithmic}
   \STATE The floor of 3.14 is $\floor{3.14}$.
   \end{algorithmic}
   \end{algorithm}
```
and the code will get rendered as
\[ \newcommand{\ceil}[1]{\lceil #1 \rceil} \newcommand{\floor}[1]{\lfloor #1 \rfloor} \]
```
            % A comment to avoid parser issues

\begin{algorithm}
\caption{Using an Inline Macro}
\begin{algorithmic}
\STATE The floor of 3.14 is $\floor{3.14}$.
\end{algorithmic}
\end{algorithm}
        
```

Per-Page Macros: Define macros in a .. math:: block. These macros will be available to all pcode blocks on the same page. For example, we can write

.. math::

   \newcommand{\ceil}[1]{\lceil #1 \rceil}

.. pcode::

   \begin{algorithm}
   \caption{Using a Per-Page Macro}
   \begin{algorithmic}
   \STATE The ceiling of 3.14 is $\ceil{3.14}$.
   \end{algorithmic}
   \end{algorithm}

and the code will get rendered as

\[\newcommand{\ceil}[1]{\lceil #1 \rceil}\]

            \begin{algorithm}
\caption{Using a Per-Page Macro}
\begin{algorithmic}
\STATE The ceiling of 3.14 is $\ceil{3.14}$.
\end{algorithmic}
\end{algorithm}

Global Macros: Define macros in your conf.py file using the mathjax3_config setting. These macros will be available across your entire Sphinx project.

# In conf.py
mathjax3_config = {
    'tex': {
        'macros': {
            'RR': r'\mathbb{R}',
        }
    }
}

Then we can write

.. pcode::

   \begin{algorithm}
   \caption{Using a Global Macro}
   \begin{algorithmic}
   \STATE The set of real numbers is $\RR$.
   \end{algorithmic}
   \end{algorithm}

and the code will get rendered as

            \begin{algorithm}
\caption{Using a Global Macro}
\begin{algorithmic}
\STATE The set of real numbers is $\RR$.
\end{algorithmic}
\end{algorithm}

sphinxcontrib-pseudocode demo¶

Features¶

Cross-References with :ref:¶

Custom Macros with \newcommand¶

Cross-References with `:ref:`¶

Custom Macros with `\newcommand`¶