C API for Sista library. More...

#include <stddef.h>

Include dependency graph for api.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	sista_RGBColor
	Represents an RGB color with red, green, and blue components. More...

struct	sista_Coordinates
	Represents a pair of coordinates (y, x). More...

Typedefs
typedef struct sista_Field *	FieldHandler_t

typedef struct sista_SwappableField *	SwappableFieldHandler_t

typedef struct sista_ANSISettings *	ANSISettingsHandler_t

typedef struct sista_Border *	BorderHandler_t

typedef struct sista_Pawn *	PawnHandler_t

Enumerations
enum	sista_ForegroundColor { F_BLACK = 30 , F_RED = 31 , F_GREEN = 32 , F_YELLOW = 33 , F_BLUE = 34 , F_MAGENTA = 35 , F_CYAN = 36 , F_WHITE = 37 }
	Predefined foreground colors for terminal text. More...

enum	sista_BackgroundColor { B_BLACK = 40 , B_RED = 41 , B_GREEN = 42 , B_YELLOW = 43 , B_BLUE = 44 , B_MAGENTA = 45 , B_CYAN = 46 , B_WHITE = 47 }
	Predefined background colors for terminal text. More...

enum	sista_Attribute { A_RESET = 0 , A_BRIGHT = 1 , A_FAINT = 2 , A_ITALIC = 3 , A_UNDERLINE = 4 , A_BLINK = 5 , A_BLINK_FAST = 6 , A_REVERSE = 7 , A_HIDDEN = 8 , A_STRIKETHROUGH = 9 }
	Text attributes for terminal text. More...

Functions
FieldHandler_t	sista_createField (size_t, size_t)
	Creates a Field with the specified width and height.

void	sista_printField (FieldHandler_t, char)
	Prints the specified Field with a given border.

void	sista_destroyField (FieldHandler_t)
	Deallocates the Field from memory.

SwappableFieldHandler_t	sista_createSwappableField (size_t, size_t)
	Creates a SwappableField with the specified width and height.

void	sista_printSwappableField (SwappableFieldHandler_t, char)
	Prints the specified Field with a given border.

void	sista_destroySwappableField (SwappableFieldHandler_t)
	Deallocates the SwappableField from memory.

void	sista_resetAnsi ()
	Resets ANSI settings to default.

void	sista_setForegroundColor (enum sista_ForegroundColor)
	Sets the foreground color using a predefined color.

void	sista_setBackgroundColor (enum sista_BackgroundColor)
	Sets the background color using a predefined color.

void	sista_setAttribute (enum sista_Attribute)
	Sets a text attribute.

void	sista_resetAttribute (enum sista_Attribute)
	Resets a text attribute.

void	sista_setForegroundColorRGB (const struct sista_RGBColor *)
	Sets the foreground color using an RGB color.

void	sista_setBackgroundColorRGB (const struct sista_RGBColor *)
	Sets the background color using an RGB color.

ANSISettingsHandler_t	sista_createANSISettings (enum sista_ForegroundColor, enum sista_BackgroundColor, enum sista_Attribute)
	Creates an ANSISettings object.

ANSISettingsHandler_t	sista_createANSISettingsRGB (struct sista_RGBColor, struct sista_RGBColor, enum sista_Attribute)
	Creates an ANSISettings object.

void	sista_applyANSISettings (ANSISettingsHandler_t)
	Applies the ANSI settings to the terminal.

void	sista_destroyANSISettings (ANSISettingsHandler_t)
	Deallocates the ANSISettings from memory.

BorderHandler_t	sista_createBorder (char, ANSISettingsHandler_t)
	Creates a Border object.

void	sista_destroyBorder (BorderHandler_t)
	Deallocates the Border from memory.

void	sista_printFieldWithBorder (FieldHandler_t, BorderHandler_t)
	Prints the field with the specified border.

void	sista_printSwappableFieldWithBorder (SwappableFieldHandler_t, BorderHandler_t)
	Prints the field with the specified border.

PawnHandler_t	sista_createPawnInSwappableField (SwappableFieldHandler_t, char, ANSISettingsHandler_t, struct sista_Coordinates)
	Creates a Pawn object in a given field.

