libakgl/include/akgl/registry.h

/**
 * @file registry.h
 * @brief Declares the public registry API.
 */

#ifndef _REGISTRY_H_
#define _REGISTRY_H_

#include <akgl/error.h>
#include <akgl/staticstring.h>

/** @brief Registry of actors keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR;
/** @brief Registry of sprites keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_SPRITE;
/** @brief Registry of spritesheets keyed by asset path. */
extern SDL_PropertiesID AKGL_REGISTRY_SPRITESHEET;
/** @brief Registry of characters keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_CHARACTER;
/** @brief Registry mapping actor-state names to bit values. */
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR_STATE_STRINGS;
/** @brief Registry of fonts keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_FONT;
/** @brief Registry of music assets keyed by name. */
extern SDL_PropertiesID AKGL_REGISTRY_MUSIC;
/** @brief Registry of string configuration properties. */
extern SDL_PropertiesID AKGL_REGISTRY_PROPERTIES;

/**
 * @brief Registry init.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_* Propagates an error reported by a delegated operation.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init();
/**
 * @brief Registry init music.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_music();
/**
 * @brief Registry init font.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_font();
/**
 * @brief Registry init actor.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor();
/**
 * @brief Registry init sprite.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_sprite();
/**
 * @brief Registry init spritesheet.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_spritesheet();
/**
 * @brief Registry init character.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_character();
/**
 * @brief Registry init properties.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_properties();
/**
 * @brief Registry load properties.
 * @param fname Path to the input or output file.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_load_properties(char *fname);
/**
 * @brief Registry init actor state strings.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor_state_strings();
/**
 * @brief Set property.
 * @param name Registry key or human-readable object name.
 * @param value Property value to store.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_set_property(char *name, char *value);
/**
 * @brief Get property.
 * @param name Registry key or human-readable object name.
 * @param dest Output destination populated by the function.
 * @param def Fallback string returned when the property is absent.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_property(char *name, akgl_String **dest, char *def);

#endif //_REGISTRY_H_