The Filp C API (1.0.0-rc4-cvs)

By Source

filp_array.c

filp_array_binary_seek, filp_array_collapse, filp_array_del, filp_array_destroy, filp_array_dim, filp_array_dup, filp_array_expand, filp_array_get, filp_array_ins, filp_array_seek, filp_array_set, filp_array_size, filp_array_sort, filp_hash_del, filp_hash_get, filp_hash_get_pair, filp_hash_set, filp_hash_size, filp_new_hash

filp_core.c

_filp_bareword, _filp_dict, _filp_error, _filp_error_info, _filp_isolate, _filp_real, _filp_stack, _filp_stack_elems, _filp_stack_size, _filp_swap_stack, _filp_version, filp_cmp, filp_destroy_symbol, filp_find_symbol, filp_get_symbol, filp_hashfunc, filp_is_true, filp_list_size, filp_new_symbol, filp_new_value, filp_poke, filp_pop, filp_push, filp_push_dict, filp_ref_value, filp_rot, filp_set_symbol, filp_splice, filp_stack_value, filp_swap_stack, filp_sweeper, filp_unref_value

filp_parse.c

_filp_parse_string, filp_exec, filp_execf, filp_execv, filp_load_exec, filp_push_symbol_value

filp_util.c

filp_bin_code, filp_code_push, filp_ext_file, filp_ext_int, filp_ext_real, filp_ext_string, filp_int_pop, filp_int_push, filp_load_file, filp_new_bin_code_value, filp_new_int_value, filp_new_real_value, filp_null_push, filp_real_pop, filp_real_push, filp_scalar_push, filp_val_to_int, filp_val_to_real

Alphabetical

_filp_bareword - Use of barewords flag.
_filp_dict - Pointer to the symbol table.
_filp_error - Last error code.
_filp_error_info - Text info about the last error.
_filp_isolate - Flag to isolate potentially dangerous commands.
_filp_parse_string - Parses a string
_filp_real - Use of real numbers instead of integers flag.
_filp_stack - Pointer to the stack.
_filp_stack_elems - Number of elements currently in the stack.
_filp_stack_size - Maximum size of the stack.
_filp_swap_stack - Pointer to the swapped stack.
_filp_version - Version of filp.
filp_array_binary_seek - Seeks a string in a sorted array.
filp_array_collapse - Shrinks an array.
filp_array_del - Deletes an element of an array.
filp_array_destroy - Destroys an array.
filp_array_dim - Gives dimension to an array.
filp_array_dup - Duplicates an array.
filp_array_expand - Inserts room in an array.
filp_array_get - Gets an element of an array.
filp_array_ins - Inserts a value in an array.
filp_array_seek - Seeks a string in an array.
filp_array_set - Sets the value of an array's element.
filp_array_size - Gets the size of an array.
filp_array_sort - Sorts an array.
filp_bin_code - Creates a new binary code symbol.
filp_cmp - Compares two filp values.
filp_code_push - Pushes a string to the stack, as filp code.
filp_destroy_symbol - Destroys a symbol.
filp_exec - Executes filp code.
filp_execf - Executes filp code, with formatting.
filp_execv - Executes filp code inside a filp value.
filp_ext_file - Creates a new external file descriptor symbol.
filp_ext_int - Creates a new external C integer symbol.
filp_ext_real - Creates a new external C double symbol.
filp_ext_string - Creates a new external string symbol.
filp_find_symbol - Finds a symbol by name.
filp_get_symbol - Gets the value of a symbol.
filp_hash_del - Deletes a key-value pair from a hash.
filp_hash_get - Gets an element from a hash.
filp_hash_get_pair - Gets a key-value pair from the hash.
filp_hash_set - Stores a key-value pair into a hash.
filp_hash_size - Returns the number of pairs of a hash.
filp_hashfunc - Hash function for the dictionary.
filp_int_pop - Pops a value from the stack, as an integer value.
filp_int_push - Pushes a C integer into the stack, as a scalar.
filp_is_true - True condition tester.
filp_list_size - Computes the size of a list.
filp_load_exec - Loads and executes a filp code file.
filp_load_file - Loads a filp code file.
filp_new_bin_code_value - Creates a bin code value.
filp_new_hash - Creates a new hash.
filp_new_int_value - Creates a new scalar from an int.
filp_new_real_value - Creates a new scalar from a double.
filp_new_symbol - Creates a new symbol.
filp_new_value - Creates a new filp value.
filp_null_push - Pushes a special NULL value to the stack.
filp_poke - Stores a byte in a dynamic string.
filp_pop - Pops a value from the stack.
filp_push - Pushes a value into the stack, duplicating it.
filp_push_dict - Pushes to the stack names of symbols.
filp_push_symbol_value - Pushes a symbol value to the stack
filp_real_pop - Pops a value from the stack, as a double value.
filp_real_push - Pushes a C double into the stack, as a scalar.
filp_ref_value - Increments the reference to a value
filp_rot - Rotates the stack.
filp_scalar_push - Pushes a scalar into the stack.
filp_set_symbol - Sets a symbol to a value.
filp_splice - Deletes and inserts text in an string
filp_stack_value - Returns the nth element of the stack.
filp_swap_stack - Commutes between the two stacks.
filp_sweeper - Forces a garbage collection
filp_unref_value - Decrements the reference to a value
filp_val_to_int - Converts a filp value to an int.
filp_val_to_real - Converts a filp value to a double.

