#pragma once

/// \file blueprint.h
/// \author Folling <folling@ikarus.world>

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

/// \defgroup blueprints Blueprints
/// \brief Blueprints are templates for entities.
/// @{

IKARUS_BEGIN_HEADER

/// \brief A blueprint object.
/// \details  A blueprint is a collection of properties which can be linked to entities.
/// Each entity the blueprint is linked to will have values for the blueprints properties.q
struct IkarusBlueprint;

/// \brief Creates a blueprint.
/// \param project The project the blueprint is part of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param parent The parent folder of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the blueprint in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \return The created blueprint or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API IkarusBlueprint * ikarus_blueprint_create(
    struct IkarusProject * project, struct IkarusBlueprintFolder * parent, size_t position, char const * name
);

/// \brief Creates a blueprint from an entity.
/// \details The created blueprint will have the same properties as the entity.
/// \param entity The entity to create the blueprint from.
/// \pre \li Must not be null.
/// \param link_entity If true, the entity will be linked to the blueprint. If not they will remain separate.
/// \param parent The parent folder of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the blueprint in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the blueprint. Must not be empty.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \return The created blueprint or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API IkarusBlueprint * ikarus_blueprint_create_from_entity(
    struct IkarusEntity * entity, bool link_entity, struct IkarusBlueprintFolder * parent, size_t position, char const * name
);

/// \brief Copies a blueprint.
/// \details Creates a deep copy of the blueprint including all of its properties.
/// \param blueprint The blueprint to copy.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param parent The parent folder of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param position The position of the blueprint in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \param name The name of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \return The created blueprint or null if an error occurs.
/// \remark Linked entities won't be copied.
/// \remark Must be freed using #ikarus_free.
IKA_API IkarusBlueprint * ikarus_blueprint_copy(
    IkarusBlueprint const * blueprint, struct IkarusBlueprintFolder * parent, size_t position, char const * name
);

/// \brief Deletes a blueprint.
/// \param blueprint The blueprint to delete.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \remark The blueprint must not be accessed after deletion.
IKA_API void ikarus_blueprint_delete(IkarusBlueprint * blueprint);

/// \brief Gets the project of a blueprint.
/// \param blueprint The blueprint to get the project of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The project of the blueprint or null if an error occurs.
IKA_API struct IkarusProject * ikarus_blueprint_get_project(IkarusBlueprint const * blueprint);

/// \brief Gets the parent folder of a blueprint.
/// \param blueprint The blueprint to get the parent folder of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The parent folder of the blueprint or null if an error occurs.
IKA_API struct IkarusBlueprintFolder * ikarus_blueprint_get_parent(IkarusBlueprint const * blueprint);

/// \brief Gets the position of a blueprint within its parent folder.
/// \param blueprint The blueprint to get the position of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The position of the blueprint or undefined if an error occurs.
IKA_API size_t ikarus_blueprint_get_position(IkarusBlueprint const * blueprint);

/// \brief Gets the name of a blueprint.
/// \param blueprint The blueprint to get the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The name of the blueprint or null if an error occurs.
/// \remark The returned pointer is valid until the blueprint is freed but may be invalidated by other operations.
IKA_API char const * ikarus_blueprint_get_name(IkarusBlueprint const * blueprint);

/// \brief Gets the property root folder of a blueprint.
/// \param blueprint The blueprint to get the root folder of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The root folder of all properties of the blueprint or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusPropertyFolder * ikarus_blueprint_get_property_root_folder(IkarusBlueprint const * blueprint);

/// \brief Gets the number of properties of a blueprint.
/// \param blueprint The blueprint to get the number of properties of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The number of properties or undefined if an error occurs.
IKA_API size_t ikarus_blueprint_get_property_count(IkarusBlueprint const * blueprint);

/// \brief Gets the properties of a blueprint.
/// \param blueprint The blueprint to get the properties of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param properties_out The buffer to write the properties to.
/// \pre \li Must not be null.
/// \param properties_out_size The size of the buffer.
IKA_API void ikarus_blueprint_get_properties(
    IkarusBlueprint const * blueprint, struct IkarusProperty ** properties_out, size_t properties_out_size
);

/// \brief Gets the number of entities linked to a blueprint.
/// \param blueprint The blueprint to get the number of linked entities of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The number of linked entities or undefined if an error occurs.
IKA_API size_t ikarus_blueprint_get_linked_entity_count(IkarusBlueprint const * blueprint);

/// \brief Gets the entities linked to a blueprint.
/// \param blueprint The blueprint to get the linked entities of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param entities_out The buffer to write the entities to.
/// \pre \li Must not be null.
/// \param entities_out_size The size of the buffer.
IKA_API void ikarus_blueprint_get_linked_entities(
    IkarusBlueprint const * blueprint, struct IkarusEntity ** entities_out, size_t entities_out_size
);

/// \brief Sets the parent folder of a blueprint.
/// \param blueprint The blueprint to set the parent folder of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_parent The new parent folder of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_position The new position of the blueprint in the parent folder. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \remark This adjusts the positions of old and new siblings.
IKA_API void ikarus_blueprint_set_parent(
    IkarusBlueprint * blueprint, struct IkarusBlueprintFolder * new_parent, size_t new_position
);

/// \brief Sets the position of a blueprint within its parent folder.
/// \param blueprint The blueprint to set the position of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_position The new position of the blueprint. \see #FolderPosition
/// \pre \li Must be within bounds for the parent folder.
/// \remark This adjusts the positions of siblings.
IKA_API void ikarus_blueprint_set_position(IkarusBlueprint * blueprint, size_t new_position);

/// \brief Sets the name of a blueprint.
/// \param blueprint The blueprint to set the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_name The new name of the blueprint.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
IKA_API void ikarus_blueprint_set_name(IkarusBlueprint * blueprint, char const * new_name);

/// \brief Converts a blueprint to an object.
/// \param blueprint The blueprint to convert.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The constructed object, representing the blueprint.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusObject * ikarus_blueprint_to_object(IkarusBlueprint const * blueprint);

/// \brief Compares two blueprints.
/// \param left The left blueprint to compare.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param right The right blueprint to compare.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return True if the two blueprints are equal, false otherwise.
/// \remark This neither performs a pointer comparison nor a deep comparison. When we say "equal" we mean that the two
/// blueprints reference the same blueprint in the same project.
IKA_API bool ikarus_blueprint_is_equal(IkarusBlueprint const * left, IkarusBlueprint const * right);

IKARUS_END_HEADER

// @}