#pragma once

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

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

/// \defgroup projects Projects
/// \brief Projects are the persistence mechanism of Ikarus. Each project contains a set of objects.
/// \details Projects are stored on the filesystem. Each project has a name.
/// @{

IKARUS_BEGIN_HEADER

/// \brief An Ikarus project.
/// \details A project may only be open once at a time. Opening a project from two different locations Gets undefined
/// behavior.
struct IkarusProject;

/// \brief Creates a persisted project on the filesystem.
/// \param path The path to the project.
/// \pre \li Must not be null.
/// \pre \li Must point to a valid unused path on the system.
/// \param name The name of the project. Must neither be null nor empty.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
/// \return The created project or null if an error occurs.
/// \remark Must be freed using #ikarus_free. Freeing does not delete the project from the filesystem. For that, use
/// ikarus_project_delete
IKA_API IkarusProject * ikarus_project_create(char const * path, char const * name, IkarusErrorData * error_out);

/// \brief Creates a project in memory.
/// \param name The name of the project. Must neither be null nor empty.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
/// \return The created project or null if an error occurs.
/// \remark Must be freed using #ikarus_free. Freeing does not delete the project from the filesystem. For that, use
/// ikarus_project_delete
IKA_API IkarusProject * ikarus_project_create_in_memory(char const * name, IkarusErrorData * error_out);

/// \brief Opens an existing project.
/// \param path The path to the project.
/// \pre \li Must not be null.
/// \pre \li Must point to an existing project on the system.
/// \param error_out \see errors.h
/// \return The opened project or null if an error occurs.
/// \remark Must be freed using ikarus_free. Freeing does not delete the project from the filesystem. For that, use
/// ikarus_project_delete
IKA_API IkarusProject * ikarus_project_open(char const * path, IkarusErrorData * error_out);

/// \brief Gets the name of a project.
/// \param project The project 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 project.
/// \remark Ownership remains with libikarus, must not be freed.
IKA_API char const * ikarus_project_get_name(IkarusProject const * project, IkarusErrorData * error_out);

/// \brief Sets the name of a project.
/// \param project The project to set the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_name The new name of the project.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
IKA_API void ikarus_project_set_name(IkarusProject * project, char const * new_name, IkarusErrorData * error_out);

/// \brief Gets the path of a project.
/// \param project The project to get the path of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The path of the project.
/// \remark Ownership remains with libikarus, must not be freed.
IKA_API char const * ikarus_project_get_path(IkarusProject const * project, IkarusErrorData * error_out);

/// \brief Gets the entities of a project.
/// \param project The project to get the 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.
/// \param error_out \see errors.h
IKA_API void ikarus_project_get_entities(
    IkarusProject * project,
    struct IkarusEntity ** entities_out,
    size_t entities_out_size,
    IkarusErrorData * error_out
);

/// \brief Gets the number of entities of a project.
/// \param project The project to get the number of entities of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The number of entities or undefined if an error occurs.
IKA_API size_t ikarus_project_get_entity_count(IkarusProject * project, IkarusErrorData * error_out);

/// \brief Gets the blueprints of a project.
/// \param project The project to get the blueprints of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param blueprints_out The buffer to write the blueprints to.
/// \pre \li Must not be null.
/// \param blueprints_out_size The size of the buffer.
/// \param error_out \see errors.h
IKA_API void ikarus_project_get_blueprints(
    IkarusProject * project,
    struct IkarusBlueprint ** blueprints_out,
    size_t blueprints_out_size,
    IkarusErrorData * error_out
);

/// \brief Gets the number of blueprints of a project.
/// \param project The project to get the number of blueprints of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The number of blueprints or undefined if an error occurs.
IKA_API size_t ikarus_project_get_blueprint_count(IkarusProject const * project, IkarusErrorData * error_out);

/// \brief Finds an entity by a given name.
/// \param project The project to search.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The name to search for.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
/// \return The entity with the given name or null if none was found.
IKA_API struct IkarusEntity* get_entity_by_name(
    IkarusProject const * project,
    char const * name,
    IkarusErrorData * error_out
);

/// \brief Finds a property by a given name.
/// \param project The project to search.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param scope The scope of the property.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \remark Property names are unique only within their scope.
/// \param name The name to search for.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
/// \return The property with the given name or null if none was found.
IKA_API struct IkarusProperty *
get_property_by_name(IkarusProject const * project, struct IkarusPropertyScope * scope, char const * name, IkarusErrorData * error_out);

/// \brief Finds a blueprint by a given name.
/// \param project The project to search.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The name to search for.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
/// \return The blueprint with the given name or null if none was found.
IKA_API struct IkarusBlueprint * get_blueprints_by_name(IkarusProject const * project, char const * name, IkarusErrorData * error_out);

IKARUS_END_HEADER

/// @}