Name

_filp_bareword - Use of barewords flag.

Synopsis

int _filp_bareword=0;

Description

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.

Name

_filp_dict - Pointer to the symbol table.

Synopsis

static struct filp_sym * _filp_dict[FILP_DICT_HASH_SIZE];

Description

This variable holds the symbol table, or dictionary.

Name

_filp_error - Last error code.

Synopsis

int _filp_error=FILPERR_NONE;

Description

This variable contains the last error code. Can be used as an offset to the filp_error_strings filp array.

Name

_filp_error_info - Text info about the last error.

Synopsis

char _filp_error_info[80]="";

Description

This string contain additional info about the last error.

Name

_filp_isolate - Flag to isolate potentially dangerous commands.

Synopsis

int _filp_isolate=0;

Description

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.

Name

_filp_parse_string - Parses a string

Synopsis

static char * _filp_parse_string(char * str, int slash, int interp);

Arguments

str

the string to be parsed

slash

flag to process backslashed chars (\n, etc).

interp

flag to interpolate variables (ala Perl).

Description

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.

Name

_filp_real - Use of real numbers instead of integers flag.

Synopsis

int _filp_real=0;

Description

This flag tells filp if it must perform mathematical operations using integers (by default) or real numbers.

Name

_filp_stack - Pointer to the stack.

Synopsis

static struct filp_stack * _filp_stack=NULL;

Description

This variable stores the stack in use.

Name

_filp_stack_elems - Number of elements currently in the stack.

Synopsis

int _filp_stack_elems=0;

Description

The number of elements currently stored in the stack.

Name

_filp_stack_size - Maximum size of the stack.

Synopsis

int _filp_stack_size=16384;

Description

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.

Name

_filp_swap_stack - Pointer to the swapped stack.

Synopsis

static struct filp_stack * _filp_swap_stack=NULL;

Description

This variable points to the alternative (swapped) stack. The content of this variable is swapped with _filp_stack by the filp_swap_stack() function.

Name

_filp_version - Version of filp.

Synopsis

char _filp_version[]=VERSION;

Description

This string holds the current version of filp.

Name

filp_array_binary_seek - Seeks a string in a sorted array.

Synopsis

int filp_array_binary_seek(struct filp_val * a, char * str, int inc);

Arguments

a

the array

str

the string to be found

inc

element increment

Description

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.

Name

filp_array_collapse - Shrinks an array.

Synopsis

void filp_array_collapse(struct filp_val * a, int offset, int num);

Arguments

a

the array

offset

offset to the first element to be deleted

num

number of elements to be deleted

Description

Deletes num empty elements at the offset of the a array.

Name

filp_array_del - Deletes an element of an array.

Synopsis

struct filp_val * filp_array_del(struct filp_val * value, int i);

Arguments

value

the value

i

subscript of the element to be deleted.

Description

Deleted the i element from the value array. The array is shrinked by one. Returns the deleted element.

Name

filp_array_destroy - Destroys an array.

Synopsis

void filp_array_destroy(struct filp_val * value);

Arguments

value

the array

Description

Destroys an array.

Name

filp_array_dim - Gives dimension to an array.

Synopsis

struct filp_val ** filp_array_dim(int asize);

Arguments

asize

the new size of the array

Description

Gives dimension to an array.

Name

filp_array_dup - Duplicates an array.

Synopsis

