This reference documents version 1.0.0-rc4-dev of the Filp Programming Language.
ARGV - Array of command-line arguments.
ARGV
This array contains the command-line arguments when used from the filp interpreter, or an empty array if used from an embedded version of the filp library.
NULL - Stores a NULL value on the top of stack.
NULL NULL [ NULL ( NULL
Stores a NULL value on the top of stack. Though [ is used as a delimiter for lists and ( for arrays, in practice all of them are the same.
STDERR - Standard error file descriptor.
STDERR
This is the standard error file descriptor.
STDIN - Standard input file descriptor.
STDIN
This is the standard input file descriptor.
STDOUT - Standard output file descriptor.
STDOUT
This is the standard output file descriptor.
abseek - Seeks a sorted array for a scalar.
array scalar abseek subscript
Seeks a sorted array in search of a string. Returns the subscript where the scalar is if positive, or the position where it should be if negative.
add - Math sum.
op1 op2 add result op1 op2 + result
Sums both values and sends the result to the stack. If filp_real is set, the operation is made in real mode, or integer otherwise.
adel - Deletes an element from an array.
array_symbol subscript adel array subscript adel modified_array
Deletes an element from an array. The array shrinks. If subscript is zero, the last element is deleted and if it's out of range, nothing happens.
adump - Dumps an array as a list.
array adump [ array_elements ]
Dumps an array as a list.
aget - Gets an element from an array.
array subscript @ element array subscript aget element
Gets the element number subscript from the array. If subscript is out of range, NULL is returned instead. The array subscripts in filp starts at 1; the 0 element contains the total number of elements in the array.
ains - Inserts a value into an array.
array_symbol subscript value ains array subscript value ains modified_array
Inserts a value into the subscript position of an array. The elements with greater subscripts move up one position, incrementing the total size of the array by 1. Remember that the array subscripts in filp start at 1. If the subscript is 0 (array size), the element is added to the end.
and - Boolean and.
bool1 bool2 and bool_result bool1 bool2 && bool_result
Returns true if both values are true. The command && can be used as a synonym.
array - Creates an array.
( value value ... ) new_array ( value value array new_array
Creates an array. The ) character can be used as a synonym, and it's preferred as it's more intuitive. The new array value is left on the top of stack, ready to be asigned or used.
aseek - Seeks an array for a scalar.
array scalar aseek subscript
Seeks an array in search of a string. Returns the subscript where the scalar is, or 0 if not found.
aset - Assigns a value to an element of an array.
array_symbol subscript value aset array subscript value aset modified_array
Assigns a value to the element subscript of an array. Remember that the array subscripts in filp start at 1. The @= command can be used as a synonym.
asort - Sorts an array.
array_symbol asort array asort sorted_array
Sorts (alfabetically) an array.
bread - Reads a block of bytes from a file.
size fdes bread size data
Reads a block of bytes from a file. The block of data and its size is returned. On EOF, the returned size will be zero.
bwrite - Writes a block of bytes to a file.
size data fdes bwrite
Writes a block of bytes to a file.
chop - Chops the last character of a string.
string chop strin
Chops the last character of a string. Mainly to be used to cut the trailing \n character of a line read from a file.
close - Closes a file.
fdes close
Closes a file.
defined - Tests if a symbol is defined.
symbol defined bool_result
Returns a boolean value telling whether the symbol is defined or not.
div - Math division.
divd divs div result divd divs / result
Divides divd by divs and sends the result to the stack. If filp_real is set, the operation is made in real mode, or integer otherwise.
dumper - Dumps a value (probably an array) as a tree.
value dumper value_tree
Dumps a value (probably an array) as a filp-parseable tree.
dup - Duplicates the value in the top of stack.
value dup value value
Duplicates the value in the top of stack.
dupnz - Duplicates the value in the top of stack if true.
value dupnz value value
Duplicates the value in the top of stack if it has a 'true' value.
enum - Defines a group of constants.
[ list_elements ] first enum
Defines a group of constants. The first (deeper in the stack) will have a value of first and so on, increasingly.
eq - String equality test.
string1 string2 eq bool_value
Compares the two strings and returns true if both are equal.
errno - The C library errno variable.
errno
This variable contains the C library errno variable.
eval - Executes a value as filp code and returns its error code.
value eval error_code
Executes a value as filp code. It can be a string or a block of code. The error code will be put on the top of stack, and the execution is never interrupted.
exec - Executes a value as filp code.
value exec
Executes a value as filp code. It can be a string or a block of code.
false - Stores a false value on the top of stack.
false false_value
Stores a conditional value equal to 'false' on the top of stack.
filp_arch - Architecture id string.
filp_arch
This string contains 'linux' if filp is running under any flavour of linux, 'win32' if under any flavour of MS Windows, 'beos' if under BeOS or 'unix' otherwise.
filp_bareword - Use of barewords flag.
filp_bareword
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_compile_date - Compilation date.
filp_compile_date
This string contains the date of compilation of the filp library.
filp_compile_options - Compilation options information.
filp_compile_options
This string contains human-readable information about possible compilation options or limitations.
filp_compile_time - Compilation time.
filp_compile_time
This string contains the time of compilation of the filp library.
filp_error - Last error code.
filp_error
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.
filp_error_info
This string contain additional info about the last error.
filp_error_strings - Array of error strings.
filp_error_strings
This array contains the message associated to an error message contained in filp_error.
filp_lang - Two letter code of the preferred language.
filp_lang
This variable contains the two letter code of the preferred language defined by the user. It mainly takes its value from the LANG environment variable, but other sources (mainly for win32) are tried as well.
filp_real - Use of real numbers instead of integers flag.
filp_real
This flag tells filp if it must perform mathematical operations using integers (by default) or real numbers.
filp_stack_elems - Number of elements currently in the stack.
filp_stack_elems
The number of elements currently stored in the stack.
filp_stack_size - Maximum size of the stack.
filp_stack_size
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_uname - Operating system information.
filp_uname
This string contains human-readable information about the operating system filp is running on.
filp_version - Version of filp.
filp_version
This string holds the current version of filp.
for - Executes a block incrementing a value.
from inc to code_block for
Executes the block of code, sending previously a value to the stack. This value ranges from the initial from value, being incremented by inc until to (inclusive). The block of code must take this value from the stack.
forall - Executes a block of code for all elements of the array
array { code } forall
Executes a block of code for each element of array after pushing each one to the stack. The code block must take the values from the top of stack on each iteration.
foreach - Executes a block of code for each element of a list.
[ list_elements ... ] code_block foreach
Executes a block of code for each element of a list, that is, until there is a NULL in the top of stack. The code block must take the values from the top of stack on each iteration. The NULL value is automatically dropped.
getdoc - Gets documentation from a symbol.
symbol getdoc documentation_string
Gets documentation from a symbol. If it hasn't any, it's name is returned instead.
getenv - Obtains the value of an environment string.
envvar getenv value
Obtains the value of an environment string (as PATH or HOME). Returns the value or NULL if the variable does not exist.
glob - Returns a list with a file expansion set.
filespec glob [ file_list ]
Returns a list with all the files that matches the filespec
expression. This filespec is system dependent, but any combination
of characters plus * or ? should work in all systems. The directory
separator is /, though \ can also be used on MS Windows; anyway, the
output list will always have / separators, that can also be used
in all supported systems as an argument for open() or similar.
gt - String 'greater than' test.
string1 string2 gt bool_value
Compares the two strings and returns true if the first one is greater (in ASCII) than the second one.
idup - Duplicates a specific value from the stack.
val#i val#i-1 ... val#1 i idup val#i
Creates a copy of the element number i from the stack, and leaves it in the first position. Stack elements start from 1.
if - Conditional execution of code.
bool code_block if
Executes the block of code if bool is true.
ifelse - Conditional execution of code.
bool code_block_true code_block_false ifelse
Executes the first block of code if bool is true or the second if false.
index - Extract an element from a list by subscript.
[ elements_of_list ] offset index value
Extract the element number offset from the list, and puts it on the top of stack. If the offset is out of range (i.e. there are less elements in the list), NULL is returned instead.
instr - Search a string inside another.
string substring instr offset
Search a substring inside a string. If it's found, the offset is returned, or 0 instead. Remember that string offsets start from 1.
join - Joins a list into a string.
[ list_elements ] joiner join string
Joins a list into a string, using the string joiner as a glue.
length - Returns the length of a string.
string length len
Returns the length of the string.
license - Returns the filp license.
license license_text
Returns a text string containing the license of the filp library (The GNU Public License, GPL).
load - Loads a filp source code file and executes it.
file_name load
Loads a filp source code file and executes it.
loop - The infinite loop.
code_block loop
Executes code_block until the end of times.
lsize - Returns the size of a list.
[ list_elements ] lsize number
Returns the number of elements of a list.
lt - String 'lower than' test.
string1 string2 lt bool_value
Compares the two strings and returns true if the first one is lower (in ASCII) than the second one.
map - Executes a block of code for all elements of the array modifying
array_symbol { code } map
array { code } map modified_array
Executes a block of code for each element of array after pushing each one to the stack. At the end of the block, the value in the top of stack will be assigned to the element. If array is an immediate value (i.e. not a symbol), the modified array is left on the stack.
mkdir - Creates a directory.
dirname mkdir
Creates a directory.
mod - Math modulo.
divd divs mod remainder divd divs % remainder
Divides divd by divs and sends the remainder to the stack. This operation is always made in integer mode regardless of the value of filp_real.
mul - Math multiply.
op1 op2 mul result op1 op2 * result
Multiplies both values and sends the result to the stack. If filp_real is set, the operation is made in real mode, or integer otherwise.
open - Opens a file.
"filename" open fdes ">filename" open fdes ">>filename" open fdes "+filename" open fdes "+>filename" open fdes "|program" open fdes "program|" open fdes
Opens a file. If no prefix is used, the file is open for reading; The valid prefixes are: '>', open for writing; '>>', open for appending; '+', reading and writing, positioned in the beginning; '+>', reading and writing, truncating; '|', treat the file name as a program which standard input will be the file. The valid suffixes are: '|', treat the file name as a program which standard output will be the file. Pipes doesn't work in MS Windows by now. Returns a file descriptor, or NULL if file could not be opened.
or - Boolean or.
bool1 bool2 or bool_result bool1 bool2 || bool_result
Returns true if any value are true. The command || can be used as a synonym.
pop - Drops a value from the top of stack.
value pop
Drops a value from the top of stack. The value is destroyed.
print - Prints a value to the standard output.
value print value ?
Prints a value to the standard output followed by a newline (\n). The command ? can be used as a synonym.
printwn - Prints a value to the standard output without newline.
value printwn value ??
Prints a value to the standard output. The command ?? can be used as a synonym.
putenv - Sets the value of an environment string.
envvar value putenv
Sets the value of an environment string.
read - Reads a line from a file.
fdes read line
Reads a line from a file. Returns the line or NULL on EOF.
regex - Matches a POSIX regular expression.
str re =~ bool_value str re regex bool_value
Tests if str matches the re POSIX regular expression. Returns true if the string matches. See the regex(7) man page for more information about POSIX regular expressions.
repeat - Executes a block of code a number of times.
times code_block repeat
Executes a block of code a number of times.
reverse - Reverses a list.
[ elem-1 elem-2 ... elem-n ] reverse [ elem-n ... elem-2 elem-1 ]
Reverses a list.
rot - Rotates the stack.
val#i val#i-1 ... val#1 i rot val#i-1 ... val#1 val#i
Rotates the stack. The element number i moves to the top of the stack, shifting all the upper ones one position down.
safe - Enters isolate mode
safe
Enters isolate mode, so all potentially dangerous commands as file access, environment variable definitions and external command executions are disabled. There is no turning back. When executed inside an 'eval' code, isolate mode operates only inside it.
seek - Seeks an element in a list.
[ elements_of_list ] value seek offset
Seeks an element in the list. If the element is found, its offset is returned on the top of stack; in not, 0 is returned instead. Take note that list elements are numbered from 1.
set - Sets the value of a symbol.
variable content set
variable content def
variable content =
command { content } set
Sets the value of a symbol. If the content is code surrounded by { } , the symbol is marked as executable and becomes a command, otherwise it will be a plain variable. The commands def and = can be used as synonyms of set.
setdoc - Set documentation for a symbol.
documentation_string symbol setdoc
Stores documentation for a symbol.
shell - Executes an external program.
program shell output_from_program
Executes an external program and sends all of its output to the stack.
size - Returns the size of a value.
value size size_in_bytes
Returns the size in bytes of the value. Note that this number is not necessary the same as the length.
sort - Sorts a list.
[ list_elements ] sort [ sorted_elements ]
Sorts a list.
split - Splits a string into substrings.
string separator split [ string_slices ]
Splits a string into a list by the separator. If separator is an empty string, string is splitted by char.
sprintf - Formats into a string.
value [ value ... ] format_string sprintf result_string
Makes a printf() -like formatting into a string. As in that
function, the percent char is used as a placeholder for
a formatting command.
sscanf - Scans a string and extracts values.
string format_string sscanf value1 value2 ...
Scans a string and extracts values using a scanf() -like
format string.
strcat - Concatenates two strings.
str1 str2 strcat str1str2 str1 str2 . str1str2
Concatenates two strings. The . command can be used as a synonym.
strerror - Returns the system error string.
errno strerror
Returns the system error string. errno must be the value of the filp_errno variable.
sub - Math substraction.
min subt sub result min subt - result
Substracts subt from min and sends the result to the stack. If filp_real is set, the operation is made in real mode, or integer otherwise.
substr - Extracts a substring.
string offset size substr substring
Extracts a substring from the string, starting at offset. Take note that string subscripts start from 1.
swap - Swaps the two values on top of the stack.
value2 value1 swap value1 value2 value2 value1 xchg value1 value2 value2 value1 # value1 value2
Swaps the two values on top of the stack. The commands xchg or # are synonyms.
sweep - Collects garbage.
sweep
Calls the internal garbage collector.
switch - Multiple conditional execution.
[ condition_code execute_code ... ] switch
Executes from top to down the condition block codes and, if
one of them returns a true value, executes the associated execution
code block and continues on the next instruction. The first
condition / execution code pairs being run are the nearest to
the switch instruction, and all of them are really a list, so
the [ terminator must not be forgotten. To implement a clause
similar to the 'default' one from the C language switch() command,
it must be the last one and its condition code be always true.
swstack - Swaps between the two stacks.
swstack
Filp has two stacks, one on use and the other 'dormant'. This command swaps between the two stacks. It's used basicly when a running process can destroy valid information stored in the current stack, so this command puts it in a safe place. The variable filp_stack_elems is set accordingly.
symbol - Sends symbol names to the stack.
prefix symbol [ symbols ... ]
Sends to the stack as a list all symbol names beginning with prefix. If prefix is "" (the empty string), all symbol names will be pushed.
time - Returns the time in seconds.
time time_t
Returns the time in seconds. This is the value returned by the
C function time().
timer - millisecond timer
timer msec_timer
Returns a millisecond timer.
tpop - Stores the top of stack into the temporal variable.
value tpop
Stores the top of stack into the temporal variable ($_).
tpush - Pushes the temporal variable to the stack.
tpush value
Pushes the temporal variable ($_) to the stack.
true - Stores a true value on the top of stack.
true true_value
Stores a conditional value equal to 'true' on the top of stack.
type - Returns a string describing the type of a value.
value type type_string
Returns a string describing the type of a value. If value is a name of a symbol, the type of its content is returned; otherwise, the value type itself is returned. The returned value can be one of SCALAR, CODE, BIN_CODE, EXT_INT, EXT_REAL, EXT_STRING, NULL, FILE or ARRAY.
unless - Conditional execution of code.
bool code_block unless
Executes the block of code if bool is false.
unset - Undefines a variable.
<variable> unset <variable> undef
Undefines a variable. The command undef is a synonym.
val - Returns the value of a symbol.
string val content
Treats the string as a symbol name and returns its value. If it does not exist as a symbol, NULL is returned instead.
while - Conditional loop.
condition_code repeat_code while
While the execution of condition_code returns a non-NULL value, repeat_code is also executed, having that value available in the top of stack for being processed. The NULL result of condition_code is clean from the stack.
write - Writes a string to a file.
string fdes write
Writes a string to a file.