PawnHandler_t	sista_createPawnInField (FieldHandler_t, char, ANSISettingsHandler_t, struct sista_Coordinates)
	Creates a Pawn object in a given field.

int	sista_movePawn (FieldHandler_t, PawnHandler_t, struct sista_Coordinates)
	Moves the pawn to a new position.

int	sista_addPawnToSwap (SwappableFieldHandler_t, PawnHandler_t, struct sista_Coordinates)
	Adds the Pawn to a list of pawns to be moved ("swapped") later.

int	sista_applySwaps (SwappableFieldHandler_t)
	Executes all pending pawn swaps.

Detailed Description

C API for Sista library.

This header defines the C API for the Sista library, allowing interaction with core functionalities such as creating and managing SwappableFields and Pawns. The API is designed to be used in C programs, providing a bridge to the underlying C++ implementations and allowing for FFI usage with other programming languages thanks to ABI compatibility.

Note: This API is compatible with the C89 standard for maximum ABI stability.

Author: FLAK-ZOSO

Date: 2025

Version: 3.0.0

Copyright: GNU General Public License v3.0

Typedef Documentation

◆ ANSISettingsHandler_t

typedef struct sista_ANSISettings* ANSISettingsHandler_t

◆ BorderHandler_t

typedef struct sista_Border* BorderHandler_t

◆ FieldHandler_t

typedef struct sista_Field* FieldHandler_t

◆ PawnHandler_t

typedef struct sista_Pawn* PawnHandler_t

◆ SwappableFieldHandler_t

typedef struct sista_SwappableField* SwappableFieldHandler_t

Enumeration Type Documentation

◆ sista_Attribute

enum sista_Attribute

Text attributes for terminal text.

This enumeration defines a set of text attributes that can be used to modify the appearance of text in terminal applications using ANSI escape codes. Attributes include styles such as bold, italic, underline, and more.

See also: sista_setAttribute; sista_resetAttribute; sista::Attribute

Enumerator
A_RESET
A_BRIGHT
A_FAINT
A_ITALIC
A_UNDERLINE
A_BLINK
A_BLINK_FAST
A_REVERSE
A_HIDDEN
A_STRIKETHROUGH

◆ sista_BackgroundColor

enum sista_BackgroundColor

Predefined background colors for terminal text.

This enumeration defines a set of standard background colors that can be used to change the background color of text in terminal applications using ANSI escape codes.

See also: sista_setBackgroundColor; sista::BackgroundColor

Enumerator
B_BLACK
B_RED
B_GREEN
B_YELLOW
B_BLUE
B_MAGENTA
B_CYAN
B_WHITE

◆ sista_ForegroundColor

enum sista_ForegroundColor

Predefined foreground colors for terminal text.

This enumeration defines a set of standard foreground colors that can be used to change the color of text in terminal applications using ANSI escape codes.

See also: sista_setForegroundColor; sista::ForegroundColor

Enumerator
F_BLACK
F_RED
F_GREEN
F_YELLOW
F_BLUE
F_MAGENTA
F_CYAN
F_WHITE

Function Documentation

◆ sista_addPawnToSwap()

int sista_addPawnToSwap	(	SwappableFieldHandler_t	field,
		PawnHandler_t	pawn,
		struct sista_Coordinates	destination
	)

Adds the Pawn to a list of pawns to be moved ("swapped") later.

Parameters

field	The SwappableField containing the Pawn.
pawn	The Pawn to add to the swap list.
destination	The destination coordinates.

Returns: Status code

This function adds the specified Pawn to a list of pawns that will be moved (swapped) when sista_executeSwaps is called. The pawn will be moved to the specified destination coordinates.

Return values

0	If the pawn was successfully added to the swap list.
1	If adding the pawn to the swap list failed for any other reason.
2	If the destination is out of bounds.
3	If the destination is occupied by another pawn.
4	If the field is a nullptr.
5	If the pawn is a nullptr.

See also: sista::SwappableField::addPawnToSwap

◆ sista_applyANSISettings()

void sista_applyANSISettings ( ANSISettingsHandler_t settings )

Applies the ANSI settings to the terminal.

Parameters

settings The ANSISettings to apply.