struct filp_val * filp_array_dup(struct filp_val * value);

Arguments

value

the array

Description

Duplicates the value array. A new value containing the same elements is returned.

Name

filp_array_expand - Inserts room in an array.

Synopsis

void filp_array_expand(struct filp_val * a, int offset, int num);

Arguments

a

the array

offset

offset where the room is to be open

num

number of elements to be inserted

Description

Inserts num empty elements in the offset of the a array.

Name

filp_array_get - Gets an element of an array.

Synopsis

struct filp_val * filp_array_get(struct filp_val * value, int i);

Arguments

value

the array

i

the subscript of the element

Description

Returns the element number i of the array value.

Name

filp_array_ins - Inserts a value in an array.

Synopsis

void filp_array_ins(struct filp_val * value, struct filp_val * e, int i);

Arguments

value

the array

e

the element to be inserted

i

subscript where the element is going to be inserted

Description

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.

Name

filp_array_seek - Seeks a string in an array.

Synopsis

int filp_array_seek(struct filp_val * value, char * str, int inc);

Arguments

value

the array

str

the string to be found

inc

element increment

Description

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.

Name

filp_array_set - Sets the value of an array's element.

Synopsis

struct filp_val * filp_array_set(struct filp_val * value, struct filp_val * e, int i);

Arguments

value

the array

e

the element to be assigned

i

the subscript of the element

Description

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.

Name

filp_array_size - Gets the size of an array.

Synopsis

int filp_array_size(struct filp_val * value);

Arguments

value

the array

Description

Returns the number of elements of the array.

Name

filp_array_sort - Sorts an array.

Synopsis

void filp_array_sort(struct filp_val * value, int inc);

Arguments

value

the value

inc

increment

Description

Sorts alphabetically the elements of the array. If inc is greater than 1, the elements are ordered in groups of that quantity.

Name

filp_bin_code - Creates a new binary code symbol.

Synopsis

int filp_bin_code(char * name, int (* func)(void));

Arguments

name

name of the new symbol

func

C code function

Description

Creates a new binary code (C code) symbol. This symbol can be directly executed by the filp parser.

Name

filp_cmp - Compares two filp values.

Synopsis

int filp_cmp(struct filp_val * v1, struct filp_val * v2);

Arguments

v1

first value

v2

second value

Description

Compares two filp values. Only must be used compare scalar values. Returns a value similar to that of strcmp().

Name

filp_code_push - Pushes a string to the stack, as filp code.

Synopsis

int filp_code_push(char * code);

Arguments

code

the string containing filp code

Description

Pushes a string to the stack as filp code. The code is not tested for integrity nor syntax.

Name

filp_destroy_symbol - Destroys a symbol.

Synopsis

void filp_destroy_symbol(struct filp_sym * s);

Arguments

s

the symbol to be destroyed

Description

Destroys a symbol and deletes it from the symbol table.

Name

filp_exec - Executes filp code.

Synopsis

int filp_exec(char * code)
/* runs a program (main parser) */;

Arguments

code

filp code to run

Description

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).

Name

filp_execf - Executes filp code, with formatting.

Synopsis

int filp_execf(char * code, ...);

Arguments

code

filp code with printf-like formatting

Description

Formats code as a printf() -like string, and executes it as filp code. See filp_exec() for return values.

Name

filp_execv - Executes filp code inside a filp value.

Synopsis

int filp_execv(struct filp_val * v);

Arguments

v

the value.

Description

Executes filp code inside a value. The value v must be binary code, filp code or a scalar containing filp code.

Name

filp_ext_file - Creates a new external file descriptor symbol.

Synopsis

int filp_ext_file(char * name, FILE * f);

Arguments

name

name of the new symbol

f

pointer to a FILE C descriptor

Description

Creates a new external file descriptor symbol. The file should be alread opened and never closed from the C code.

Name

filp_ext_int - Creates a new external C integer symbol.

Synopsis

int filp_ext_int(char * name, int * val);

Arguments

name

name of the new symbol

val

pointer to the integer

Description

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.

Name

filp_ext_real - Creates a new external C double symbol.

Synopsis

int filp_ext_real(char * name, double * val);

Arguments

name

name of the new symbol

val

pointer to the double float

Description

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.

Name

filp_ext_string - Creates a new external string symbol.

Synopsis

int filp_ext_string(char * name, char * val, int size);

Arguments

name

name of the new symbol

val

pointer to the string

size

