#pragma once

/// \file entity.h
/// \author Folling <mail@folling.io>

/// \defgroup entities Entities
/// \brief Entities are the core building blocks of Ikarus.

#include <ikarus/errors.h>
#include <ikarus/macros.h>
#include <ikarus/stdtypes.h>

struct IkarusProject;
struct IkarusEntity;
struct IkarusProperty;

IKARUS_BEGIN_HEADER

/// \brief Entities are the core building blocks of Ikarus.
/// \details Entities store a number of values associated with a name or property.
///
/// For documentation on the types and layout of values \see values.h.
///
/// Entities can be linked to blueprints.
/// The entity has a (possibly uninitialized) value for each property of all
/// blueprints it is linked to. \see property.h \see blueprint.h.
///
/// We distinguish between `EntityValues` and `EntityPropertyValues`.
/// `EntityValues` are a direct part of the entity.
/// `EntityPropertyValues` are an indirect part of the entity, linked to them
/// via a blueprint.
struct IkarusEntity;

/// \brief Flags for creating an entity.
enum IkarusEntityCreateFlags {
	/// \brief No flags.
	IkarusEntityCreateFlags_None = 0,
};

/// \brief Checks whether an entity exists.
/// \param entity The entity to check.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return True if the entity exists, false otherwise or if an error occurs.
IKA_API bool ikarus_entity_exists(struct IkarusEntity * entity, struct IkarusErrorData * error_out);

