libikarus/include/ikarus/objects/property.h

#pragma once

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

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

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

IKARUS_BEGIN_HEADER

/// \brief Properties define the structure of blueprints.
/// \details Each blueprint can have any number of properties.
/// Every property has a type that identifies the kind of data that can be put
/// in. This is the "base class" of properties. See the derived types (e.g.
/// IkarusToggleProperty) for more information.
///
/// 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)
///
/// Each entity associated with the property has a value for it.
///
/// \remark Values for properties are lazily created to save space.
/// Fetching the value for some property of some entity will return the
/// property's default value if none is specified.
struct IkarusProperty;

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

/// \brief Flags for creating a property.
enum IkarusPropertyCreateFlags {
	/// \brief No flags.
	IkarusPropertyCreateFlags_None = 0,
};

/// \brief Create a new property.
/// \param project The project to create the property in.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param blueprint The blueprint to create the property for.
/// \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 schema The schema of the property.
/// \pre \li Must not be null.
/// \pre \li Must be a valid JSON buffer for a IkarusValueSchema. \see schema.h
/// \param default_value The default value of the property.
/// \pre \li Must not be null.
/// \pre \li Must be a valid JSON buffer for an IkarusValueData. \see data.h
/// \param flags Flags for creating the property.
/// \param error_out \see errors.h
/// \return The created property or NULL if an error occurred.
/// \remark Must only be deleted with #ikarus_property_delete.
IKA_API IkarusProperty * ikarus_property_create(
	struct IkarusBlueprint * blueprint,
	char const * name,
	char const * schema,
	char const * default_value,
	IkarusPropertyCreateFlags flags,
	IkarusErrorData * error_out
);

/// \brief Flags for copying a property.
enum IkarusPropertyCopyFlags {
	/// \brief No flags.
	IkarusPropertyCopyFlags_None = 0,
};

/// \brief Copy a property.
/// \param property The property to copy.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param flags Flags for copying the property.
/// \param error_out \see errors.h
/// \return The copied property or NULL if an error occurred.
IKA_API IkarusProperty *
ikarus_property_copy(IkarusProperty * property, IkarusPropertyCopyFlags flags, IkarusErrorData * error_out);

/// \brief Flags for deleting a property.
enum IkarusPropertyDeleteFlags {
	/// \brief No flags.
	IkarusPropertyDeleteFlags_None = 0,
};

/// \brief Delete a property.
/// \param property The property to delete.
/// \param flags Flags for deleting the property.
/// \param error_out \see errors.h
IKA_API void
ikarus_property_delete(IkarusProperty * property, IkarusPropertyDeleteFlags flags, IkarusErrorData * error_out);

/// \brief Get the project a property belongs to.
/// \param property The property 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 property belongs to or null if an error occurred.
/// \remark Ownership remains with libikarus.
IKA_API struct IkarusProject * ikarus_property_get_project(IkarusProperty * property, IkarusErrorData * error_out);

/// \brief Get the name of a property.
/// \param property The property 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 property or null if an error occurred.
/// \remark Ownership remains with libikarus.
IKA_API char const * ikarus_property_get_name(IkarusProperty * property, IkarusErrorData * error_out);

/// \brief Flags for setting the name of a property.
enum IkarusPropertySetNameFlags {
	/// \brief No flags.
	IkarusPropertySetNameFlags_None = 0,
};

/// \brief Set the name of a property.
/// \param property The property to set the name of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param name The new name of the property.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param flags Flags for setting the name of the property.
/// \param error_out \see errors.h
/// \remark Ownership remains with the caller.
IKA_API void ikarus_property_set_name(
	IkarusProperty * property,
	char const * name,
	IkarusPropertySetNameFlags flags,
	IkarusErrorData * error_out
);

/// \brief Get the schema of a property.
/// \param property The property to get the schema of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param error_out \see errors.h
/// \return The schema of the property in JSON format or null if an error occurred. \see schema.h
IKA_API char const * ikarus_property_get_schema(IkarusProperty * property, IkarusErrorData * error_out);

/// \brief Flags for setting the schema of a property.
enum IkarusPropertySetSchemaFlags {
	/// \brief No flags.
	IkarusPropertySetSchemaFlags_None = 0,
};

/// \brief Set the schema of a property.
/// \details Setting the schema of a property will reset all existing values.
/// \param property The property to set the schema of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param schema The new schema of the property.
/// \pre \li Must not be null.
/// \pre \li Must be a valid JSON buffer for a IkarusValueSchema. \see schema.h
/// \param new_default_value The new default value of the property.
/// \pre \li Must not be null.
/// \pre \li Must be a valid JSON buffer for an IkarusValueData. \see data.h
/// \param flags Flags for setting the schema of the property.
/// \param error_out \see errors.h
IKA_API void ikarus_property_set_schema(
	IkarusProperty * property,
	char const * schema,
	char const * new_default_value,
	IkarusPropertySetSchemaFlags flags,
	IkarusErrorData * error_out
);

/// \brief Get 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.
/// \param error_out \see errors.h
/// \return The default value data of the property in JSON format or null if an error occurred. \see data.h
IKA_API char const * ikarus_property_get_default_value(IkarusProperty * property, IkarusErrorData * error_out);

/// \details The default value must match the schema of the property.

/// \brief Flags for setting the default value of a property.
enum IkarusPropertySetDefaultValueFlags {
	/// \brief No flags.
	IkarusPropertySetDefaultValueFlags_None = 0,
};

/// \brief Flags for setting the default value of a property.
/// \param property The property to set the default value of.
/// \pre \li Must not be null.
/// \pre \li Must exist.
/// \param value The new default value of the property.
/// \pre \li Must not be null.
/// \pre \li Must be valid JSON \see data.h
/// \pre \li Must be valid according to the property's schema.
/// \param flags Flags for setting the default value of the property.
/// \param error_out \see errors.h
IKA_API void ikarus_property_set_default_value(
	IkarusProperty * property,
	char const * value,
	IkarusPropertySetDefaultValueFlags flags,
	IkarusErrorData * error_out
);

/// \brief Gets all values for a property.
/// \param property The property to get the values of.
///

IKARUS_END_HEADER

/// @}