This function applies the specified ANSI settings to the terminal by outputting the corresponding ANSI escape codes to standard output.

See also: sista::ANSISettings::apply

◆ sista_applySwaps()

int sista_applySwaps ( SwappableFieldHandler_t field )

Executes all pending pawn swaps.

Parameters

field The SwappableField containing the pawns to swap.

Returns: Status code

This function executes all pending pawn swaps that have been added using sista_addPawnToSwap. It attempts to move each pawn to its specified destination, handling any conflicts or errors that arise.

Note: The swaps that cannot be applied (due to more than one pawn trying to move to the same destination, generally) are skipped.

Todo:: In future versions, the function may return a list of the swaps that could not be applied.

Return values

0	If all possible (read note) swaps were successful.
1	If executing the swaps failed for any other reason.

See also: sista::SwappableField::applySwaps

◆ sista_createANSISettings()

ANSISettingsHandler_t sista_createANSISettings	(	enum	sista_ForegroundColor,
		enum	sista_BackgroundColor,
		enum	sista_Attribute
	)

Creates an ANSISettings object.

Parameters

fgColor	The foreground color (predefined).
bgColor	The background color (predefined).
attribute	The text attribute to apply.

Returns: A handler to the created ANSISettings object.

This function allocates and initializes a new ANSISettings object. It returns a pointer that can be used to reference the ANSISettings in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned ANSISettings object, including deallocation if necessary.

See also: sista::ANSISettings; sista_destroyANSISettings

◆ sista_createANSISettingsRGB()

ANSISettingsHandler_t sista_createANSISettingsRGB	(	struct sista_RGBColor	,
		struct sista_RGBColor	,
		enum	sista_Attribute
	)

Creates an ANSISettings object.

Parameters

fgColor	The foreground color (RGB).
bgColor	The background color (RGB).
attribute	The text attribute to apply.

Returns: A handler to the created ANSISettings object.

This function allocates and initializes a new ANSISettings object. It returns a pointer that can be used to reference the ANSISettings in subsequent API calls. Unlike sista_createANSISettings, it takes RGB colors for foreground and background.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned ANSISettings object, including deallocation if necessary.

Note: While the API only accepts either predefined colors or RGB colors, the underlying implementation supports mixing both types. This would require two more functions to be exposed in the API.

See also: sista::ANSISettings; sista_destroyANSISettings

◆ sista_createBorder()

BorderHandler_t sista_createBorder	(	char	symbol,
		ANSISettingsHandler_t	settings
	)

Creates a Border object.

Parameters

symbol	The character symbol for the border brick.
settings	The ANSISettings to apply to the border brick.

Returns: A handler to the created Border object.

This function allocates and initializes a new Border object with the specified symbol and ANSI settings. It returns a pointer that can be used to reference the Border in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned Border object, including deallocation if necessary.

See also: sista::Border; sista_destroyBorder

◆ sista_createField()

FieldHandler_t sista_createField	(	size_t	width,
		size_t	height
	)

Creates a Field with the specified width and height.

Parameters

width	The width of the Field.
height	The height of the Field.

Returns: A handler to the created Field.

This function allocates and initializes a new Field object with the given dimensions. It returns a pointer that can be used to reference the Field in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned Field object, including deallocation if necessary.

See also: Field

◆ sista_createPawnInField()

PawnHandler_t sista_createPawnInField	(	FieldHandler_t	field,
		char	symbol,
		ANSISettingsHandler_t	settings,
		struct sista_Coordinates	position
	)

Creates a Pawn object in a given field.

Parameters

field	The Field to add the pawn to.
symbol	The character symbol for the pawn.
settings	The ANSISettings to apply to the pawn.
position	The initial position of the pawn.

Returns: A handler to the created Pawn object.

This function allocates and initializes a new Pawn object with the specified symbol, ANSI settings, and initial position. It returns a pointer that can be used to reference the Pawn in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: Unlike with other objects, the caller is NOT responsible for managing the lifetime of the returned Pawn object. Pawns are managed by the Field they are added to, and will be deallocated when the Field is destroyed.

See also: sista::Pawn; sista_destroyPawn

◆ sista_createPawnInSwappableField()

