#pragma once

// IMPLEMENTATION_DETAIL_LAZY_VALUE_CREATION

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

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

/// \defgroup properties Properties
/// \brief Properties define the structure and types of data.
/// @{

IKARUS_BEGIN_HEADER

/// \brief Properties are the placeholders of values for entities.
/// \details Each entity can have any number of properties.
/// Every property has a type that identifies the kind of data that can be put in.
///
/// The following types currently exist:
/// - Toggle: A true/false boolean-like value
/// - Number: An arbitrary numeric value
/// - Text: An arbitrary textual value
///
/// Property Examples:
/// - Is Dead (Toggle)
/// - Age (Number)
/// - ISBN (Text)
///
/// Every property has settings which can be used to customise the property further.
/// Two settings that are shared among all properties are the following:
/// - Multiple
/// - Allow undefined
///
/// The former transforms a property into a list. Instead of one number, you could then specify a series of numbers.
/// The latter allows you to specify an "unknown" value for a property.
/// It might not be known if a character is dead or not for example.
///
/// Each entity associated with the property has a value for it.
///
/// Properties can also be added to blueprints in which case they are available for all entities associated with the
/// blueprint.
///
/// We call properties within entities "Entity Properties" and properties within blueprints "Blueprint Properties".
///
/// \remark Properties are scoped to the blueprint or entity they are associated with.
/// \remark Values for properties are lazily created as space saving measure.
/// Fetching the value for some property of some entity will return the property's default value if none is specified.
/// This default value is specified when the property is created and can be updated later.
/// \remark Properties' tree structures are scoped to the entity or blueprint they are associated with.
struct IkarusProperty;

/// \brief Creates a property
/// \param project The project the property is part of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param property_source The property source the property is part of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The name of the property.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param property_info The info of the property.
/// \pre \li Must not be null.
/// \return The created property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusProperty * ikarus_property_create(
    struct IkarusProject * project,
    struct IkarusPropertySource * property_source,
    char const * name,
    struct IkarusPropertyTypeInfo * property_info
);

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

/// \brief Gets the type info of a property.
/// \param property The property to get the type info of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The type info of the property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusPropertyTypeInfo * ikarus_property_get_type_info(IkarusProperty const * property);

/// \brief Gets the source of a property.
/// \param property The property to get the source of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The source of the property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusPropertySource * ikarus_property_get_source(IkarusProperty const * property);

/// \brief Gets the default value of a property.
/// \param property The property to get the default value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The default value of the property or null if an error occurs.
/// \remark Must be freed using #ikarus_free.
IKA_API struct IkarusValue * ikarus_property_get_default_value(IkarusProperty const * property);

/// \brief Sets the type info of a property and resets all values to the new default value.
/// \param property The property to set the type info of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param new_type The new type info of the property.
/// \param attempt_conversion Whether to attempt to convert the property's values to the new type info. Conversion rules are
/// unspecified for now, but follow common sense.
IKA_API void ikarus_property_set_type_info(
    IkarusProperty * property, struct IkarusPropertyTypeInfo new_type_info, bool attempt_conversion
);

/// \brief Casts a property to an object.
/// \param property The property to cast.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \return The property represented as an object or null if an error occurs.
/// \remark This operation is guaranteed to be very fast and is intended to be used frequently.
IKA_API struct IkarusObject * ikarus_property_to_object(IkarusProperty const * property);

IKARUS_END_HEADER

// @}