size of the string

Description

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.

Name

filp_find_symbol - Finds a symbol by name.

Synopsis

struct filp_sym * filp_find_symbol(char * name);

Arguments

name

name of the symbol to be found

Description

Finds a symbol by name. Returns the symbol, or a NULL pointer if not found.

Name

filp_get_symbol - Gets the value of a symbol.

Synopsis

struct filp_val * filp_get_symbol(struct filp_sym * s);

Arguments

s

the symbol

Description

Gets the value of a symbol.

Name

filp_hash_del - Deletes a key-value pair from a hash.

Synopsis

struct filp_val * filp_hash_del(struct filp_val * h, char * key);

Arguments

h

the hash

key

the key

Description

Deletes a key-value pair from the hash given its key. If the pair exists, the value is returned, or NULL otherwise.

Name

filp_hash_get - Gets an element from a hash.

Synopsis

struct filp_val * filp_hash_get(struct filp_val * h, char * key);

Arguments

h

the hash

key

the key which value is wanted

Description

Returns the value associated with key form the hash h, or NULL if no one exists.

Name

filp_hash_get_pair - Gets a key-value pair from the hash.

Synopsis

int filp_hash_get_pair(struct filp_val * h, int i,
	struct filp_val ** key, struct filp_val ** value);

Arguments

h

the hash

i

the pair number

key

a pointer to store the key

value

a pointer to store the value

Description

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.

Name

filp_hash_set - Stores a key-value pair into a hash.

Synopsis

struct filp_val * filp_hash_set(struct filp_val * h, char * key,
	struct filp_val * value);

Arguments

h

the hash

key

the key

value

the value

Description

Stores a key-value pair into the hash. Returns the previously stored value under that key if one exists, or NULL otherwise.

Name

filp_hash_size - Returns the number of pairs of a hash.

Synopsis

int filp_hash_size(struct filp_val * h);

Arguments

h

the hash

Description

Returns the number of key-value pairs stored in the hash.

Name

filp_hashfunc - Hash function for the dictionary.

Synopsis

int filp_hashfunc(unsigned char * string, int mod);

Arguments

string

the string to be hashed

mod

modulus

Description

Calculates a hash for the string argument, to be used to search the dictionary. Returns the computed hash.

Name

filp_int_pop - Pops a value from the stack, as an integer value.

Synopsis

int filp_int_pop(void);

Description

Pops a value from the stack, as a C integer value. If the value has no meaning as a number, 0 is returned.

Name

filp_int_push - Pushes a C integer into the stack, as a scalar.

Synopsis

int filp_int_push(int value);

Arguments

value

integer value

Description

Pushes a C integer into the stack, previously converted to its printable value.

Name

filp_is_true - True condition tester.

Synopsis

int filp_is_true(struct filp_val * v);

Arguments

v

the value to be tested

Description

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".

Name

filp_list_size - Computes the size of a list.

Synopsis

int filp_list_size(void);

Description

Computes the size of a list.

Name

filp_load_exec - Loads and executes a filp code file.

Synopsis

int filp_load_exec(char * filename);

Arguments

filename

the name of the file contaning filp code

Description

Loads a file and executes it. See filp_exec() for the return values.

Name

filp_load_file - Loads a filp code file.

Synopsis

char * filp_load_file(char * filename);

Arguments

filename

the file to be loaded

Description

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.

Name

filp_new_bin_code_value - Creates a bin code value.

Synopsis

struct filp_val * filp_new_bin_code_value(int (* func)(void));

Arguments

func

the function to be used

Description

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.

Name

filp_new_hash - Creates a new hash.

Synopsis

struct filp_val * filp_new_hash(int buckets);

Arguments

buckets

number of buckets in the hash

Description

Creates a new hash. A filp hash is, internally, a filp array of buckets arrays.

Name

filp_new_int_value - Creates a new scalar from an int.

Synopsis

struct filp_val * filp_new_int_value(int value);

Arguments

value

the integer to be used as the value

Description

Creates a new scalar from the integer value. Returns the new value.

Name

filp_new_real_value - Creates a new scalar from a double.

Synopsis

struct filp_val * filp_new_real_value(double value);

Arguments

value

the double to be used as the value

Description

Creates a new scalar from the double value. Returns the new value.

Name

filp_new_symbol - Creates a new symbol.

Synopsis

struct filp_sym * filp_new_symbol(filp_type type, char * name);

Arguments

