SYNOPSIS
|
DESCRIPTION
Every Agar
AG_Object(3) instance has an associated set of named variables, which are useful for storing
primitive data as well as references to external, structured data.
An Agar variable can store the following types of data:
An AG_Variable can also reference the following types of data:
AG_Variable is used extensively throughout Agar and Agar-based libraries. In the Agar-GUI system, GUI widgets use Agar variables to reference external data (also known as "bindings"). For example, the "value" variable of an AG_Numerical(3) spinbutton may be tied to a fixed-size integer, a floating-point number, or any other type implemented by AG_Numerical. It is also possible to allocate anonymous AG_Variable structures on the fly. For instance, the event system of AG_Object(3) uses a list of AG_Variable elements to describe the list of arguments passed to event handler routines. |
INTERFACE
|
The AG_Defined() routine returns 1 if the specified variable name is defined under the object obj, otherwise it returns 0. The caller must lock obj before invoking AG_Defined(). The AG_GetVariable() routine searches for a named variable under object obj and returns a pointer to the corresponding AG_Variable structure if found. If no such variable exists, NULL is returned. If the variable is tied to a function, the function is evaluated first. If the data argument is not NULL, a pointer to the variable's primitive data is returned into it (not valid for strings). AG_GetVariableLocked() looks up the named variable under obj and returns a pointer to the corresponding AG_Variable structure if found, otherwise NULL is returned. If the variable is tied to a function, the function is not evaluated internally. Before returning, AG_GetVariableLocked() acquires any locking devices associated with the variable. The caller is expected to invoke AG_UnlockVariable() when done accessing the data. The AG_FetchVariable() routine looks up a variable by name, returning a pointer to the corresponding AG_Variable structure. If no such variable exists, a new one of the specified type is allocated. The AG_FetchVariableOfType() variant works like AG_FetchVariable(), except that preexisting variables of a differing type are automatically destroyed and recreated to match the specified type. AG_LockVariable() and AG_UnlockVariable() acquire and release any locking device associated with the specified variable. AG_GetVariableVFS() searches an AG_Object(3) VFS for a variable from a string of the form object:variable. The AG_EvalVariable() function evaluates the value of a variable tied to a function. The corresponding function is invoked and the value is returned into the data union. Note that internally, AG_GetVariable() calls AG_EvalVariable(), but AG_GetVariableLocked() does not. AG_PrintVariable() returns a string representation of the value of variable var into a fixed-size buffer dst, of len bytes. AG_CopyVariable() copies the contents of a variable from Vsrc to Vdst. Pointer references are preserved. For AG_VARIABLE_STRING variable types, internally-allocated strings are duplicated. AG_DerefVariable() copies the contents of Vsrc to Vdst, converting pointer references to immediate values. For AG_VARIABLE_STRING variable types, strings are duplicated unconditionally. The AG_CompareVariables() compares the value of two variables, returning zero if they are identical. If they differ, the difference between the two first differing bytes is returned. If AG_CompareVariables() encounters pointer types, they are not dereferenced (rather the value of the pointer itself is compared). The AG_Set() sets an object-bound variable value using a format-string interface (see AG_PARSE_VARIABLE_ARGS()). AG_Unset() deletes the named object-bound variable. AG_VariableSubst() parses the string s for references of the form "$(foo)", and substitutes those references for the value of variable foo (under object obj). The substituted string is returned into fixed-size buffer dst, of size dst_size. |
TYPE-SPECIFIC INTERFACES
|
The following functions are used to retrieve or set variables of
specific types.
The AG_GetFoo() functions return the value of variable name (under object obj). If the variable is a pointer type, it is dereferenced. If it is tied to a function, the function is evaluated first. The AG_InitFoo() functions initialize an AG_Variable structure var with the specified value val. The AG_SetFoo() functions set the value of variable name to the specified value val. If the variable does not exist, it is created. The AG_BindFoo() functions create or modify a typed pointer variable. The argument pVal is a pointer to the actual value. The AG_BindFooMp() variant accepts an extra lock argument, which is a mutex device (i.e., an AG_Mutex or pthread_mutex_t) to be acquired whenever the data referenced by pVal will be accessed. The AG_BindFooFn() variants create or modify a variable, tying the variable to a function fn, which will be evaluated whenever the variable is read. A list of optional AG_Event(3) style arguments follow the fn argument. |
INTEGERS
REAL NUMBERS
These functions provide an interface to floating-point numbers. The long double functions are only available if AG_HAVE_LONG_DOUBLE is defined. |
C STRINGS
These functions provide an interface to C strings. A string variable can either contain a dynamically-allocated buffer, or reference an external, fixed-size buffer. AG_GetString() returns the contents of a string variable. The string is safely copied to fixed-size buffer dst, of size dst_size. The return value is the number of bytes that would have been copied, were dst_size unlimited. AG_GetStringDup() returns a newly-allocated copy of the string variable. If the string cannot be allocated, NULL is returned. The AG_GetStringP() function returns a direct pointer to the buffer containing the string. If the given variable is function-defined (i.e., it was set by AG_BindStringFn()), the value generated by the last AG_EvalVariable() operation is returned. Note that AG_GetStringP() is not free-threaded, so calls to this function should be protected by AG_LockVariable() (as an exception, dynamically-allocated strings set by AG_SetString() are safe to access without locking, as long as the variable's parent object is locked). AG_InitString() initializes a AG_Variable structure with the given string, which is copied from s. The AG_InitStringNODUP() variant sets the s pointer without copying the string. The AG_SetString() function creates or modifies a string variable. The s argument is a C string which will be duplicated or copied. If the variable exists as a reference to a fixed-size buffer (i.e., it has been created by AG_BindString()), then the contents of s are copied to the buffer. If the buffer has insufficient space, the string is truncated. The s argument may be set to NULL (in which case further AG_GetString() calls will return NULL). The AG_SetStringNODUP() variant accepts a pointer to a dynamically-allocated string buffer. This buffer will be freed automatically when the parent object is destroyed. The AG_PrtString() variant sets a string variable from a format string argument. AG_BindString() creates or modifies a variable referencing a fixed-size string buffer s, of size len. The AG_BindStringFn() variant ties the variable to a function fn. |
TEXT OBJECTS
These functions provide an interface to Agar text objects (see AG_Text(3)). |
GENERIC POINTERS
These functions provide an interface to generic pointer types. |
BITS
These functions provide an interface for binding to specific bits in integers. They follow the standard form, with an extra bitmask argument.
The AG_BindVariable() function creates a reference to a variable named varKey, under the target object varObj. Whenever AG_GetVariable() or AG_GetVariableLocked() finds a reference variable, the target variable is looked up and returned. |
STRUCTURE DATA
For the
AG_Variable structure:
|
SEE ALSO
| AG_Intro(3), AG_List(3), AG_Object(3), AG_Tbl(3), AG_Tree(3) |
HISTORY
| The AG_Variable interface first appeared in Agar 1.3.4. It replaced the older AG_Prop(3) interface, and widget bindings which were previously stored in AG_Widget(3) itself. |
