.. -*- coding: utf-8; indent-tabs-mode: nil; -*-


**************   
 Introduction
**************

The package contains the following lexers:

.. include:: lexerlist.rst

They may be used in `Sphinx`_ by their aliases:

.. code-block:: none

   .. code-block:: algpseudocode

      \PROGRAM {The Pseudoprogram} \IS

      \END PROGRAM {The Pseudoprogram}

It will be rendered as:

.. code-block:: algpseudocode

   \PROGRAM {The Pseudoprogram} \IS

   \END PROGRAM {The Pseudoprogram}

And the same with the german variant
(using ``.. code-block:: algpseudocode-de`` as language alias):

.. code-block:: algpseudocode-de

   \PROGRAM {The Pseudoprogram} \IS

   \END PROGRAM {The Pseudoprogram}

A basic documentation for FrPseudocode you find on its
:ref:`detail page <fr-pseudocode>`.

The AlgPseudocode lexer and its friends AlgPseudocodeDE and AlgPseudocodeFR
basically work in three states: `default`, `expression` and `text`.

  In expressions it automatically recognizes:

  - Strings (single-quote, double-quote, triple-single-quote,
    triple-double-quote, `Python`_ style)
  - Numbers (also `Python`_ style)
  - (Mathematical) operators and symbols
  - ``\TEXT{...}``

    To switch in a text-mode that prohibits automatic expression
    highlighting.

    A closing curly brace can be quoted with ``\}`` to not end the
    text mode prematurely.

  - ``\NAME``, ``\CALL`` and ``\GETS``

  - ``\REM`` and ``\REMARK`` for remarks (aka comments)

  - Names (`Name.Entity`)

  - :ref:`explicit-token-types`

  In the default-mode it recogzizes expressions and additionally all
  sorts of comments and commands that are inspired by CTAN's
  `Algpseudocodex`_.

  In texts it recogzizes:

  - ``\EXPR`` or ``\EXPRESSION``

    To switch to expression-mode.

    A closing curly brace can be quoted with ``\}`` to not end the expression
    mode prematurely.

  - ``\REM`` and ``\REMARK`` for remarks (aka comments)

  - :ref:`explicit-token-types`


.. rubric:: Some Examples

A synthetic example with most features:

.. literalinclude:: examples/example-1.pseudocode
   :language: algpseudocode
   :lines: 2-

With a customized `AlgPseudocodeLexer` and its `no_end`
option set to ``True``.

.. literalinclude:: examples/example-1.pseudocode
   :language: NoEndAlgPseudocode
   :lines: 2-

This is Wikipedia's description of *Dinic's Algorithm*
(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm):

.. literalinclude:: examples/algorithm-dinic.description
   :language: algpseudocode
   :lines: 2-

This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm):

.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
   :language: algpseudocode
   :lines: 2-

This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
with a custom lexer that skip all ``ENDxxx`` keywords:

.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
   :language: NoEndAlgPseudocode
   :lines: 2-

And now the *Edmonds–Karp Algorithm* with french keywords:

.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
   :language: algpseudocode-fr
   :lines: 2-

More details you will find :ref:`here <details-algpseudocode>`.