This reference documents version 1.0.0-rc4-dev of the C API.
_filp_bareword - Use of barewords flag.
int _filp_bareword = 0;
If this flag is set, barewords (not-quoted words that are not recognized as commands) are treated as literal strings. Barewords are dangerous and hard to debug. Don't use it.
_filp_dict - Pointer to the symbol table.
static struct filp_sym *_filp_dict[FILP_DICT_HASH_SIZE];
This variable holds the symbol table, or dictionary.
_filp_error - Last error code.
int _filp_error = FILPERR_NONE;
This variable contains the last error code. Can be used as an offset to the filp_error_strings filp array.
_filp_error_info - Text info about the last error.
char _filp_error_info[80] = "";
This string contain additional info about the last error.
_filp_isolate - Flag to isolate potentially dangerous commands.
int _filp_isolate = 0;
If this flag is set to 1, potentially dangerous commands are disabled and generate errors. Can be used on sensible embedded systems exposed to untested input code. Basicly, denies access to file functions, putenv and shell execution.
_filp_parse_string - Parses a string
static char *_filp_parse_string(char *str, int slash, int interp);
Parses a string, converting escaped sequences (e.g. \n) to their corresponden equivalences if slash is set. If interp is set, any variable name prefixed by $ will have its value interpolated (as in Perl strings). Returns a pointer to a newly allocated string. This string must be freed when is not useful anymore.
_filp_real - Use of real numbers instead of integers flag.
int _filp_real = 0;
This flag tells filp if it must perform mathematical operations using integers (by default) or real numbers.
_filp_stack - Pointer to the stack.
static struct filp_stack *_filp_stack = NULL;
This variable stores the stack in use.
_filp_stack_elems - Number of elements currently in the stack.
int _filp_stack_elems = 0;
The number of elements currently stored in the stack.
_filp_stack_size - Maximum size of the stack.
int _filp_stack_size = 16384;
The maximum number of values the stack is allowed to store. By default is 16384. Just to avoid mad code from devouring all the available memory.
_filp_swap_stack - Pointer to the swapped stack.
static struct filp_stack *_filp_swap_stack = NULL;
This variable points to the alternative (swapped) stack.
The content of this variable is swapped with _filp_stack
by the filp_swap_stack() function.
_filp_version - Version of filp.
char _filp_version[] = VERSION;
This string holds the current version of filp.
filp_array_binary_seek - Seeks a string in a sorted array.
int filp_array_binary_seek(struct filp_val *a, char *str, int inc);
Seeks the string str in the a sorted array, incrementing the element to be seek by inc (to seek all the array, use an increment of 1). If the element is found, its subscript is returned as a positive number; otherwise, the subscript of the position where the value should be is returned as a negative number.
filp_array_collapse - Shrinks an array.
void filp_array_collapse(struct filp_val *a, int offset, int num);
Deletes num empty elements at the offset of the a array.
filp_array_del - Deletes an element of an array.
struct filp_val *filp_array_del(struct filp_val *value, int i);
Deleted the i element from the value array. The array is shrinked by one. Returns the deleted element.
filp_array_destroy - Destroys an array.
void filp_array_destroy(struct filp_val *value);
Destroys an array.
filp_array_dim - Gives dimension to an array.
struct filp_val **filp_array_dim(int asize);
Gives dimension to an array.
filp_array_dup - Duplicates an array.
struct filp_val *filp_array_dup(struct filp_val *value);
Duplicates the value array. A new value containing the same elements is returned.
filp_array_expand - Inserts room in an array.
void filp_array_expand(struct filp_val *a, int offset, int num);
Inserts num empty elements in the offset of the a array.
filp_array_get - Gets an element of an array.
struct filp_val *filp_array_get(struct filp_val *value, int i);
Returns the element number i of the array value.
filp_array_ins - Inserts a value in an array.
void filp_array_ins(struct filp_val *value, struct filp_val *e, int i);
Inserts the e value in the value array in the i subscript. Further elements are pushed up, so the array increases its size by one. If i is 0, the element is inserted at the end of the array.
filp_array_seek - Seeks a string in an array.
int filp_array_seek(struct filp_val *value, char *str, int inc);
Seeks the string str in the value array, incrementing the element to be seek by inc (to seek all the array, use an increment of 1). Returns the subscript of the first element with a value equal to str or 0 if none has it.
filp_array_set - Sets the value of an array's element.
struct filp_val *filp_array_set(struct filp_val *value, struct filp_val *e, int i);
Sets the element i of the array value to be the e value. If i is 0, the element set is the last of the array. Returns the previous element.
filp_array_size - Gets the size of an array.
int filp_array_size(struct filp_val *value);
Returns the number of elements of the array.
filp_array_sort - Sorts an array.
void filp_array_sort(struct filp_val *value, int inc);
Sorts alphabetically the elements of the array. If inc is greater than 1, the elements are ordered in groups of that quantity.
filp_bin_code - Creates a new binary code symbol.
int filp_bin_code(char *name, int (*func) (void));
Creates a new binary code (C code) symbol. This symbol can be directly executed by the filp parser.
filp_cmp - Compares two filp values.
int filp_cmp(struct filp_val *v1, struct filp_val *v2);
Compares two filp values. Only must be used compare
scalar values.
Returns a value similar to that of strcmp().
filp_code_push - Pushes a string to the stack, as filp code.
int filp_code_push(char *code);
Pushes a string to the stack as filp code. The code is not tested for integrity nor syntax.
filp_destroy_symbol - Destroys a symbol.
void filp_destroy_symbol(struct filp_sym *s);
Destroys a symbol and deletes it from the symbol table.
filp_exec - Executes filp code.
int filp_exec(char *code)/* runs a program (main parser) */;
Executes the string as filp code. Returns 0 if everything is ok, <0 on error or >0 if execution is intentionally interrupted (by using break or end).
filp_execf - Executes filp code, with formatting.
int filp_execf(char *code, ...);
Formats code as a printf() -like string, and executes it
as filp code. See filp_exec() for return values.
filp_execv - Executes filp code inside a filp value.
int filp_execv(struct filp_val *v);
Executes filp code inside a value. The value v must be binary code, filp code or a scalar containing filp code.
filp_ext_file - Creates a new external file descriptor symbol.
int filp_ext_file(char *name, FILE * f);
Creates a new external file descriptor symbol. The file should be alread opened and never closed from the C code.
filp_ext_int - Creates a new external C integer symbol.
int filp_ext_int(char *name, int *val);
Creates a new external C integer symbol. This symbol will behave as a scalar filp variable, but any value assigned to it will be converted to integer and stored into the variable.
filp_ext_real - Creates a new external C double symbol.
int filp_ext_real(char *name, double *val);
Creates a new external C double float symbol. This symbol will behave as a scalar filp variable, but any value assigned to it will be converted to double float and stored into the variable.
filp_ext_string - Creates a new external string symbol.
int filp_ext_string(char *name, char *val, int size);
Creates a new external C string symbol. This symbol will behave as a scalar filp variable, but any value assigned to it will be stored into the C string. If the assigned value exceeds size, it will be silently truncated.
filp_find_symbol - Finds a symbol by name.
struct filp_sym *filp_find_symbol(char *name);
Finds a symbol by name. Returns the symbol, or a NULL pointer if not found.
filp_get_symbol - Gets the value of a symbol.
struct filp_val *filp_get_symbol(struct filp_sym *s);
Gets the value of a symbol.
filp_hash_del - Deletes a key-value pair from a hash.
struct filp_val *filp_hash_del(struct filp_val *h, char *key);
Deletes a key-value pair from the hash given its key. If the pair exists, the value is returned, or NULL otherwise.
filp_hash_get - Gets an element from a hash.
struct filp_val *filp_hash_get(struct filp_val *h, char *key);
Returns the value associated with key form the hash h, or NULL if no one exists.
filp_hash_get_pair - Gets a key-value pair from the hash.
int filp_hash_get_pair(struct filp_val *h, int i, struct filp_val **key, struct filp_val **value);
Gets the key-value pair number i from the hash h. A hash
contains key-value pairs numbered from 1 to filp_hash_size().
key and value can be pointers to struct filp_val or NULL.
filp_hash_set - Stores a key-value pair into a hash.
struct filp_val *filp_hash_set(struct filp_val *h, char *key, struct filp_val *value);
Stores a key-value pair into the hash. Returns the previously stored value under that key if one exists, or NULL otherwise.
filp_hash_size - Returns the number of pairs of a hash.
int filp_hash_size(struct filp_val *h);
Returns the number of key-value pairs stored in the hash.
filp_hashfunc - Hash function for the dictionary.
int filp_hashfunc(unsigned char *string, int mod);
Calculates a hash for the string argument, to be used to search the dictionary. Returns the computed hash.
filp_int_pop - Pops a value from the stack, as an integer value.
int filp_int_pop(void);
Pops a value from the stack, as a C integer value. If the value has no meaning as a number, 0 is returned.
filp_int_push - Pushes a C integer into the stack, as a scalar.
int filp_int_push(int value);
Pushes a C integer into the stack, previously converted to its printable value.
filp_is_true - True condition tester.
int filp_is_true(struct filp_val *v);
Tests if the v value is evaluated as a boolean 'true' filp expression. A filp value is true if it's not FILP_NULL and it's not a scalar containing 0 or "0".
filp_list_size - Computes the size of a list.
int filp_list_size(void);
Computes the size of a list.
filp_load_exec - Loads and executes a filp code file.
int filp_load_exec(char *filename);
Loads a file and executes it. See filp_exec() for the
return values.
filp_load_file - Loads a filp code file.
char *filp_load_file(char *filename);
Loads a filp code file and returns a pointer to it.
The file must not be necessary filp code; no integrity
or syntax is checked. The returned pointer must be
destroyed using free() when no longer needed.
filp_new_bin_code_value - Creates a bin code value.
struct filp_val *filp_new_bin_code_value(int (*func) (void));
Creates a new value of the FILP_BIN_CODE type. The func must have no parameters and return a non-zero integer value in case of error.
filp_new_hash - Creates a new hash.
struct filp_val *filp_new_hash(int buckets);
Creates a new hash. A filp hash is, internally, a filp array of buckets arrays.
filp_new_int_value - Creates a new scalar from an int.
struct filp_val *filp_new_int_value(int value);
Creates a new scalar from the integer value. Returns the new value.
filp_new_real_value - Creates a new scalar from a double.
struct filp_val *filp_new_real_value(double value);
Creates a new scalar from the double value. Returns the new value.
filp_new_symbol - Creates a new symbol.
struct filp_sym *filp_new_symbol(filp_type type, char *name);
Creates a new symbol. A pointer to it is returned.
filp_new_value - Creates a new filp value.
struct filp_val *filp_new_value(filp_type type, void *value, int size);
Creates a new filp value. The type must be a valid filp value type, and the value a pointer to the specific data to be stored inside (can be NULL for some types). The size argument can be -1 for the FILP_SCALAR and FILP_CODE types to make it automatically calculated. Returns a pointer to a struct filp_val, containing the new value, or NULL if it could not be done.
filp_null_push - Pushes a special NULL value to the stack.
int filp_null_push(void);
Pushes a special NULL value to the stack.
filp_poke - Stores a byte in a dynamic string.
char *filp_poke(char *ptr, int *size, int offset, int c);
Stores a byte in a dynamic string at offset. If the offset
is higher than the size of the string, the latter is resized
using realloc(). The string ptr can be NULL; in that case,
a new string is created.
Returns a pointer to the new string (the original ptr could
have changed).
filp_pop - Pops a value from the stack.
struct filp_val *filp_pop(void);
Pops a value from the stack. Returns a special NULL filp value on stack underflow condition.
filp_push - Pushes a value into the stack, duplicating it.
int filp_push(struct filp_val *v);
Pushes a copy of the value into the stack. The value can still be used, and must be destroyed when not useful anymore, as usual.
filp_push_dict - Pushes to the stack names of symbols.
int filp_push_dict(char *mask);
Pushes to the stack all the symbol names that start with mask as a list.
filp_push_symbol_value - Pushes a symbol value to the stack
void filp_push_symbol_value(char *symbol);
Pushes the value of a symbol to the stack, or a FILP_NULL value if symbol is not found.
filp_real_pop - Pops a value from the stack, as a double value.
double filp_real_pop(void);
Pops a value from the stack, as a C double float value. If the value has no meaning as a number, 0 is returned.
filp_real_push - Pushes a C double into the stack, as a scalar.
int filp_real_push(double value);
Pushes a C double flaot into the stack, previously converted to its printable value.
filp_ref_value - Increments the reference to a value
void filp_ref_value(struct filp_val *v);
Increments the reference count of v. Values with a reference count > 0 will never be destroyed by the garbage collector.
filp_rot - Rotates the stack.
void filp_rot(int pos);
Move the element number pos from the stack to the top.
filp_scalar_push - Pushes a scalar into the stack.
int filp_scalar_push(char *value);
Pushes a scalar into the stack. The scalar must be a string.
filp_set_symbol - Sets a symbol to a value.
void filp_set_symbol(struct filp_sym *s, struct filp_val *v);
Assigns the value v to the symbol s.
filp_splice - Deletes and inserts text in an string
char *filp_splice(char *src, int offset, int size, char *new);
Removes size elements from the offset of the src string and substitutes them by new. size can be 0 if no chars are to be deleted, of new can be "" if no string is to be inserted. A new allocated string is returned.
filp_stack_value - Returns the nth element of the stack.
struct filp_val *filp_stack_value(int pos);
Returns the nth element of the stack, counting from 1. The stack is left untouched. If no value is found, a FILP_NULL value is returned.
filp_swap_stack - Commutes between the two stacks.
void filp_swap_stack(void);
Commutes between the two stacks.
filp_sweeper - Forces a garbage collection
void filp_sweeper(int full);
Forces a garbage collection. If full is nonzero, the complete value poll is checked; otherwise, only a small set of them are checked.
filp_unref_value - Decrements the reference to a value
void filp_unref_value(struct filp_val *v);
Decrements the reference count of v. Values with a reference count > 0 will never be destroyed by the garbage collector.
filp_val_to_int - Converts a filp value to an int.
int filp_val_to_int(struct filp_val *v);
Converts a filp value into an integer. Returns the integer.
filp_val_to_real - Converts a filp value to a double.
double filp_val_to_real(struct filp_val *v);
Converts a filp value into a double. Returns the integer.
Visitor comments
2010-05-14