Working With Variables

Accessing a Variable's Data

Before we get into the specifics you should know that ferite internally represents all variables using FeriteVariable *'s, and they can safely represent any native type within ferite. The builder and the return macros you've already seen are in place to perform conversions for the sake of convenience. But sometimes you just need to stick your finger in the pudding, so here is how to do it without breaking ferite.

There are a few bits of general information you can get from a FeriteVariable * without looking specifically into one variable type. The internal variable name is accessible, although it really isn't as useful as it sounds. Usually the variable name has been automatically generated by an operator or a function. But if you'd really like to have it, you can access is by: [it is a null terminated c string]

    var->name

Much more useful than the variable name is the variable type. This will tell you if the data held is a number (and what kind), a ferite string, an object, an array, or void (nothing at all). It is accessible by:

    var->type

It is an integer that can be any one of the following values:

F_VAR_VOID - a void variable, no value.
F_VAR_LONG - a number variable as a c long.
F_VAR_DOUBLE - a number variable as a c double.
F_VAR_STR - a string variable.
F_VAR_UARRAY - an unified array variable.
F_VAR_OBJ - an object.

There are a number of additional macros available for accessing the actual data within different variable types. You should use these macros as much as possible when working with ferite variables. Internal structures may change, but these macros should always be up to date and provide exactly the same semantics when it comes to value access.

F_VAR_VOID - since this is a void variable, there really isn't any data to gain access to.
F_VAR_LONG - the data can be accesses by VAI( var ) . This will make it act exactly like a c long. You can read its value, and set new values.
Example:
VAI(mynum) = 7;
F_VAR_DOUBLE - the data can be accessed by VAF( var ). This will make it act exactly like a c double. You can read its value and set new values.
Example:
VAF(mynum) = 8.16;
F_VAR_STR - using the VAS( var ) macro will get you a FeriteString *, which can then be used in API functions to perform various operations. You can access the string's length and data by using the original FeriteVariable * in the FE_STRLEN( var ) and FE_STR2PTR( var ) macros, respectively. FE_STR2PTR behaves like a char *, and FE_STRLEN behaves like an int. Whenever you change a string's content, you must always update it's internal size to reflect the new actual size.
Example:
ffree(FE_STR2PTR(var)); FE_STR2PTR(var) = fstrdup("My new string!"); FE_STRLEN(var) = strlen(FE_STR2PTR(var));
There are a whole host of functions within the ferite engine for manipulating FeriteString*'s allowing you to do comparisons and replacements on the strings. It should also be noted that FeriteString*'s are designed to hold binary data.
F_VAR_OBJECT - using the macro VAO( var ) will get you a FeriteObject *, which can then be used in a variety of api functions to access variables and functions within that object.
F_VAR_UARRAY - using the macro VAUA( var ) will get you a FeriteUnifiedArray *, which can then be used in the unified array api functions to add, retrieve, and remove values from the array.

Changing a Variable's Type

You can change a variable's type by changing the var->type value to the desired type, but converting the variable's contents is entirely up to you. You should be especially careful when changing the type of strings, objects and arrays, as they have a lot of extra data that goes along with them. However changing a number between types is quite easy. For example, to change a double to a long, you can simply do this:

    VAI(var) = (long) VAF(var);
    var->type = F_VAR_LONG;

And to change it back:

    VAF(var) = (double) VAI(var);
    var->type = F_VAR_DOUBLE;

It is considered bad for to simply change the type of a variable and is therefore not encouraged at all. It is therefore on your own head to keep things correct.

Creating and Destroying Variables

Creating variables is quite simple. Each variable type has a 'create' function that returns a FeriteVariable *, which will be encapsulating the type you requested. The only thing difficult about creating variables is remembering that the returned object will always be a FeriteVariable *, rather than the specific struct type that you wanted. This is because the FeriteVariable * is encapsulating the variable type you had wanted. This is actually quite convenient, since you would have to stuff the specific variable type into a FeriteVariable * before giving it back to the ferite engine anyhow.

You already know how to manipulate these variables (or at least get to the information needed to manipulate them), so I'll just quickly run through the variable types available, and their creation functions. The parameters should be pretty self explanitary, if not please refer the the C api document. It should be noted though that they all take the same argument "alloc", this tells ferite whether or not the name of the variable should be allocated or whether it is static.

F_VAR_VOID - FeriteVariable *ferite_create_void_variable(char *name, int alloc);
F_VAR_LONG - FeriteVariable *ferite_create_number_long_variable(char *name, long data, int alloc);
F_VAR_DOUBLE - FeriteVariable *ferite_create_number_double_variable(char *name, double data, int alloc);
F_VAR_STR - FeriteVariable *ferite_create_string_variable(char *name, FeriteString *data, int alloc);
F_VAR_STR - FeriteVariable *ferite_create_string_variable_from_ptr(char *name, char *data, int length, int encoding, int alloc); [As of the time of writing, the encoding value is always FE_CHARSET_DEFAULT. The reason for it being set now is so the in the future when the encoding of a string is important code will still work unmodified]
F_VAR_UARRAY - FeriteVariable *ferite_create_uarray_variable(char *name, int size, int alloc);
F_VAR_OBJ - FeriteVariable *ferite_create_object_variable( char *name, int alloc );

Deleting variables is actually easier than creating them, if you can believe it. To delete any ferite variable, you simply use the ferite_variable_destroy() function. This function takes the current script and a FeriteVariable * as parameters, and it returns void.

    void ferite_variable_destroy( FeriteScript *script, FeriteVariable *var );

You can use this function on any type of variable, each will be handled in the appropriate manner according to it's type. Strings will have their c-string data freed by ffree() and will then be destroyed. Objects will have their destructor called before they are destroyed. Lastly, unified arrays will have the variables at each of its indexes destroyed in the appropriate manner according to their type and will then, themselves, be destroyed.