This documentation is kept for historical reasons, the up-to-date documentation is available at: 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 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:

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:

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

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:

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

border.hpp

This header contains the following class used to represent the border of a field.

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 contains the following struct used to represent the coordinates of a Pawn.

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 contains the following constants:

Constant	Value	Description
CHA	‘H’	Cursor Horizontal Absolute
VPA	‘d’	Vertical Position Absolute

This header also contains the following function.

void clearScreen();

This header also contains the following enums based on the ANSI escape codes

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.

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 contains the following enum used to represent the movement of a pawn when it tries to move out of the field boundaries.

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.

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.

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.

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 contains the following “abstract” class used to represent a pawn.

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 includes all the other headers.

#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]