PawnHandler_t sista_createPawnInSwappableField	(	SwappableFieldHandler_t	field,
		char	symbol,
		ANSISettingsHandler_t	settings,
		struct sista_Coordinates	position
	)

Creates a Pawn object in a given field.

Parameters

field	The SwappableField to add the pawn to.
symbol	The character symbol for the pawn.
settings	The ANSISettings to apply to the pawn.
position	The initial position of the pawn.

Returns: A handler to the created Pawn object.

This function allocates and initializes a new Pawn object with the specified symbol, ANSI settings, and initial position. It returns a pointer that can be used to reference the Pawn in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: Unlike with other objects, the caller is NOT responsible for managing the lifetime of the returned Pawn object. Pawns are managed by the SwappableField they are added to, and will be deallocated when the SwappableField is destroyed.

See also: sista::Pawn; sista_destroyPawn

◆ sista_createSwappableField()

SwappableFieldHandler_t sista_createSwappableField	(	size_t	width,
		size_t	height
	)

Creates a SwappableField with the specified width and height.

Parameters

width	The width of the SwappableField.
height	The height of the SwappableField.

Returns: A handler to the created SwappableField.

This function allocates and initializes a new SwappableField object with the given dimensions. It returns a pointer that can be used to reference the SwappableField in subsequent API calls.

Return values

NULL	If memory allocation fails.

Warning: The caller is responsible for managing the lifetime of the returned SwappableField object, including deallocation if necessary.

See also: SwappableField

◆ sista_destroyANSISettings()

void sista_destroyANSISettings ( ANSISettingsHandler_t settings )

Deallocates the ANSISettings from memory.

Parameters

settings The ANSISettings to delete.

This function deallocates the ANSISettings from memory through the opaque handler pointing to it.

See also: sista::ANSISettings; sista_createANSISettings

◆ sista_destroyBorder()

void sista_destroyBorder ( BorderHandler_t border )

Deallocates the Border from memory.

Parameters

border The Border to delete.

This function deallocates the Border from memory through the opaque handler pointing to it.

See also: sista::Border; sista_createBorder

◆ sista_destroyField()

void sista_destroyField ( FieldHandler_t field )

Deallocates the Field from memory.

Parameters

field The Field to delete

This function deallocates the Field from memory through the opaque handler pointing to it.

See also: Field

◆ sista_destroySwappableField()

void sista_destroySwappableField ( SwappableFieldHandler_t field )

Deallocates the SwappableField from memory.

Parameters

field The SwappableField to delete

This function deallocates the SwappableField from memory through the opaque handler pointing to it.

See also: SwappableField

◆ sista_movePawn()

int sista_movePawn	(	FieldHandler_t	field,
		PawnHandler_t	pawn,
		struct sista_Coordinates	destination
	)

Moves the pawn to a new position.

Parameters

field	The Field containing the Pawn.
pawn	The Pawn to move.
destination	The destination coordinates.

Returns: Status code

Return values

0	If the move was successful.
1	If the move failed for any other reason.
2	If the destination is out of bounds.
3	If the destination is occupied by another pawn.
4	If the field is a nullptr.
5	If the pawn is a nullptr.

See also: sista::Field::movePawn

◆ sista_printField()

void sista_printField	(	FieldHandler_t	field,
		char	border
	)

Prints the specified Field with a given border.

Parameters

field	The Field.
border	The border character to use.

This function prints the entire field to the terminal, using the specified character as the border around the field.

See also: Field; Border

◆ sista_printFieldWithBorder()

void sista_printFieldWithBorder	(	FieldHandler_t	field,
		BorderHandler_t	border
	)

Prints the field with the specified border.

Parameters

field	The Field to print.
border	The Border to print.

This function prints the entire field to the terminal, using the specified Border object to draw the border around the field.

See also: sista::Border::print; sista::Field::print

◆ sista_printSwappableField()

void sista_printSwappableField	(	SwappableFieldHandler_t	field,
		char	border
	)

Prints the specified Field with a given border.

Parameters

field	The SwappableField.
border	The border character to use.

This function prints the entire field to the terminal, using the specified character as the border around the field.

See also: Field; Border