type

type of the new symbol

name

name of the new symbol

Description

Creates a new symbol. A pointer to it is returned.

Name

filp_new_value - Creates a new filp value.

Synopsis

struct filp_val * filp_new_value(filp_type type, void * value, int size);

Arguments

type

value type

value

the value

size

size of the value

Description

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.

Name

filp_null_push - Pushes a special NULL value to the stack.

Synopsis

int filp_null_push(void);

Description

Pushes a special NULL value to the stack.

Name

filp_poke - Stores a byte in a dynamic string.

Synopsis

char * filp_poke(char * ptr, int * size, int offset, int c);

Arguments

ptr

the string

size

size of the string

offset

offset where the byte should be stored

c

the byte to be stored

Description

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).

Name

filp_pop - Pops a value from the stack.

Synopsis

struct filp_val * filp_pop(void);

Description

Pops a value from the stack. Returns a special NULL filp value on stack underflow condition.

Name

filp_push - Pushes a value into the stack, duplicating it.

Synopsis

int filp_push(struct filp_val * v);

Arguments

v

the value to be pushed

Description

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.

Name

filp_push_dict - Pushes to the stack names of symbols.

Synopsis

int filp_push_dict(char * mask);

Description

Pushes to the stack all the symbol names that start with mask as a list.

Name

filp_push_symbol_value - Pushes a symbol value to the stack

Synopsis

void filp_push_symbol_value(char * symbol);

Arguments

symbol

the name of the symbol

Description

Pushes the value of a symbol to the stack, or a FILP_NULL value if symbol is not found.

Name

filp_real_pop - Pops a value from the stack, as a double value.

Synopsis

double filp_real_pop(void);

Description

Pops a value from the stack, as a C double float value. If the value has no meaning as a number, 0 is returned.

Name

filp_real_push - Pushes a C double into the stack, as a scalar.

Synopsis

int filp_real_push(double value);

Arguments

value

double float value

Description

Pushes a C double flaot into the stack, previously converted to its printable value.

Name

filp_ref_value - Increments the reference to a value

Synopsis

void filp_ref_value(struct filp_val * v);

Arguments

v

the value

Description

Increments the reference count of v. Values with a reference count > 0 will never be destroyed by the garbage collector.

Name

filp_rot - Rotates the stack.

Synopsis

void filp_rot(int pos);

Arguments

pos

offset of the element to be rotated

Description

Move the element number pos from the stack to the top.

Name

filp_scalar_push - Pushes a scalar into the stack.

Synopsis

int filp_scalar_push(char * value);

Arguments

value

the string containing the scalar

Description

Pushes a scalar into the stack. The scalar must be a string.

Name

filp_set_symbol - Sets a symbol to a value.

Synopsis

void filp_set_symbol(struct filp_sym * s, struct filp_val * v);

Arguments

s

the symbol to be set.

v

the value.

Description

Assigns the value v to the symbol s.

Name

filp_splice - Deletes and inserts text in an string

Synopsis

char * filp_splice(char * src, int offset, int size, char * new);

Arguments

src

the source string

offset

offset

size

number of chars to be substituted

new

new string to be inserted

Description

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.

Name

filp_stack_value - Returns the nth element of the stack.

Synopsis

struct filp_val * filp_stack_value(int pos);

Arguments

pos

offset in the stack

Description

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.

Name

filp_swap_stack - Commutes between the two stacks.

Synopsis

void filp_swap_stack(void);

Description

Commutes between the two stacks.

Name

filp_sweeper - Forces a garbage collection

Synopsis

void filp_sweeper(int full);

Arguments

full

full sweeping flag

Description

Forces a garbage collection. If full is nonzero, the complete value poll is checked; otherwise, only a small set of them are checked.

Name

filp_unref_value - Decrements the reference to a value

Synopsis

void filp_unref_value(struct filp_val * v);

Arguments

v

the value

Description

Decrements the reference count of v. Values with a reference count > 0 will never be destroyed by the garbage collector.

Name

filp_val_to_int - Converts a filp value to an int.

Synopsis

int filp_val_to_int(struct filp_val * v);

Arguments

v

the value to be converted

Description

Converts a filp value into an integer. Returns the integer.

Name

filp_val_to_real - Converts a filp value to a double.

Synopsis

double filp_val_to_real(struct filp_val * v);

Arguments

v

the value to be converted

Description

Converts a filp value into a double. Returns the integer.