triptico.com

Un naufragio personal

The Filp C API

This reference documents version 1.0.0-rc4-dev of the C API.

By Source

filp_array.c

filp_core.c

filp_parse.c

filp_util.c

Alphabetical

_filp_bareword

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.

_filp_dict

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.

_filp_error

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.

_filp_error_info

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.

_filp_isolate

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.

_filp_parse_string

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.

_filp_real

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.

_filp_stack

Name

_filp_stack - Pointer to the stack.

Synopsis

 static struct filp_stack *_filp_stack = NULL;

Description

This variable stores the stack in use.

_filp_stack_elems

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.

_filp_stack_size

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.

_filp_swap_stack

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.

_filp_version

Name

_filp_version - Version of filp.

Synopsis

 char _filp_version[] = VERSION;

Description

This string holds the current version of filp.

filp_array_binary_seek

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.

filp_array_collapse

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.

filp_array_del

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.

filp_array_destroy

Name

filp_array_destroy - Destroys an array.

Synopsis

 void filp_array_destroy(struct filp_val *value);

Arguments

value
the array

Description

Destroys an array.

filp_array_dim

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.

filp_array_dup

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.

filp_array_expand

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.

filp_array_get

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.

filp_array_ins

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.

filp_array_seek

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.

filp_array_set

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.

filp_array_size

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.

filp_array_sort

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.

filp_bin_code

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.

filp_cmp

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

filp_code_push

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.

filp_destroy_symbol

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.

filp_exec

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

filp_execf

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.

filp_execv

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.

filp_ext_file

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.

filp_ext_int

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.

filp_ext_real

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.

filp_ext_string

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.

filp_find_symbol

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.

filp_get_symbol

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.

filp_hash_del

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.

filp_hash_get

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.

filp_hash_get_pair

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.

filp_hash_set

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.

filp_hash_size

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.

filp_hashfunc

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.

filp_int_pop

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.

filp_int_push

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.

filp_is_true

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

filp_list_size

Name

filp_list_size - Computes the size of a list.

Synopsis

 int filp_list_size(void);

Description

Computes the size of a list.

filp_load_exec

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.

filp_load_file

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.

filp_new_bin_code_value

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.

filp_new_hash

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.

filp_new_int_value

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.

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

filp_new_symbol

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.

filp_new_value

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.

filp_null_push

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.

filp_poke

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

filp_pop

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.

filp_push

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.

filp_push_dict

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.

filp_push_symbol_value

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.

filp_real_pop

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.

filp_real_push

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.

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

filp_rot

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.

filp_scalar_push

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.

filp_set_symbol

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.

filp_splice

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.

filp_stack_value

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.

filp_swap_stack

Name

filp_swap_stack - Commutes between the two stacks.

Synopsis

 void filp_swap_stack(void);

Description

Commutes between the two stacks.

filp_sweeper

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.

filp_unref_value

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.

filp_val_to_int

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.

filp_val_to_real

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.


Angel Ortega - angel@triptico.com - Built with mp_doccer 1.2.2-dev

Related

Visitor comments

hard
2010-05-14
ti is good