◆ sista_printSwappableFieldWithBorder()

void sista_printSwappableFieldWithBorder	(	SwappableFieldHandler_t	field,
		BorderHandler_t	border
	)

Prints the field with the specified border.

Parameters

field	The SwappableField to print.
border	The Border to print.

This function prints the entire field to the terminal, using the specified Border object to draw the border around the field.

See also: sista::Border::print; sista::Field::print

◆ sista_resetAnsi()

void sista_resetAnsi ( )

Resets ANSI settings to default.

This function resets the terminal's ANSI settings, including colors and attributes, to their default values.

See also: sista::resetAnsi

◆ sista_resetAttribute()

void sista_resetAttribute ( enum sista_Attribute )

Resets a text attribute.

Parameters

attribute The text attribute to reset.

This function resets a text attribute, such as bold or underline, specified in the sista_Attribute enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_Attribute; sista::resetAttribute

◆ sista_setAttribute()

void sista_setAttribute ( enum sista_Attribute )

Sets a text attribute.

Parameters

attribute The text attribute to set.

This function sets a text attribute, such as bold or underline, specified in the sista_Attribute enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_Attribute; sista::setAttribute

◆ sista_setBackgroundColor()

void sista_setBackgroundColor ( enum sista_BackgroundColor )

Sets the background color using a predefined color.

Parameters

color The predefined background color to set.

This function sets the terminal's background color to one of the predefined colors specified in the sista_BackgroundColor enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_BackgroundColor; sista::setBackgroundColor

◆ sista_setBackgroundColorRGB()

void sista_setBackgroundColorRGB ( const struct sista_RGBColor * color )

Sets the background color using an RGB color.

Parameters

color A pointer to a sista_RGBColor struct defining the color.

This function sets the terminal's background color using the RGB components specified in the provided sista_RGBColor struct. It outputs the corresponding ANSI escape code to standard output.

Note: The function takes no effect if the pointer is nullptr.

See also: sista_RGBColor; sista::setBackgroundColor

◆ sista_setForegroundColor()

void sista_setForegroundColor ( enum sista_ForegroundColor )

Sets the foreground color using a predefined color.

Parameters

color The predefined foreground color to set.

This function sets the terminal's foreground color to one of the predefined colors specified in the sista_ForegroundColor enumeration. It outputs the corresponding ANSI escape code to standard output.

See also: sista_ForegroundColor; sista::setForegroundColor

◆ sista_setForegroundColorRGB()

void sista_setForegroundColorRGB ( const struct sista_RGBColor * color )

Sets the foreground color using an RGB color.

Parameters

color A pointer to a sista_RGBColor struct defining the color.

This function sets the terminal's foreground color using the RGB components specified in the provided sista_RGBColor struct. It outputs the corresponding ANSI escape code to standard output.

Note: The function takes no effect if the pointer is nullptr.

See also: sista_RGBColor; sista::setForegroundColor

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ANSISettingsHandler_t

◆ BorderHandler_t

◆ FieldHandler_t

◆ PawnHandler_t

◆ SwappableFieldHandler_t

Enumeration Type Documentation

◆ sista_Attribute

◆ sista_BackgroundColor

◆ sista_ForegroundColor

Function Documentation

◆ sista_addPawnToSwap()

◆ sista_applyANSISettings()

◆ sista_applySwaps()

◆ sista_createANSISettings()

◆ sista_createANSISettingsRGB()

◆ sista_createBorder()

◆ sista_createField()

◆ sista_createPawnInField()

◆ sista_createPawnInSwappableField()

◆ sista_createSwappableField()

◆ sista_destroyANSISettings()

◆ sista_destroyBorder()

◆ sista_destroyField()

◆ sista_destroySwappableField()

◆ sista_movePawn()

◆ sista_printField()

◆ sista_printFieldWithBorder()

◆ sista_printSwappableField()

◆ sista_printSwappableFieldWithBorder()

◆ sista_resetAnsi()

◆ sista_resetAttribute()

◆ sista_setAttribute()

◆ sista_setBackgroundColor()

◆ sista_setBackgroundColorRGB()

◆ sista_setForegroundColor()

◆ sista_setForegroundColorRGB()