Agar


Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

The AG_Object(3) class provides a set of general-purpose properties (key=value pairs). Values are specified using the AG_Variable(3) interface. The AG_Prop interface allows properties to be assigned and read.

By default, properties are made persistent by the AG_Object archiving process.

NOTE: As of Agar 1.3.4, this interface is now deprecated. Developers should use the new AG_Variable(3), interface instead.

READING PROPERTIES


AG_Prop * AG_GetProp (AG_Object *obj, const char *key, enum ag_prop_type type, void *dst)

int AG_PropDefined (AG_Object *obj, const char *key)

AG_Prop * AG_CopyProp (const AG_Prop *prop)

void AG_LockProps (AG_Object *obj)

void AG_UnlockProps (AG_Object *obj)

int AG_GetBool (AG_Object *obj, const char *key)

Uint AG_GetUint (AG_Object *obj, const char *key)

int AG_GetInt (AG_Object *obj, const char *key)

Uint8 AG_GetUint8 (AG_Object *obj, const char *key)

Sint8 AG_GetSint8 (AG_Object *obj, const char *key)

Uint16 AG_GetUint16 (AG_Object *obj, const char *key)

Sint16 AG_GetSint16 (AG_Object *obj, const char *key)

Uint32 AG_GetUint32 (AG_Object *obj, const char *key)

Sint32 AG_GetSint32 (AG_Object *obj, const char *key)

float AG_GetFloat (AG_Object *obj, const char *key)

double AG_GetDouble (AG_Object *obj, const char *key)

size_t AG_GetString (AG_Object *obj, const char *key, char *dst, size_t dst_size)

char * AG_GetStringDup (AG_Object *obj, const char *key)

void * AG_GetPointer (AG_Object *obj, const char *key)


The AG_GetProp() function searches for a property of type type named key and writes its value to dst, which should point to a variable of the specific data type associated with the property. AG_Prop returns a pointer to the related AG_Prop structure, or NULL if no property matches key.

The AG_PropDefined() routine returns 1 if a property key exists.

The AG_CopyProp() function returns a copy of prop.

The AG_LockProps() and AG_UnlockProps() functions acquire/release the recursive mutex which is associated with an object's properties.

The AG_(Type)() functions all look for a property named key and return the associated value, raising a fatal condition if there is no match.

The AG_GetString() routine copies up to dst_size - 1 characters from the value of a string property to dst, NUL-terminating the result.

AG_GetStringDup() returns a copy of the string.

WRITING PROPERTIES


AG_Prop * AG_SetProp (AG_Object *obj, const char *name, enum ag_prop_type type, ...)

AG_Prop * AG_SetBool (AG_Object *obj, const char *key, int value)

AG_Prop * AG_SetUint (AG_Object *obj, const char *key, Uint value)

AG_Prop * AG_SetInt (AG_Object *obj, const char *key, int value)

AG_Prop * AG_SetUint8 (AG_Object *obj, const char *key, Uint8 value)

AG_Prop * AG_SetSint8 (AG_Object *obj, const char *key, Sint8 value)

AG_Prop * AG_SetUint16 (AG_Object *obj, const char *key, Uint16 value)

AG_Prop * AG_SetSint16 (AG_Object *obj, const char *key, Sint16 value)

AG_Prop * AG_SetUint32 (AG_Object *obj, const char *key, Uint32 value)

AG_Prop * AG_SetSint32 (AG_Object *obj, const char *key, Sint32 value)

AG_Prop * AG_SetFloat (AG_Object *obj, const char *key, float value)

AG_Prop * AG_SetDouble (AG_Object *obj, const char *key, double value)

AG_Prop * AG_SetString (AG_Object *obj, const char *key, const char *s)

AG_Prop * AG_SetStringNODUP (AG_Object *obj, const char *key, const char *s)

AG_Prop * AG_SetStringFixed (AG_Object *obj, const char *key, char *buf, size_t bufSize)

AG_Prop * AG_PrtString (AG_Object *obj, const char *key, const char *fmt, ...)

AG_Prop * AG_SetPointer (AG_Object *obj, const char *key, void *ptr)


The AG_SetProp() function searches for a property of type type named key and sets its value to data read from the next arguments, which should be data of the specific data type associated with the property. If the key does not match an existing property, a new one is created.

The AG_Set(Type)() functions all look for a property named key and set its value to value, returning a pointer to the modified property. If the key does not match any existing property, a new one is created.

SAVING/LOADING


int AG_PropLoad (AG_Object *obj, AG_DataSource *ds)

int AG_PropSave (AG_Object *obj, AG_DataSource *ds)


The AG_PropLoad() function loads an object's property table in machine-independent format from ds, and AG_PropSave() saves an object's property table in machine-independent format to ds. Properties which are marked non-persistent (such as all properties of type AG_VARIABLE_POINTER) are ignored by these functions.

SEE ALSO

AG_Intro(3), AG_Object(3), AG_DataSource(3)

HISTORY

The AG_Prop interface first appeared in Agar 1.0. Support for property-specific and object-specific read/write operations first appeared in Agar 1.1. The introduction of AG_Variable(3) in Agar 1.3.4 rendered the AG_Prop interface obsolete.