/// \brief Creates a new entity.
/// \param project The project to create the entity in.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The name of the entity.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param flags Flags for creating the entity.
/// \param error_out \see errors.h
/// \return The created entity or null if an error occurs.
IKA_API struct IkarusEntity * ikarus_entity_create(
	struct IkarusProject * project,
	char const * name,
	enum IkarusEntityCreateFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Flags for deleting an entity.
enum IkarusEntityDeleteFlags {
	/// \brief No flags.
	IkarusEntityDeleteFlags_None = 0,
};

/// \brief Deletes an entity and its values.
/// \param entity The entity to delete.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param flags Flags for deleting the entity.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_delete(
	struct IkarusEntity * entity,
	enum IkarusEntityDeleteFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Flags for copying an entity.
enum IkarusEntityCopyFlags {
	/// \brief No flags.
	IkarusEntityCopyFlags_None = 0,
};

/// \brief Copies an entity.
/// \param entity The entity to copy.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param flags Flags for copying the entity.
/// \param error_out \see errors.h
/// \return The copied entity or null if an error occurs.
IKA_API struct IkarusEntity *
ikarus_entity_copy(struct IkarusEntity * entity, enum IkarusEntityCopyFlags flags, struct IkarusErrorData * error_out);

/// \brief Gets the project an entity belongs to.
/// \param entity The entity to get the project of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The project the entity belongs to.
IKA_API struct IkarusProject *
ikarus_entity_get_project(struct IkarusEntity * entity, struct IkarusErrorData * error_out);

/// \brief Gets the name of an entity.
/// \param entity The entity to get the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The name of the entity.
IKA_API char const * ikarus_entity_get_name(struct IkarusEntity * entity, struct IkarusErrorData * error_out);

/// \brief Flags for setting the name of an entity.
enum IkarusEntitySetNameFlags {
	/// \brief No flags.
	IkarusEntitySetNameFlags_None = 0,
};

/// \brief Sets the name of an entity.
/// \param entity The entity to set the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The new name of the entity.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param flags Flags for setting the name of the entity.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_set_name(
	struct IkarusEntity * entity,
	char const * name,
	enum IkarusEntitySetNameFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Gets whether an entity is linked to a blueprint.
/// \param entity The entity to check the blueprint of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param blueprint The blueprint to check the entity's link to.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \pre \li Must be in the same project as the entity.
/// \param error_out \see errors.h
/// \return True if the entity is linked to the blueprint, false otherwise or if an error occurs.
IKA_API bool ikarus_entity_is_linked_to_blueprint(
	struct IkarusEntity * entity,
	struct IkarusBlueprint * blueprint,
	struct IkarusErrorData * error_out
);

/// \brief Gets the blueprints an entity is linked to.
/// \param entity The entity to get the blueprints of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param size_out An out parameter for the number of blueprints in the returned array
/// or undefined if an error occurs.
/// \param error_out \see errors.h
IKA_API struct IkarusBlueprint ** ikarus_entity_get_linked_blueprints(
	struct IkarusEntity * entity,
	size_t * size_out,
	struct IkarusErrorData * error_out
);

/// \brief Gets the number of blueprints an entity is linked to.
/// \param entity The entity to get the number of linked blueprints of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The number of linked blueprints or 0 if an error occurs.
IKA_API size_t
ikarus_entity_get_linked_blueprints_count(struct IkarusEntity * entity, struct IkarusErrorData * error_out);

/// \brief Flags for linking an entity to a blueprint.
enum IkarusEntityLinkBlueprintFlags {
	/// \brief No flags.
	IkarusEntityLinkBlueprintFlags_None = 0,
};

/// \brief Links an entity to a blueprint.
/// \details An uninitialized (default) value is created for each property of the
/// blueprint.
/// \param entity The entity to link the blueprint to.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param blueprint The blueprint to link to.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \pre \li Must be in the same project as the entity.
/// \remark If the entity is already linked to the blueprint, nothing happens.
/// \param flags Flags for linking the entity to the blueprint.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_link_blueprint(
	struct IkarusEntity * entity,
	struct IkarusBlueprint * blueprint,
	enum IkarusEntityLinkBlueprintFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Flags for unlinking an entity from a blueprint.
enum IkarusEntityUnlinkBlueprintFlags {
	/// \brief No flags.
	IkarusEntityUnlinkBlueprintFlags_None = 0,
};

/// \brief Unlinks an entity from a blueprint.
/// \details All values associated with the blueprint are deleted.
/// \param entity The entity to unlink the blueprint from.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param blueprint The blueprint to unlink from.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \pre \li Must be in the same project as the entity.
/// \remark If the entity is not linked to the blueprint, nothing happens.
/// \param flags Flags for unlinking the entity from the blueprint.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_unlink_blueprint(
	struct IkarusEntity * entity,
	struct IkarusBlueprint * blueprint,
	enum IkarusEntityUnlinkBlueprintFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Gets whether an entity has a value.
/// \param entity The entity to check the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The value's name.
/// \pre \li Must not be null.
/// \param error_out \see errors.h
/// \return True if the entity has a value with the name, false otherwise or if an error occurs.
IKA_API bool
ikarus_entity_has_value(struct IkarusEntity * entity, char const * name, struct IkarusErrorData * error_out);

/// \brief Struct for an entity value.
struct IkarusEntityValue {
	/// \brief The name of the value.
	char const * name;
	/// \brief The value in json format. \see value.h
	char const * value;
};

/// \brief Gets the values of an entity.
/// \param entity The entity to get the values of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param size_out An out parameter for the number of values in the returned array
/// or undefined if an error occurs.
/// \param error_out \see errors.h
/// \return The values or null if an error occurs.
IKA_API struct IkarusEntityValue *
ikarus_entity_get_values(struct IkarusEntity * entity, size_t * size_out, struct IkarusErrorData * error_out);

/// \brief Gets a value of an entity.
/// \param entity The entity to get the value of.
///	\pre \li Must not be null.
///	\pre \li Must exist.
///	\param name The value's name.
///	\pre \li Must not be null.
///	\pre \li Must exist.
/// \param error_out \see errors.h
/// \return The value, in json format of or null if an error occurs. \see value.h
IKA_API char const *
ikarus_entity_get_value(struct IkarusEntity * entity, char const * name, struct IkarusErrorData * error_out);

/// \brief Flags for setting a value of an entity.
enum IkarusEntitySetValueFlags {
	/// \brief No flags.
	IkarusEntitySetValueFlags_None = 0,
};

/// \brief Sets a value of an entity.
/// \details If no value exists for the name, a new one is created.
/// Any previous value is overwritten.
/// \param entity The entity to set the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The value's name.
/// \pre \li Must not be null.
/// \param value The value to set.
/// \pre \li Must not be null.
/// \pre \li Must be a valid json representation of a value. \see value.h
/// \param flags Flags for setting the value.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_set_value(
	struct IkarusEntity * entity,
	char const * name,
	char const * value,
	enum IkarusEntitySetValueFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Flags for deleting a value of an entity.
enum IkarusEntityDeleteValueFlags {
	/// \brief No flags.
	IkarusEntityDeleteValueFlags_None = 0,
};

/// \brief Deletes a value of an entity.
/// \param entity The entity to delete the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The property's name to delete the value of.
/// \pre \li Must not be null.
/// \pre \li Must be the name of a value which exists within the property.
/// \param flags Flags for deleting the value.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_delete_value(
	struct IkarusEntity * entity,
	char const * name,
	enum IkarusEntityDeleteValueFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Gets whether an entity has a property value.
/// \param entity The entity to check the property value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param property The property to check the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \pre \li Must be in the same project as the entity.
/// \param error_out \see errors.h
/// \return True if the entity has a value for the property, false otherwise or if an error occurs.
IKA_API bool ikarus_entity_has_property_value(
	struct IkarusEntity * entity,
	struct IkarusProperty * property,
	struct IkarusErrorData * error_out
);

/// \brief Struct for an entity property value.
struct IkarusEntityPropertyValue {
	/// \brief The property.
	struct IkarusProperty * property;
	/// \brief The value in json format. \see value.h
	char const * value;
};

/// \brief Gets the property values of an entity.
/// \param entity The entity to get the property values of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param size_out An out parameter for the number of property values in the
/// returned array or undefined if an error occurs.
/// \param error_out \see errors.h
/// \return The property values, or null if an error occurs.
IKA_API struct IkarusEntityPropertyValue *
ikarus_entity_get_property_values(struct IkarusEntity * entity, size_t * size_out, struct IkarusErrorData * error_out);

/// \brief Gets the value of a property of an entity.
///	\param entity The entity to get the value of.
///	\pre \li Must not be null.
///	\pre \li Must exist.
///	\param property The property to get the value of.
///	\pre \li Must not be null.
///	\pre \li Must exist.
///	\pre \li Must be linked to the entity.
///	\param error_out \see errors.h
///	\return The value, in json format of or null if an error occurs. \see
/// value.h
IKA_API char const * ikarus_entity_get_property_value(
	struct IkarusEntity * entity,
	struct IkarusProperty * property,
	struct IkarusErrorData * error_out
);

/// \brief Flags for setting the value of a property of an entity.
enum IkarusEntitySetPropertyValueFlags {
	/// \brief No flags.
	IkarusEntitySetPropertyValueFlags_None = 0,
};

/// \brief Sets the value of a property of an entity.
/// \details Any previous value is overwritten.
/// \param entity The entity to set the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param property The property to set the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \pre \li Must be linked to the entity.
/// \param value The value to set.
/// \pre \li Must not be null.
/// \pre \li Must be a valid json representation of a value. \see value.h
/// \pre \li Must be valid for the property's schema. \see schema.h
/// \param flags Flags for setting the property value.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_set_property_value(
	struct IkarusEntity * entity,
	struct IkarusProperty * property,
	char const * value,
	enum IkarusEntitySetPropertyValueFlags flags,
	struct IkarusErrorData * error_out
);

/// \brief Flags for clearing the value of a property of an entity.
enum IkarusEntityClearPropertyValueFlags {
	/// \brief No flags.
	IkarusEntityClearPropertyValueFlags_None = 0,
};

/// \brief Clears the value of a property of an entity.
/// \param entity The entity to clear the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param property The property to clear the value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \pre \li Must be linked to the entity.
/// \param flags Flags for clearing the property value.
/// \param error_out \see errors.h
IKA_API void ikarus_entity_clear_property_value(
	struct IkarusEntity * entity,
	struct IkarusProperty * property,
	enum IkarusEntitySetPropertyValueFlags flags,
	struct IkarusErrorData * error_out
);

IKARUS_END_HEADER

/// @}