This documentation is kept for historical reasons, the up-to-date documentation is available at: `flak-zoso.github.io/Sista <https://flak-zoso.github.io/Sista/>`_.

``Library``
================

``Sista`` as a library is a collection of the following headers:

- ``ansi.hpp``: ANSI escape codes for terminal colors and styles
- ``border.hpp``: Border
- ``coordinates.hpp``: Coordinates manipulation
- ``cursor.hpp``: Cursor, clearScreen
- ``field.hpp``: Field
- ``pawn.hpp``: Pawn
- ``sista.hpp``: main header file, includes all the others

From this point all the elements of the library are part of the ``sista`` namespace.

``ansi.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/ansi.hpp>`_ contains the following preprocessor constants:

+-------------+-------------+-----------------------------+
| Constant    | Value       | Description                 |
+=============+=============+=============================+
| CSI         | "\x1b["     | Command Sequence Introducer |
+-------------+-------------+-----------------------------+
| ESC         | "\x1b"      | ESC                         |
+-------------+-------------+-----------------------------+
| CLS         | "\x1b[2J"   | CLean Screen                |
+-------------+-------------+-----------------------------+
| SSB         | "\x1b[3J"   | Scroll Screen Buffer        |
+-------------+-------------+-----------------------------+
| TL          | "\x1b[H"    | Top Left                    |
+-------------+-------------+-----------------------------+
| HIDE_CURSOR | "\x1b[?25l" | Hide Cursor                 |
+-------------+-------------+-----------------------------+
| SHOW_CURSOR | "\x1b[?25h" | Show Cursor                 |
+-------------+-------------+-----------------------------+

This header also contains the following functions:

.. code-block:: cpp

    void setForegroundColor(ForegroundColor);
    void setBackgroundColor(BackgroundColor);
    void setAttribute(Attribute);
    void resetAttribute(Attribute);
    void resetAnsi();
    void setForegroundColor(const RGBColor&);
    void setBackgroundColor(const RGBColor&);
    void setForegroundColor(unsigned short int, unsigned short int, unsigned short int);
    void setBackgroundColor(unsigned short int, unsigned short int, unsigned short int);
    void setForegroundColor(unsigned short int);
    void setBackgroundColor(unsigned short int);
    void setScreenMode(ScreenMode);
    void unsetScreenMode(ScreenMode);

This header also contains the following struct used to represent a color in RGB format:

.. code-block:: cpp

    struct RGBColor {
        unsigned short int red;
        unsigned short int green;
        unsigned short int blue;

        RGBColor();
        RGBColor(unsigned short int, unsigned short int, unsigned short int);
    };

This header also contains the following enums based on the `ANSI escape codes <https://en.wikipedia.org/wiki/ANSI_escape_code>`_

.. code-block:: cpp

    enum class ForegroundColor : int;
    enum class BackgroundColor : int;
    enum class Attribute : int;
    enum class ScreenMode : int;

This header also contains the following struct used to represent the style of a char in the terminal:

.. code-block:: cpp

    struct ANSISettings {
        std::variant<ForegroundColor, RGBColor> foregroundColor;
        std::variant<BackgroundColor, RGBColor> backgroundColor;
        Attribute attribute;
    };

``border.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/border.hpp>`_ contains the following class used to represent the border of a field.

.. code-block:: cpp

    class Border {
    protected:
        char symbol; // Symbol of the Border
        ANSISettings settings; // settings of the Border style
    public:
        Border(char, ANSISettings);
        Border(char, ANSISettings&, bool);
        virtual void print(bool apply_settings=true) const;
    };

``coordinates.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/coordinates.hpp>`_ contains the following struct used to represent the coordinates of a Pawn.

.. code-block:: cpp

    struct Coordinates { // 2D coordinates
        unsigned short y; // y coordinate
        unsigned short x; // x coordinate

        Coordinates();
        Coordinates(unsigned short, unsigned short);

        static Coordinates fromPair(const std::pair<unsigned short, unsigned short>&);
        std::pair<unsigned short, unsigned short> toPair() const;

        bool operator==(const Coordinates&) const;
        bool operator!=(const Coordinates&) const;
        bool operator<(const Coordinates&) const;
        Coordinates operator+(const Coordinates&) const;
        Coordinates operator-(const Coordinates&) const;
        Coordinates operator*(const unsigned short) const;
        Coordinates operator+=(const Coordinates&);
        Coordinates operator-=(const Coordinates&);
    };

``Coordinates`` also supports hashing through a template specialization of ``std::hash``.

``cursor.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/coordinates.hpp>`_ contains the following constants:

+--------------+--------------+-----------------------------+
| Constant     | Value        | Description                 |
+==============+==============+=============================+
| CHA          | 'H'          | Cursor Horizontal Absolute  |
+--------------+--------------+-----------------------------+
| VPA          | 'd'          | Vertical Position Absolute  |
+--------------+--------------+-----------------------------+

This header also contains the following function.

.. code-block:: cpp

    void clearScreen();

This header also contains the following enums based on the `ANSI escape codes <https://en.wikipedia.org/wiki/ANSI_escape_code>`_

.. code-block:: cpp

    enum class EraseScreen : int;
    enum class EraseLine : int;
    enum class MoveCursor : char;
    enum class MoveCursorDEC : int;
    enum class MoveCursorSCO : char;

This header also contains the following struct used to represent the cursor of the terminal.

.. code-block:: cpp

    struct Cursor {
        const static unsigned short int offset_y;
        const static unsigned short int offset_x;

        Cursor();
        ~Cursor();

        void goTo(unsigned short int, unsigned short int) const;
        void goTo(Coordinates) const;

        void eraseScreen(EraseScreen) const;
        void eraseLine(EraseLine) const;
        void move(MoveCursor, unsigned short int) const;
        void move(MoveCursorDEC) const;
        void move(MoveCursorSCO) const;
    };

The coordinates are 0-based like in the ``Coordinates`` struct, they will be adapted to the ``{3, 2}``-based coordinates of the terminal when printed.

``field.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/field.hpp>`_ contains the following enum used to represent the movement of a pawn when it tries to move out of the field boundaries.

.. code-block:: cpp

    enum class Effect { // Effect enum - effect when a coordinate overflows
        PACMAN = 0, // Pacman effect when a coordinate overflows
        MATRIX = 1 // Classic C style matrix effect when a coordinate overflows
    };

This header also contains the following "abstract" class used to represent a field.

.. code-block:: cpp

    class Field {
    protected:
        std::vector<std::vector<std::shared_ptr<Pawn>>> pawns; // Matrix of pawns
        Cursor cursor; // Cursor
        int width; // Width of the matrix
        int height; // Height of the matrix
    
    public:
        Field(int, int);
        ~Field();
    
        void clear();
        void reset();
        void print() const;
        void print(char) const;
        void print(Border&) const;
    
        virtual void addPawn(std::shared_ptr<Pawn>);
        virtual void removePawn(Pawn*);
        void addPrintPawn(std::shared_ptr<Pawn>);
        void rePrintPawn(Pawn*);
        Pawn* getPawn(Coordinates&);

        void movePawn(Pawn*, Coordinates&);
        void movePawnBy(Pawn*, Coordinates&);
        void movePawnBy(Pawn*, Coordinates&, bool);
        void movePawnFromTo(Coordinates&, Coordinates&);

        Coordinates movingByCoordinates(Pawn*, short int, short int);
        Coordinates movingByCoordinates(Pawn*, short int, short int, Effect);

        bool isOccupied(Coordinates&) const;
        bool isOutOfBounds(Coordinates&) const;
        bool isFree(Coordinates&) const;
        void validateCoordinates(Coordinates&) const;
    };

ℹ️ - All the methods with a ``Coordinates&`` argument can use a ``Coord`` typedef or two ``unsigned short`` instead.

When using a ``SwappableField``, the movement of a ``Pawn`` can be queued using a ``Path`` object.

.. code-block:: cpp

    struct Path { // Path struct - begin and end Coordinates of a path
        static int current_priority; // current_priority - priority of the current Path [counter]
        int priority; // priority - priority of the Path (used in operator<)
        Coordinates begin;
        Coordinates end;
        Pawn* pawn; // pawn - the pawn that is moving along the path

        Path(Coordinates, Coordinates, Pawn*);

        bool operator|(const Path& other) const;
        bool operator<(const Path& other) const;
    };

Then the ``SwappableField`` class can be used to represent a field with some useful function to handle cell-conflicts.

.. code-block:: cpp
    
    class SwappableField: public Field {
    private:
        std::vector<std::vector<short int>> pawnsCount;
        std::vector<Path> pawnsToSwap;
        Coordinates firstInvalidCell(std::vector<std::vector<short int>>&);
    
    public:
        SwappableField(int, int);
        ~SwappableField();
    
        void addPawn(std::shared_ptr<Pawn>);
        void removePawn(Pawn*);
        void clearPawnsToSwap();

        void addPawnToSwap(Pawn*, Coordinates&);
        void addPawnToSwap(Path&);
        void applySwaps();
        void swapTwoPawns(Coordinates&, Coordinates&);
        void swapTwoPawns(Pawn*, Pawn*);
    };

``pawn.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/pawn.hpp>`_ contains the following "abstract" class used to represent a pawn.

.. code-block:: cpp

    class Pawn {
    protected:
        char symbol;
        Coordinates coordinates;
        ANSISettings settings;

    public:
        Pawn(char, const Coordinates&, const ANSISettings&);
        virtual ~Pawn();

        virtual void print();
    };

It comes with getters and setters for its attributes.

``sista.hpp``
================

This `header <https://github.com/FLAK-ZOSO/Sista/blob/main/include/sista/sista.hpp>`_ includes all the other headers.

.. code-block:: cpp

    #include "ansi.hpp" // ForegroundColor, BackgroundColor, Attribute, ANSISettings
    #include "border.hpp" // Border
    #include "coordinates.hpp" // Coordinates, <utility>
    #include "pawn.hpp" // Pawn
    #include "field.hpp" // Field, Path, SwappableField
    #include "cursor.hpp" // Cursor, clearScreen [cross-platform since v0.6.0]