GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
LIBFTH(3) FreeBSD Library Functions Manual LIBFTH(3)

libfth — Forth script and extension language library

library “libfth”

#include <fth.h>

This is the Fth library manual page. One can include Fth library functions in applications and in C extension libraries. The following shows example for each:

% cat hello.c
#include <fth.h>
int
main(int argc, char *argv[])
{
    fth_init();
    fth_printf("%s, World%c\n", "Hello", '!');
    return (EXIT_SUCCESS);
}

Compile and link it with:

% cc -I/usr/local/include/fth -c hello.c
% cc hello.o -o hello -L/usr/local/lib -lfth -lm
A test run looks like this:
% ./hello ⇒ Hello, World!

% cat libhello.c
#include <fth.h>

/*
 * hello-prim ( str1 -- str2 )
 * intro hello-prim ⇒ "Hello, World!"
 */
static void
ficl_hello_primitive(ficlVm *vm)
{
    FTH intro, world, result;

    FTH_STACK_CHECK(vm, 1, 1);
    intro = fth_pop_ficl_cell(vm);
    world = fth_variable_ref("world");
    result = fth_make_string_format("%S, %S!", intro, world);
    fth_push_ficl_cell(vm, result);
}

/*
 * hello-proc ( str1 -- str2 )
 * intro hello-proc ⇒ "Hello, World!"
 */
static FTH
fth_hello_procedure(FTH intro)
{
    FTH world, result;

    world = fth_variable_ref("world");
    result = fth_make_string_format("%S, %S!", intro, world);
    return (result);
}

void
Init_libhello(void)
{
    fth_define_variable("intro",
        fth_make_string("Hello"), NULL);
    fth_define_constant("world",
        fth_make_string("World"), NULL);
    FTH_PRI1("hello-prim",
        ficl_hello_primitive, NULL);
    FTH_PROC("hello-proc",
        fth_hello_procedure, 1, 0, 0, NULL);
}

Compile and link it with:

% cc -fPIC -I/usr/local/include/fth -c libhello.c
% cc -shared -o libhello.so libhello.o -L/usr/local/lib -lfth -lm
Installing isn't necessarily required for testing. Start fth and load the new library with
dl-load ./libhello.so Init_libhello
or start fth and load the library direct from the command line
% fth -S "./libhello.so Init_libhello"
The new words hello-prim and hello-proc as well as the variable intro and the constant world are available. In the following, ‘%’ is the shell prompt and ‘ok’ is the forth prompt 
% fth -Qq
ok dl-load ./libhello.so Init_libhello
ok intro hello-prim ⇒ "Hello, World!"
ok intro hello-proc ⇒ "Hello, World!"
ok "Goodbye" to intro
ok intro hello-prim ⇒ "Goodbye, World!"
ok "Bye" hello-proc ⇒ "Bye, World!"
ok bye
%
Or test it from the command line: 
% fth -S "./libhello.so Init_libhello" \
    -e 'intro hello-prim . cr' \
    -e 'intro hello-proc . cr' \
    -e '"Goodbye" to intro' \
    -e 'intro hello-prim . cr' \
    -e '"Bye" hello-proc . cr'
If the new library is finished, one can install it with
% fth -ve "install libhello.so" -e ""
After installing you can load your new library with
dl-load libhello Init_libhello

A short Array Object Type example in C:

FTH ary = fth_make_array_var(2, FTH_ZERO, FTH_ONE);

fth_array_length(ary);          ⇒ 2
fth_array_ref(ary, 0);          ⇒ 0
fth_array_push(ary, FTH_TWO);   ⇒ #( 0 1 2 )
fth_array_length(ary);          ⇒ 3
fth_array_shift(ary);           ⇒ 0
fth_array_shift(ary);           ⇒ 1
fth_array_shift(ary);           ⇒ 2
fth_array_length(ary);          ⇒ 0

FTH ary_each(FTH val, FTH data, ficlIndex idx)
{
    return (fth_string_sformat(data, "array[%d]: %S\n", idx, val));
}

FTH ary_map(FTH val, FTH data)
{
    return (fth_number_mul(val, data));
}

ary = fth_make_array_var(3, FTH_ZERO, FTH_ONE, FTH_TWO);

fth_array_each_with_index(ary, ary_each, fth_make_empty_string());
                                ⇒ "array[0]: 0\n ..."
fth_array_map(ary, ary_map, INT_TO_FIX(10));
                                ⇒ #( 0 10 20 )
int (obj)
Returns 1 if obj is an Array object, otherwise 0.
FTH (FTH array1, FTH array2)
Appends two arrays and returns new one. If array2 is not an array, appends it as a single element.
void (FTH array)
Clears array and sets all elements to #f.
FTH (FTH array)
Returns Array object with all nil elements removed.
FTH (FTH array)
Returns copy of array with all elements new created in contrast to fth_array_to_array.
FTH (FTH array, ficlInteger index)
Deletes and returns one element from array at position index. Negative index counts from backward. Raises out-of-range exception if index is not in array's range.
FTH (FTH array, FTH key)
Deletes and returns key from array if found, or #f.
FTH (FTH array, FTH (*func)(FTH value, FTH data), FTH data)
Loops through entire array and calls func on each element. 
/*
 * #( 0 1 ) value ary
 * each { val }
 *     "%s\n" #( val ) fth-print
 * end-each
 */
static FTH ary_each(FTH val, FTH data)
{
    fth_printf("%S\n", val);
    return (data);
}

fth_array_each(hs, ary_each, FTH_NIL);
FTH (FTH array, FTH (*func)(FTH value, FTH data, ficlInteger idx), FTH data)
Loops through entire array and calls func on each element with current index. 
/*
 * #( 0 1 ) value ary
 * each { val }
 *     "%d: %s\n" #( i val ) fth-print
 * end-each
 */
static FTH ary_each(FTH val, FTH data, ficlInteger idx)
{
    fth_printf("%d: %S\n", idx, val);
    return (data);
}

fth_array_each_with_index(hs, ary_each, FTH_NIL);
int (FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are Array objects of same length and contents, otherwise 0.
FTH (FTH array, FTH value)
Sets all elements of array to value.
FTH (FTH array, FTH key)
Returns key if key exists in array.
ficlInteger (FTH array, FTH key)
Returns index of key in ary, or -1 if not found.
FTH (FTH array, ficlInteger index, FTH value)
Inserts value to array at position index and returns changed array. value can be any single object or an array. Negative index counts from backward. Raises out-of-range exception if index is not in array's range.
FTH (FTH array, FTH sep)
Returns string with all elements of array converted to their string representation and joined together separated by sep. If sep is not a string, a space will be used as separator.
ficlInteger (FTH obj)
Returns length if obj is an Array object, otherwise -1.
FTH (FTH array, FTH (*func)(FTH value, FTH data), FTH data)
Runs func for each element. func's return value is the new value at current index. 
/*
 * #( 0 1 ) map
 *     *key* 10 +
 * end-map ⇒ #( 10 11 )
 */
static FTH ary_map(FTH val, FTH data)
{
    return (fth_number_add(val, data));
}

fth_array_map(ary, ary_map, INT_TO_FIX(10));
    ⇒ #( 10 11 )
int (FTH array, FTH key)
Returns 1 if key exists in ary, otherwise 0.
FTH (FTH array)
Removes and returns last element of array. If array is empty, returns #f.
FTH (FTH array, FTH value)
Appends value, which may be any object, to array.
FTH (FTH array, ficlInteger index)
Returns element at position index. Negative index counts from backward. Raises out-of-range exception if index is not in array's range.
FTH (FTH array, FTH proc_or_xt, FTH args)
Calls proc-or-xt with the current array element as first arg and the rest from args, an array of zero or more proc arguments. The length of args + 1 is the required arity of proc-or-xt. If args is nil, an empty array is used, if is any other object, wraps it in an array of length 1. Removes all elements from array where proc-or-xt results not in #f, nil, or 0. 
/*
 * #( 0 1 2 3 4 ) lambda: <{ n1 n2 -- f }>
 *     n1 n2 >
 * ; #( 2 ) array-reject! ⇒ #( 0 1 2 )
 * \ or a bit shorter:
 * #( 0 1 2 3 4 ) <'> > 2 array-reject! ⇒ #( 0 1 2 )
 */
FTH prc = fth_proc_ref(">");
FTH ary = fth_make_array_var(5,
    FTH_ZERO, FTH_ONE, FTH_TWO, FTH_THREE, FTH_FOUR):
fth_array_reject(ary, prc, FTH_TWO);    ⇒ #( 0 1 2 )
FTH (FTH array)
Returns array in reversed order.
FTH (FTH array, ficlInteger index, FTH value)
Stores value at position index and returns value. Negative index counts from backward. Raises out-of-range exception if index is not in array's range.
FTH (FTH array)
Removes and returns first element of array. If array is empty, returns #f.
FTH (FTH array, FTH proc_or_xt)
Returns sorted array. proc-or-xt compares two elements A and B and should return a negative integer if A < B, 0 if A == B, and a positive integer if A > B. Raises bad-arity exception if proc-or-xt doesn't take two arguments. 
FTH ary_sort(FTH a, FTH b)
{
    if (fth_number_less_p(a, b))
	return (FTH_ONE_NEG);
    if (fth_number_equal_p(a, b))
	return (FTH_ZERO);
    return (FTH_ONE);
}
FTH prc = fth_make_proc_from_func("int-sort", ary_sort, 0, 2, 0, 0);
FTH ary = fth_make_array_var(3, FTH_TWO, FTH_ONE, FTH_ZERO);
fth_array_sort(ary, prc); ⇒ #( 0 1 2 )
FTH (FTH array, ficlInteger start, ficlInteger end)
Returns array built from array beginning with index start up to and excluding index end. Negative index counts from backward. Raises out-of-range exception if start is not in ary's range.
FTH (FTH array)
Returns copy of array only with references of each element in contrast to fth_array_copy. If array is not an array, returns #( array ).
FTH (FTH obj)
Returns copy of obj as list only with references of each element in contrast to array-copy. If obj is not an array, returns '( obj ).
FTH (FTH array)
Returns array without duplicated elements.
FTH (FTH array, FTH value)
Preprends value to array.
FTH (ficlInteger len)
Returns Array object with len entries.
FTH (ficlInteger len, ...)
Returns Array object with len entries, initialized with values taken from the function argument list.
FTH (ficlInteger len, FTH init)
Returns Array object with len entries each initialized to init.
FTH (void)
Returns an empty Array object with length 0.

FTH (FTH assoc, FTH key)
If key matches, returns corresponding key-value pair, otherwise #f.
FTH (FTH assoc, FTH key)
If key matches, returns corresponding value, otherwise #f.
FTH (FTH assoc, FTH key)
If key matches, removes key-value pair from assoc. Returns current assoc.
FTH (FTH assoc, FTH key, FTH value)
 
FTH (FTH assoc, FTH key, FTH value)
If key matches, sets key-value pair, otherwise adds new pair to assoc. Returns current assoc.

int (obj)
Returns 1 if obj is a list (nil or List object), otherwise 0.
int (obj)
 
int (obj)
Return 1 if obj is a List object, otherwise 0.
FTH (FTH list)
 
FTH (FTH list)
 
FTH (FTH list)
 
FTH (FTH list)
First, second, third, or fourth element of list or nil if list is shorter.
FTH (FTH list)
 
FTH (FTH list)
Rest, the cdr or cddr, of list without first or first and second element.
FTH (FTH value, FTH list)
 
FTH (FTH obj1, FTH obj2, FTH list)
Returns Lisp-like cons pointer with value as car and list as cdr or obj1 as car, obj2 as cadr and list as cddr.
FTH (FTH args)
If args is not an Array or List object, returns nil, otherwise returns new List object with each element of args concatenated with fth_array_append.
FTH (FTH list)
Returns copy of list with all elements new created in contrast to fth_list_to_array.
ficlInteger (FTH obj)
Returns length if obj is a list (nil or List object), otherwise -1.
FTH (FTH list, FTH key)
Returns #t if key exists in list, otherwise #f.
FTH (FTH list, ficlInteger index)
Returns element at position index of list. Negative index counts from backward. Raises out-of-range exception if index is not in list's range.
FTH (FTH list)
Returns new list with elements reversed.
FTH (FTH list, ficlInteger index, FTH value)
Stores element value at position index in list and returns value. Negative index counts from backward. Raises out-of-range exception if index is not in list's range.
FTH (FTH list)
Returns copy of list as array only with references of each element in contrast to fth_list_copy. If lst is not a List object, returns #( lst ).
FTH (void)
Returns an empty List object with length 0.
FTH (ficlInteger len)
Returns List object with len entries.
FTH (ficlInteger len, ...)
Returns List object with len entries, initialized with values taken from function argument list.
FTH (ficlInteger len, FTH init)
Returns List object with len entries each initialized to init.

FTH (FTH key, FTH value, FTH alist)
Returns new Lisp-like associated list from key-value pair and alist.
FTH (FTH alist, FTH key)
If key matches, returns corresponding key-value pair, otherwise #f.
FTH (FTH alist, FTH key)
If key matches, returns corresponding value, otherwise #f.
FTH (FTH alist, FTH key)
If key matches, removes key-value pair from alist. Returns current alist.
FTH (FTH alist, FTH key, FTH value)
If key matches, sets key-value pair, otherwise adds new pair to alist. Returns current alist.

General file functions:

FTH (const char *name)
If name is a file, returns last access time.
FTH (const char *name, const char *ext)
Returns basename of file name depending on ext. If ext is NULL, returns from last slash to last dot in name, otherwise use ext as delimiter. 
fth_file_basename("/home/mike/cage.snd", NULL);
    ⇒ "cage"
fth_file_basename("/home/mike/cage.snd", ".snd");
    ⇒ "cage"
fth_file_basename("/home/mike/cage.snd", "nd");
    ⇒ "cage.s"
fth_file_basename("/home/mike/cage.snd", " ");
    ⇒ "cage.snd"
void (const char *name, mode_t mode)
Changes access mode of file name to mode, see chmod(2).
void (const char *src, const char *dst)
Copies file src to dst. If dst is a directory, copy src to dst/src. Raises system-error exception if fopen(3) fails on any of the two files.
FTH (const char *name)
If name is a file, returns status change time.
void (const char *name)
If file name exists, delete it, otherwise do nothing, see unlink(2).
FTH (const char *name)
Returns directory part of name.
int (const char *src, const char *dst, mode_t mode)
Installs src to dst with access mode if dst doesn't exist or if modification time of src is greater than dst's. If dst is a directory, installs src to dst/src. Returns 1 if src could be installed, otherwise 0.
FTH (const char *name)
If name is a file, returns length in bytes.
FTH (FTH string, FTH regexp)
Returns an array of filenames in directory string matching regexp.
void (const char *name, mode_t mode)
Creates directory name with access mode, see mkdir(2).
void (const char *name, mode_t mode)
Creates fifo file name with access mode, see mkfifo(2).
FTH (const char *name)
If name is a file, returns last modification time.
FTH (const char *name)
If name starts with ‘~’, replace it with contents of environment variable HOME. If realpath(3) function exists, returns resolved path, otherwise returns name with ‘~’ replacement.
void (const char *src, const char *dst)
Renames src to dst, see rename(2).
void (const char *name)
Removes empty directory name, see rmdir(2).
FTH (const char *name)
Splits name in dirname and basename and returns the result in an array of two strings.
Creates symlink from src to dst, see symlink(2).

int (const char *name)
Returns 1 if name is a block special file, see test(1) option -b.
int (const char *name)
Returns 1 if name is a character special file, see test(1) option -c.
int (const char *name)
Returns 1 if name is a directory, see test(1) option -d.
int (const char *name)
Returns 1 if name is an executable file, see test(1) option -x.
int (const char *name)
Returns 1 if name is an existing file, see test(1) option -e.
int (const char *name)
Returns 1 if name is a named pipe, see test(1) option -p.
int (const char *name)
Returns 1 if name matches effective group id, see test(1) option -G.
int (const char *name)
Returns 1 if name matches effective user id, see test(1) option -O.
int (const char *name)
Returns 1 if name is a readable file, see test(1) option -r.
int (const char *name)
Returns 1 if name has group id flag set, see test(1) option -g.
int (const char *name)
Returns 1 if name has user id flag set, see test(1) option -u.
int (const char *name)
Returns 1 if name is a socket, see test(1) option -S.
int (const char *name)
Returns 1 if name has sticky bit set, see test(1) option -k.
Returns 1 if name is a symbolic link, see test(1) option -h.
int (const char *name)
Returns 1 if name is a writable file, see test(1) option -w.
int (const char *name)
Returns 1 if length of file name is zero.

A short Hash Object Type example in C:

FTH hs = fth_hash_set(FTH_FALSE,
    fth_symbol("a"),
    fth_make_array_var(3, FTH_ZERO, FTH_ONE, FTH_TWO));
fth_printf("%S\n", hs);
fth_hash_set(hs, fth_symbol("b"), fth_make_string("text"));
fth_printf("%S\n", hs);
fth_hash_ref(hs, fth_symbol("a"));    ⇒ #( 0 1 2 )
fth_hash_ref(hs, fth_symbol("b"));    ⇒ "text"
fth_hash_ref(hs, fth_symbol("c"));    ⇒ #f
fth_hash_delete(hs, fth_symbol("a")); ⇒ '( 'a #( 0 1 2 ) )
fth_printf("%S\n", hs);               ⇒ #{ 'b ⇒ "text" }
fth_hash_clear(hs);
fth_printf("%S\n", hs);               ⇒ #{}

FTH hs_each(FTH key, FTH val, FTH data)
{
    return (fth_string_sformat(data, "%S: %S\n", key, val));
}

FTH hs_map(FTH key, FTH val, FTH data)
{
    (void)key;
    return (fth_number_mul(val, data));
}

fth_hash_set(fth_symbol("a"), FTH_SIX);
fth_hash_each(hs, hs_each, fth_make_empty_string());
                                      ⇒ "'a: 6\n"
fth_hash_map(hs, hs_map, INT_TO_FIX(10));
                                      ⇒ #{ 'a ⇒ 60 }

C functions follow handling Hash Object Types:

int (obj)
Returns 1 if obj is a Hash object, otherwise 0.
void (FTH hash)
Removes all entries from hash, hash's length becomes zero.
FTH (FTH hash)
Returns copy of hash using object-copy for all elements.
FTH (FTH hash, FTH key)
Deletes key-value pair associated with key and returns key-value array, or #f if not found.
FTH (FTH hash, FTH (*func)(FTH key, FTH val, FTH data), FTH data)
Runs func for each key-value pair. 
/*
 * #{ 'a 0 'b 1 } value hs
 * lambda: <{ key val -- }>
 *     "%s=%s\n" #( key val ) fth-print
 * ; hash-each
 */
static FTH hs_each(FTH key, FTH val, FTH data)
{
    fth_printf("%S=%S\n", key, val);
    return (data);
}

fth_hash_each(hs, hs_each, FTH_NIL);
int (FTH obj1, FTH obj2)
Returns #t if obj1 and obj2 are Hash objects with same length and contents.
FTH (FTH hash, FTH key)
Returns key-value array if key exists, or #f if not found.
FTH (FTH hash)
Returns array of keys.
ficlInteger (FTH obj)
Returns length if obj is a Hash object, otherwise -1.
FTH (FTH hash, FTH (*func)(FTH key, FTH val, FTH data), FTH data)
Runs func for each key-value pair. func's return value is the new value for key. 
/*
 * #{ 'a 0 'b 1 } value hs
 * lambda: <{ key val -- val }>
 *     val 10 +
 * ; hash-map
 */
static FTH hs_map(FTH key, FTH val, FTH data)
{
    (void)key;
    return (fth_number_add(val, data);
}

fth_hash_map(hs, hs_map, INT_TO_FIX(10));
    ⇒ #{ 'a => 10  'b => 11 }
int (FTH hash, FTH key)
Returns #t if key exists, otherwise #f.
FTH (FTH hash, FTH key)
Returns associated value, or #f if key was not found.
FTH (FTH hash, FTH key, FTH value)
If hash is not a Hash Object type, creates new hash. Sets key-value pair of hash. If key exists, overwrites existing value, otherwise creates new key-value entry. Returns new updated hash.
FTH (FTH hash)
Returns array with #( key value ) pairs of hash's contents. 
/* #{ 'a 0  'b 1 } value hs */
FTH ary = fth_hash_to_array(hs); ⇒ #( #( 'a 0 ) #( 'b 1 ) )
FTH (FTH hash)
Returns array of values.
FTH (void)
Returns fresh empty Hash object.
FTH (int hashsize)
Returns new empty Hash object of hashsize buckets instead of the default FTH_DEFAULT_HASH_SIZE.

There exists a global hash properties variable, which can be used for every kind of information. Furthermore, every object created with fth_make_instance as well as every ficlWord has a property-slot, for those see object-properties as well as word-properties.

Usage of properties:

FTH pr = fth_properties(FTH_FALSE);  ⇒ #{}
fth_hash_length(pr);                 ⇒ 0

FTH obj = fth_make_string("string");
pr = fth_properties(obj);            ⇒ #f
fth_hash_length(pr);                 ⇒ 0
fth_property_set(obj,
    fth_symbol("a"),
    fth_make_string("hello"));
pr = fth_properties(obj);            ⇒ #{ 'a "hello" }
fth_property_ref(obj, fth_symbol("a"));
                                     ⇒ "hello"
fth_hash_length(pr);                 ⇒ 1
FTH (FTH obj)
Returns obj's property from the global properties hash, or #f if empty. If obj is #f, returns entire global properties hash.
FTH (FTH obj, FTH key)
Returns obj's value associated with key from the global properties hash variable, or #f.
void (FTH obj, FTH key, FTH value)
Sets key-value pair for obj at the global properties hash variable. If key already exists, overwrites old value.

Usage of object-properties:

FTH obj = fth_make_string("string");
FTH pr = fth_object_properties(obj); ⇒ #f
fth_hash_length(pr);                 ⇒ 0
fth_object_property_set(obj,
    fth_symbol("a"),
    fth_make_string("hello"));
pr = fth_object_properties(obj);     ⇒ #{ 'a "hello" }
fth_object_property_ref(obj, fth_symbol("a"));
                                     ⇒ "hello"
fth_hash_length(pr);                 ⇒ 1
FTH (FTH obj)
Returns obj's properties, or #f if empty.
FTH (FTH obj, FTH key)
Returns obj's property value associated with key, or #f if not found.
void (FTH obj, FTH key, FTH value)
Sets key-value pair to obj's property object. If key already exists, overwrites old value.

Usage of word-properties:

FTH obj = fth_proc_ref("noop");
FTH pr = fth_word_properties(obj);   ⇒ #f
fth_hash_length(pr);                 ⇒ 0
fth_word_property_set(obj,
    fth_symbol("a"),
    fth_make_string("hello"));
pr = fth_word_properties(obj);       ⇒ #{ 'a "hello" }
fth_word_property_ref(obj, fth_symbol("a"));
                                     ⇒ "hello"
fth_hash_length(pr);                 ⇒ 1
FTH (FTH obj)
Returns properties of obj, a ficlWord or Proc object, or #f.
FTH (FTH obj, FTH key)
Returns value associated with key of property hash of obj, a ficlWord or Proc object, or #f.
void (FTH obj, FTH key, FTH value)
Sets key-value pair property hash of obj, a ficlWord or Proc object. If key already exists, overwrites old value.

int (obj)
Returns 1 if obj is a Hook object, otherwise 0.
void (FTH hook, FTH proc)
Add hook procedure proc to hook. Raises bad-arity exception if proc's arity doesn't match hook's arity.
FTH (FTH hook, FTH args, const char *caller)
Runs each of hook's procedures with args, a single argument or an array of arguments, and returns an array of results of all hook-procedures. caller is an arbitrary string for some exception information. Raises bad-arity exception if args's length doesn't match hook's arity.
int (FTH hook)
Returns hook's required arguments.
void (FTH hook)
Removes all of hook's procedures.
int (FTH hook)
Returns 1 if hook has no hook procedures, otherwise 0.
int (FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are Hook objects with same arity and procedures, otherwise 0.
int (FTH hook, FTH name)
Returns 1 if hook has procedure name, otherwise 0. name can be a string, an xt or a Proc object.
FTH (FTH hook)
Returns array of all of hook's procedure names (strings).
FTH (FTH hook)
Returns array of all of hook's procedures.
FTH (const char *name, int arity, const char *doc)
Returns new Hook object name, arity required arguments, 0 optional arguments and no rest arguments, doc becomes the documentation of the hook.
FTH (const char *name, int req, int opt, int rest, const char *doc)
Returns new Hook object name, req required arguments, opt optional arguments and rest rest arguments, doc becomes the documentation of the hook.
FTH (int arity)
Returns new Hook object with arity required arguments, 0 optional arguments and no rest arguments.
FTH (FTH hook, FTH name)
Removes hook procedure name from hook and returns it. name can be a string, an xt or a Proc object.
FTH (FTH hook, int len, ...)
Runs each of hook's procedures with len arguments and returns an array of results of all hook-procedures. Raises bad-arity exception if len doesn't match hook's arity.
FTH (FTH hook, int len, ...)
For concatenating strings; the return value of a proc_n is set as index 0 of the input args-list for proc_n + 1. Runs each of hook's procedures with len arguments and returns the last result. Raises bad-arity exception if len doesn't match hook's arity.
FTH (FTH hook, int len, ...)
Runs each of hook's procedures with len arguments and returns #t if hook is empty or any of the procedures didn't return #f. Raises bad-arity exception if len doesn't match hook's arity.

There are several IO functions for manipulating file and pipe streams, strings and sockets. Functions like fth_io_read and fth_io_write handle file, pipe, string, and socket IO objects.

int (obj)
Returns 1 if obj is an IO object, otherwise 0.
void (FTH io)
Flushes and closes io object and sets closed? to 1.
int (FTH obj)
Returns 1 if io object is closed, otherwise 0.
int (FTH io)
Returns 1 if EOF is reached, otherwise 0.
int (FTH obj1, FTH obj2)
Returns #t if obj1 and obj2 are IO objects with equal filenames, modes and file positions.
char* (FTH io)
Returns filename of io object or NULL if filename is not available. If io is a socket, it will return the hostname instead.
int (FTH io)
Returns file descriptor of io.
void (FTH io)
Flushes io object.
int (FTH io)
Returns next character from io object or EOF.
int (FTH obj)
 
int (FTH obj)
Returns 1 if obj is an in- or output IO object, otherwise 0.
ficl2Integer (FTH obj)
Returns length of OBJ.
int (FTH io)
Returns access mode of io object.
FTH (const char *host, int port, int domain, int type, int fam)
Opens a new socket server or connects to an already established one and returns a corresponding IO object or, if something went wrong, #f. host is a host name (AF_INET/AF_INET6) or a path name (AF_UNIX). port is the connection port if domain is AF_INET/AF_INET6, otherwise unused, and domain can be AF_INET6, AF_INET, or AF_UNIX, type can be SOCK_STREAM or SOCK_DGRAM. socket(2) is opened with domain, type, and hard-coded flag 0. fam can be FICL_FAM_CLIENT or FICL_FAM_SERVER. 
/* port = 17: Quote Of The Day (qotd of inetd(1)) */
int fam = FICL_FAM_CLIENT;
FTH io = fth_io_nopen("localhost", 17,
    AF_INET6, SOCK_STREAM, fam);

while (!fth_io_eof_p(io))
    fth_printf("%s", fth_io_read(io));

fth_io_close(io);

/*
 * A server at port 2002 at one terminal (test_server):
 *
 * % ./test_server  ⇒ the server will print to *stdout*
 *                     when a client sends
 */
int fam = FICL_FAM_SERVER;
FTH io = fth_io_nopen("localhost", 2002,
    AF_INET6, SOCK_STREAM, fam);

while (!fth_io_eof_p(io))
    fth_io_write(fth_io_stdout, fth_io_read(io));

fth_io_close(io);

/*
 * A client at port 2002 at another terminal (test_client):
 *
 * % ls -lAF | ./test_client ⇒ sends it to the server
 */
int fam = FICL_FAM_CLIENT;
FTH io = fth_io_nopen("localhost", 2002,
    AF_INET6, SOCK_STREAM, fam);

while (!fth_io_eof_p(fth_io_stdin))
    fth_io_write(io, fth_io_read(fth_io_stdin));

fth_io_close(io);
FTH (const char *name, int fam)
Opens file name with mode fam which can be FICL_FAM_READ, FICL_FAM_WRITE and FICL_FAM_READ | . 
FTH io = fth_io_open("foo", FICL_FAM_WRITE);
fth_io_write(io, "hello\n");
fth_io_write(io, "world\n");
fth_io_close(io);
FTH io = fth_io_open("foo", FICL_FAM_READ);
fth_printf("%s", fth_io_read(io); ⇒ "hello\n"
fth_printf("%s", fth_io_read(io); ⇒ "world\n"
fth_io_close(io);
/* or */
FTH io = fth_io_open("foo", FICL_FAM_READ | FICL_FAM_WRITE);
fth_io_write(io, "hello\n");
fth_io_write(io, "world\n");
fth_io_rewind(io);
fth_printf("%s", fth_io_read(io); ⇒ "hello\n"
fth_printf("%s", fth_io_read(io); ⇒ "world\n"
fth_io_close(io);
int fth_io_output_p(FTH obj)
 
FTH (FTH cmd, int fam)
cmd is a string or an array of strings, fam can be FICL_FAM_READ, FICL_FAM_WRITE and FICL_FAM_READ | which correspond to popen(3) open modes “r”, “w” and “r+”. 
/* read example (popen(3) mode == "r"): */
FTH fs = fth_make_string("ls");
FTH io = fth_io_popen(fs, FICL_FAM_READ);

while (!fth_io_eof_p(io))
    fth_printf("%s", fth_io_read(io));
fth_io_close(io);

/* write example (popen(3) mode == "w"): */
FTH fs = fth_make_string("cat");
FTH io = fth_io_popen(fs, FICL_FAM_WRITE);
fth_io_write(io, "hello\n");
fth_io_close(io);

/* read-write example (popen(3) mode == "r+"): */
FTH fs = fth_make_string("cat");
FTH io = fth_io_popen(fs, FICL_FAM_READ | FICL_FAM_APPEND);
fth_io_write(io, "hello\n");
fth_printf("%s", fth_io_read(io));
fth_io_close(io);
ficl2Integer (FTH io)
Returns current io object position.
void (FTH io, ficl2Integer pos)
Sets io object position to pos.
void* (FTH io)
Returns data pointer of io object. This is the FILE pointer for file, pipe, and socket objects and FTH string for String objects.
void (FTH io, int c)
Writes character c to io object.
char* (FTH io)
Returns next line from io object or NULL if EOF.
FTH (FTH io)
Returns next line as FTH string from io object or #f if EOF. Required for fth_object_apply.
FTH (FTH io)
Returns the entire io object contents as an array of strings, line by line.
void (FTH io)
Rewinds position to begin of io object.
FTH (FTH string, int fam)
string becomes the string IO object. fam can be FICL_FAM_READ, FICL_FAM_WRITE and FICL_FAM_READ | which correspond to open modes “r”, “w” and “r+”. 
/* read example (mode == "r"): */
FTH fs = fth_make_string("string\n");
FTH io = fth_io_sopen(fs, FICL_FAM_READ);

while (!fth_io_eof_p(io))
    fth_printf("%s", fth_io_read(io));
fth_io_close(io);

/* write example (mode == "w"): */
FTH fs = fth_make_empty_string();
FTH io = fth_io_sopen(fs, FICL_FAM_WRITE);
fth_io_write(io, "hello\n");
fth_io_close(io);

/* read-write example (mode == "r+"): */
FTH fs = fth_make_empty_string();
FTH io = fth_io_sopen(fs, FICL_FAM_READ | FICL_FAM_APPEND);
fth_io_write(io, "hello\n");
fth_io_rewind(io);
fth_printf("%s", fth_io_read(io));
fth_io_close(io);
FTH (FTH io)
Returns contents of io object as string if possible.
void (FTH io, const char *line)
Writes line to io object.
void (FTH io, const char *line)
Writes line to io object and flush the IO object.
void (FTH io, FTH fmt, FTH args)
Writes formatted string to io object.
void (FTH io, FTH array-of-lines)
Writes array-of-lines to io object.
FTH (const char *name)
Opens file name, reads its contents in an array, closes file and returns the array.
void (const char *name, FTH array-of-lines)
Opens file name, writes the contents of array-of-lines to it and closes file.
int (void)
Returns exit status of last extern process from fth_file_shell, fth_file_system, etc.
int (int status)
Sets global variable fth_exit_status.
FTH (FTH io)
 
FTH (FTH io)
 
FTH (FTH io)
They set io as the current input, output, and error IO object and return the old one.
FTH (FTH ip)
Returns a hash with slots 'name (string), 'aliases (array), and 'addr-list (array) filled with results from gethostbyaddr(3) looking for ip (a string).
FTH (FTH host)
Returns a hash with slots 'name (string), 'aliases (array), and 'addr-list (array) filled with results from gethostbyname2(3) looking for host (a string).
FTH (FTH serv)
Returns a hash with slots 'name (string), 'aliases (array), 'port (integer), and 'protocol (string) filled with results from getservbyname(3) looking for service serv (a string).
FTH (FTH port)
Returns a hash with slots 'name (string), 'aliases (array), 'port (integer), and 'protocol (string) filled with results from getservbyport(3) looking for port (a number).
FILE* (void)
 
FTH (void)
Creates a temporary file resp. file IO object that is automatically removed when it is closed or on program termination. See tmpfile(3) and mkstemp(3).

void (void)
This function must be called before any libfth.so action can take place.
void (int n)
Calls fth_exit_hook and exit(3) with return code n. exit(3) calls atexit(3) with the fth_at_exit_procs list.
void (void)
Resets Ficl System and Ficl Vm and restarts Fth.

int (const char *buffer)
 
int (ficlWord *word)
Execute C string buffer or ficlWord word and return status only as FTH_OKAY, FTH_BYE (exit), or FTH_ERROR.
FTH (const char *buffer)
Evaluates C string buffer. If buffer is NULL or evaluates to no value, returns undef, if buffer evaluates to FTH_BYE, exits program, if buffer evaluates to a single value, removes it from stack and returns it, if buffer evaluates to more than one values, removes them from stack and returns them as Array object.

void (const char *path)
 
void (const char *path)
Add path at the front or back of the global array variable *load-lib-path* if not already there.
void (const char *path)
 
void (const char *path)
Add path at the front or back of the global array variable *load-path* if not already there.
void (const char *file)
Pushs file at the end of the global array variable *loaded-files* if not already there.
char* (const char *path)
Returns the part of path after the last ‘/’.
FTH (FTH name)
Returns full path of name or #f.
void (FTH fname)
Installs fname in the first writable path found in *load-path* or *load-lib-path*. Warns if no writable path could be found.
FTH (const char *lib, const char *func)
 
FTH (const char *name)
 
FTH (const char *name)
They load C string name as Fth source or as dynamic library and add name to the global array *loaded-files*. Before loading, before-load-hook is called. If this hook returns #f, nothing is loaded and the return value is #f. If loading finishes successfully, the return value is #t, otherwise an exception is thrown. After loading, after-load-hook is called. If name has no file extension, FTH_FILE_EXTENSION ‘.fs’ or ‘.so’ will be added. If name or name plus extension doesn't exist, try all path names from either *load-path* or *load-lib-path* with name. If name begins with ‘~’, replace it with HOME. fth_load_file can load the same file more than once, while fth_require_file and fth_dl_load load files only once. fth_dl_load calls func to initializes the dynamic library.
FTH (const char *init_file)
 
FTH (void)
Load C string init_file or FTH_GLOBAL_INIT_FILE ${prefix}/etc/fthrc as Forth source file if it exists, otherwise do nothing. If init_file is NULL, try to load FTH_INIT_FILE, if FTH_INIT_FILE is not set, try to load HOME/.fthrc instead. before-load-hook and after-load-hook are called.

void (const char *name)
 
int (const char *name)
Pushs C string name to the *features* list and fth_provided_p tests if feature name exists in the list.
FTH (FTH regexp)
 
FTH (const char *name)
Return array with found words from the current word list matching regexp or name.
FTH (void)
 
int (FTH fs)
Get and set hostname, see gethostname(3) and sethostname(3).
FTH (void)
Returns an array of 16 elements with all slots of struct rusage. See getrusage(2) for more information.
char* (void)
The calling word is a parse word and receives its input from the next entry in the input stream. If the contents of vm->pad is a word, return word's name, otherwise return the string itself. 
FTH parse_test(void)
{
    return (fth_make_string(fth_parse_word()));
}

fth_make_proc_from_func("parse-test", parse_test, 0, 0, 0, 0);
fth_eval("parse-test make-array"); ⇒ "make-array"
FTH (void)
Returns Hash object with five slots containing entries from uname(3), which are:
'sysname
 
'nodename
 
'release
 
'version
 
'machine
 
char* (void)
 
char* (void)
Return short or long version strings.
FTH (int (*func)(ficlWord *word, FTH data), FTH data)
Loops through entire current word list and collects words in an array where func returns not 0.

int (obj)
 
int (obj)
Return 1 if obj is an exact number, otherwise 0.
int (obj)
 
int (obj)
Return 1 if obj is a fixnum, otherwise 0.
int (obj)
 
int (obj)
 
int (obj)
Return 1 if obj is any kind of a number, otherwise 0.
int (obj)
 
int (obj)
 
int (obj)
 
int (obj)
 
int (obj)
Return 1 if obj is integer, otherwise 0.
int (ficlFloat f)
 
int (ficlFloat f)
Return 1 if f is infinite or not-a-number, otherwise 0.
int (obj)
 
int (obj)
 
int (obj)
Return 1 if obj is a Llong object, otherwise 0.
FTH (ficlFloat f)
 
FTH (FTH x)
Return a Float object.
FTH (ficl2Integer d)
 
FTH (ficl2Unsigned ud)
 
FTH (FTH obj)
Return a Llong object.
FTH (ficlInteger n)
 
FTH (ficlUnsigned u)
 
FTH (ficl2Integer d)
 
FTH (ficl2Unsigned ud)
Return a Fixnum or a Llong object depending on input.
ficlFloat (FTH x)
 
ficlFloat (FTH x)
 
ficlInteger (FTH x)
 
ficlUnsigned (FTH x)
 
ficl2Integer (FTH x)
 
ficl2Unsigned (FTH x)
They convert any number x to the corresponding return type.
ficlFloat (FTH x, ficlFloat fallback)
 
ficlInteger (FTH x, ficlInteger fallback)
They convert any number x to the corresponding return type. If x doesn't fit in Fixnum or Number object, fallback will be returned.

int (obj)
Returns 1 if obj is a Complex object, otherwise 0.
FTH (ficlComplex z)
 
FTH (ficlFloat real, ficlFloat theta)
 
FTH (ficlFloat real, ficlFloat image)
Return a Complex object.
ficlComplex (FTH x)
They convert any number x to ficlComplex.
ficlComplex (ficlStack *stack)
 
void (ficlStack *stack, ficlComplex cp)
The Complex number stack functions to push to and pop from stack Complex objects.

int (obj)
Returns 1 if obj is a Bignum object, otherwise 0.
FTH (ficlBignum bn)
 
FTH (FTH m)
Return a Bignum object.
ficlBignum (FTH obj)
They convert any number x to ficlBignum.
ficlBignum (ficlStack *stack)
 
void (ficlStack *stack, ficlBignum bn)
The Bignum number stack functions to push to and pop from stack Bignum objects.

int (obj)
Returns 1 if obj is a Ratio object, otherwise 0.
FTH (FTH num, FTH den)
Returns a Ratio object from num and den.
FTH (ficlFloat f)
 
FTH (ficlInteger num, ficlInteger den)
 
FTH (ficlRatio r)
Return a Ratio object from the corresponding input.
ficlRatio (FTH obj)
They convert any number x to ficlRatio.
FTH (FTH x)
 
FTH (FTH x)
Return denominator or numerator of x.
FTH (FTH x)
Returns the floor of x.
FTH (FTH x, FTH err)
Returns inexact number within err of x.
ficlRatio (ficlStack *stack)
 
void (ficlStack *stack, ficlRatio r)
The Ratio number stack functions to push to and pop from stack Ratio objects.

ficlFloat (ficlFloat f)
Returns ficlFloats in the range of -f ... f.
ficlFloat (ficlFloat f)
Returns ficlFloats in the range of 0 ... f.
void (ficlInteger n)
Sets variable fth_rand_rnd to seed n.

FTH (FTH x)
 
FTH (FTH x)
Convert x from and to exact and inexact numbers.
int (FTH x, FTH y)
 
int (FTH x, FTH y)
Return 1 if x is equal (or less than) y, otherwise 0.
FTH (FTH x, FTH y)
 
FTH (FTH x, FTH y)
 
FTH (FTH x, FTH y)
 
FTH (FTH x, FTH y)
Return result of x add/div/mul/sub y.

int (FTH obj)
 
int (FTH obj)
 
int (FTH obj)
Return #t if obj is an instance and the mark/protected/permanent flag is set. New created objects have the mark flag set.
void (FTH obj)
 
void (FTH obj)
 
FTH (FTH obj)
 
FTH (FTH obj)
 
FTH (FTH obj)
They mark or unmark obj to protect or unprotect it from garbage collection.
FTH (void)
 
FTH (void)
 
void (void)
They turn garbage collection on or off and run garbage collection.

void* fth_instance_ref_gen(FTH obj)
 
FTH (FTH obj)
returns the GEN-struct of obj, fth_instance_ref_obj returns the OBJ-struct of obj for fth_make_object_type_from.
int (FTH obj)
 
int (FTH obj, FTH type)
Return #t if obj is an instance resp. an instance of type.
FTH (FTH obj, void *gen)
Returns new instance of object-type obj with gen struct wrapped in.
int (FTH obj, int flag)
 
int (FTH obj, fobj_t type)
Check if obj has flag set or is of type. Flags are used for exact, inexact and numbers in general and types for internal object-types like Array, Hash, etc.
FTH fth_make_object_type(const char *name)
 
int (FTH obj)
creates a new object-type name and adds name to the feature list, creates a constant fth-name of object-type and returns the new object-type name. The new created object-type can be used to bind words to it. fth_object_type_p checks if obj is an object-type.
FTH (const char *name, FTH base)
Creates a new object-type name derived from base and adds name to the feature list, creates a constant fth-name of object-type and returns the new object-type name. All object functions defined by base are available and probably only a few have to be changed or added.
char* (FTH obj)
Returns object-type name of obj as a string.

FTH (FTH obj, void *fnc, int req, int opt, int rest)
 
FTH (FTH obj, FTH (*fnc)(FTH obj))
 
FTH (FTH obj, FTH (*fnc)(FTH obj))
 
FTH (FTH obj, FTH (*fnc)(FTH obj1, FTH obj2))
 
FTH (FTH obj, void (*fnc)(FTH obj))
 
FTH (FTH obj, FTH (*fnc)(FTH obj))
 
FTH (FTH obj, FTH (*fnc)(FTH obj))
 
FTH (FTH obj, void (*fnc)(FTH obj))
 
FTH (FTH obj, FTH (*fnd)(FTH obj))
 
FTH (FTH obj, FTH (*fnc)(FTH obj))
 
FTH (FTH obj, FTH (*fnc)(FTH obj, FTH index))
 
FTH (FTH obj, FTH (*fnc)(FTH obj, FTH index, FTH value))
They set fnc as object-xxx function to object-type obj.

ficlInteger (FTH obj)
 
ficlInteger (FTH obj)
 
ficlInteger (FTH obj)
 
ficlInteger (FTH obj, ficlInteger index)
 
FTH (FTH obj)
 
FTH (FTH obj, FTH value)
Return or set values at current cycle-index, return or set cycle-index or set cycle-index to zero. Cycles through contents of obj from first to last entry and starts over at the beginning etc.
FTH (FTH obj)
Returns hash id computed from string representation of obj. Objects with the same contents have the same id.
FTH (FTH obj, FTH args)
Runs apply on obj with args as arguments. args can be an array of arguments or a single argument. The number of args must fit apply's definition. The next two examples require each 1 argument: 
fth_set_object_apply(vct_tag, vct_ref, 1, 0, 0); /* C */
<'> enved-ref fth-enved 1 set-object-apply \ Forth
FTH (FTH obj)
Returns copy of obj. Copies any element if obj is an instance.
FTH (FTH obj)
 
char* (FTH obj)
Return dump string of obj which may be evaled to reinstate the object from a file.
int (FTH obj)
Returns 1 if length of obj is zero, otherwise 0.
int (FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 have equal contents, otherwise 0.
FTH (FTH obj)
Returns object id of obj, a uniq number.
FTH (FTH obj, FTH key)
 
ficlInteger (FTH obj, FTH key)
 
int (FTH obj, FTH key)
Return the index, the element or 1 (member) if key is present in obj, otherwise -1 (index), #f (find) or 0 (member).
FTH (FTH obj)
 
char* (FTH obj)
Return inspect string of obj.
ficlInteger (FTH obj)
Returns length of obj.
int (FTH obj, ficlInteger index)
Returns 1 if index is in range of obj, otherwise 0.
FTH (FTH obj, FTH proc)
Converts obj to an array, sorts and returns it. proc compares two items A and B and should return a negative integer if A < B, 0 if A == B, and a positive integer if A > B.
FTH (FTH obj)
Returns obj as array.
FTH (FTH obj)
 
char* (FTH obj)
Return string representation of obj.
FTH (FTH obj, ficlInteger index)
 
FTH (FTH obj, ficlInteger index, FTH value)
Return or set value at index. If obj is of a type which can have multiple elements, an array for example, returns value at index. If obj is of a type which consists of only one element, a fixnum for example, ignores index and returns obj itself and set does nothing.

FTH (FTH obj)
 
FTH (FTH obj)
Convert ficlInteger to Fixnum or Fixnum to ficlInteger, the rest stays.
FTH (ficlVm *vm)
 
void (ficlVm *vm, FTH obj)
Pop from or push to Top Of Stack TOS with ficlInteger converted to Fixnum (pop) or Fixnum converted to ficlInteger (push), the rest stays.

void (FTH port)
 
void (FTH port)
Flush or close port. If port is #f, do nothing.
void (FTH port, FTH obj)
Writes string representation of obj to port. If port is #f, prints to Ficl output.
int (FTH port)
 
char* (FTH port)
Return next character or next line from port IO object. If port is #f, read from Ficl input.
void (FTH port, int c)
 
void (FTH port, const char *str)
Write character or string to port. If port is #f, write to Ficl output.
in_cb (in_cb cb)
 
out_cb (out_cb cb)
 
out_cb (out_cb cb)
 
out_cb (out_cb cb)
Set the read, print, and error callback functions. If cb is NULL, use default_read_cb, default_print_cb, and default_error_cb.
FTH (FTH port)
Returns entire contents of port IO object as String object if available. If port is #f, returns #f.

The format string for the following functions can have zero or more of the following flags:

‘#’
The value will be converted to an alternate form. For b, B, o and O conversion prepend a zero before output, for x and X conversion prepend a ‘0x’ respective ‘0X’ before output. For a, A, e, E, f, F, g and G conversion the result will always have a decimal point.
‘-’
Flushes output left.
‘0’ (zero)
Padding with ‘0’ (zero) rather than blank.
‘l’
Modifier for long, unsigned long and long *.
‘ll’
Modifier for long long, unsigned long long and long long *.
‘z’
Modifier for size_t.
The following conversion specifiers are known:
A ‘%’ is written.
Floating point output like printf(3).
Integer output in binary, decimal, octal, void pointer, unsigned and hexadecimal form.
Single character output.
Dump string output of any Forth object with object-dump.
Inspect string output of any Forth object with object-inspect.
String representation of any Forth object with object->string, in addition, strings will be enclosed in double quotations ("string").
C string char * output.
String representation of any Forth object with object->string.
int (const char *fmt, ...)
Writes the formatted string to FILE *stderr wrapped in #<DEBUG(C): ...> and returns the written bytes.
void (const char *fmt, ...)
 
int (const char *fmt, ...)
Print formatted string to Ficl error output wrapped either in #<warning: ...> continuing execution, or in #<die: ...> and exit the interpreter with return code 1 (EXIT_FAILURE). fth_warning returns the written bytes.
int (const char *str)
 
int (const char *fmt, ...)
 
int (const char *fmt, va_list ap)
Write formatted string to Ficl error output. They return the written bytes.
char* (const char *fmt, ...)
 
char* (const char *fmt, va_list ap)
Return new allocated buffer containing the formatted string. If the string is no longer needed, it should be freed.
int (FILE *fp, const char *fmt, ...)
 
int (FTH io, const char *fmt, ...)
 
int (FTH port, const char *fmt, ...)
 
int (FILE *fp, const char *fmt, va_list ap)
 
int (FTH io, const char *fmt, va_list ap)
 
int (FTH port, const char *fmt, va_list ap)
Write formatted string to the FILE pointer fp, the IO object io, or the Port object port. If port is #f, write to Ficl output. They return the written bytes.
char* (void)
 
int (const char *str)
 
int (const char *fmt, ...)
 
int (const char *fmt, va_list ap)
Read from Ficl input or write to Ficl output. The write-functions return the written bytes.
int (char **result, const char *fmt, ...)
 
int (char **result, const char *fmt, va_list ap)
The result points to a newly allocated buffer containing the formatted string. Return the length of the allocated string. If the string is no longer needed, it should be freed.
int (char *buffer, size_t size, const char *fmt, ...)
 
int (char *buffer, size_t size, const char *fmt, va_list ap)
Create formatted string and write at most size - 1 character to buffer.

int (FTH obj)
Test if obj is an already defined word, a variable or constant or any other object in the dictionary. 
FTH x = (FTH)FICL_WORD_NAME_REF("bye");
fth_word_defined_p(x); ⇒ 1
fth_variable_set("hello", FTH_FALSE);
FTH x = (FTH)FICL_WORD_NAME_REF("hello");
fth_word_defined_p(x); ⇒ 1
fth_word_defined_p(FTH_FALSE); ⇒ 0
int (FTH obj, int type)
Test if obj is of type where type can be one of the following:
FW_WORD
FW_PROC
FW_SYMBOL
FW_KEYWORD
FW_EXCEPTION
FW_VARIABLE
FW_TRACE_VAR

FTH x = (FTH)FICL_WORD_NAME_REF("bye");
fth_word_type_p(x, FW_WORD); ⇒ 1
fth_word_type_p(x, FW_KEYWORD); ⇒ 0
int (obj)
Returns 1 if obj is a Proc object, otherwise 0.
int (obj)
Returns 1 if obj is a ficlWord, otherwise 0.
ficlWord* (const char *name, void *func, int req, int opt, int rest, const char *doc)
Returns new ficlWord name tied to C function func with req required arguments, opt optional arguments and rest (1) or no rest (0) arguments with optional documentation string doc. func takes zero or more FTH objects and returns a FTH object.
ficlWord* (const char *name, void *func, int req, int opt, int rest, const char *doc)
Returns new ficlWord name tied to C function func with req required arguments, opt optional arguments and rest (1) or no rest (0) arguments with optional documentation string doc. func takes zero or more FTH objects and doesn't return any (void).
FTH (FTH obj)
Returns documentation property string of obj or #f.
void (FTH obj, FTH doc)
Sets documentation property string of any obj to doc.
FTH (ficlInteger req, FTH def)
Returns either default value def or a value found on top of stack. req is the sum of required and following optional arguments.
FTH (FTH key, FTH def)
 
int (FTH key, int def)
 
ficlInteger (FTH key, ficlInteger def)
 
ficl2Integer (FTH key, ficl2Integer def)
 
char* (FTH key, char *def)
Return either default value def or a value found on stack specified by keyword key.
FTH (ficlWord *word, int req, int opt, int rest)
If word is an existing ficlWord, returns a corresponding Proc object with req reqired, opt optional and rest function arguments. If word is not an existing word, returns #f. 
ficlWord *xt = FICL_WORD_NAME_REF("+");
FTH prc = fth_make_proc(xt, 2, 0, 0);
fth_proc_call(prc, __func__, 2, FTH_ONE, FTH_TWO); ⇒ 3
FTH (const char *name, void *func, int void_p, int req, int opt, int rest)
Returns a Proc object from C-function func where name is the name on the Forth interpreter side, void_p if func is a void function, req required, opt optional and rest function arguments.
FTH (FTH proc, FTH args, const char *caller)
If proc is a Proc object, executes its ficlWord with Array object args as arguments on stack. caller can be any C string used for error message. Raises bad-arity exception if proc has more required arguments than len. Raises eval-error exception if an error occurred during evaluation.

If proc is not a Proc object, returns #f, If proc doesn't leave a return value on stack, returns #f, if proc leaves a single value on stack, returns it, if proc leaves more than one values on stack, returns them as Array object.

int (FTH proc)
If proc is a Proc object, returns required arguments as C int, otherwise returns 0.
FTH (FTH proc, const char *caller, int len, ...)
If proc is a Proc object, executes its ficlWord with len arguments on stack. caller can be any C string used for error message. Raises bad-arity exception if proc has more required arguments than len. Raises eval-error exception if an error occurred during evaluation.

If proc is not a Proc object, returns #f, If proc doesn't leave a return value on stack, returns #f, if proc leaves a single value on stack, returns it, if proc leaves more than one values on stack, returns them as Array object.

char* (FTH obj)
If obj is a ficlWord, returns name as C string, otherwise returns "not-a-proc".
FTH (FTH proc)
Returns source string property of proc, or #f if not available.
void (FTH proc, FTH source)
Sets source string property of proc to source.
ficlWord* (FTH proc)
Returns the actual word (the execution token xt) of proc.
FTH (FTH obj)
Returns source file where obj was created, or #f if a C-primitive or not defined.
FTH (FTH obj)
Returns source line number where obj was created or #f if a C-primitive or not defined.
FTH (FTH obj)
Returns source string of obj, a proc or xt, or #f if not found.
void (FTH obj, FTH source)
Sets source string of obj, a proc or xt, to source.
ficlWord* (ficlWord *word, const char *str)
Sets word's documentation property to str.
FTH (const char *name, FTH args, const char *caller)
Executes name, a C string, with array length arguments of type FTH. caller can be any C string used for error message. Raises eval-error exception if an error occurred during evaluation.

If the xt with name doesn't leave a return value on stack, returns #f, if a single value remains on stack, returns it, if more than one values remain on stack, returns them as Array object.

FTH fs = fth_make_string("hello, world!");
FTH re = fth_make_regexp(", (.*)!");
FTH ary = fth_make_array_var(2, re, fs);
fth_xt_apply("regexp-match", ary, __func__); ⇒ 8
fth_xt_apply("*re1*", FTH_FALSE, __func__) ⇒ "world"
FTH (const char *name, FTH args, const char *caller)
Executes name, a C string, with len arguments of type FTH. caller can be any C string used for error message. Raises eval-error exception if an error occurred during evaluation.

If the xt with name doesn't leave a return value on stack, returns #f, if a single value remains on stack, returns it, if more than one values remain on stack, returns them as Array object.

FTH fs = fth_make_string("hello, world!");
FTH re = fth_make_regexp(", (.*)!");
fth_xt_call("regexp-match", __func__, 2, re, fs); ⇒ 8
fth_xt_call("*re1*", __func__, 0); ⇒ "world"
ficlWord* (const char *name)
Finds name in Forth dictionary and returns ficlWord.
FTH (const char *name)
Finds name in Forth dictionary and returns ficlWord casted to FTH.
ficlWord* (const char *name)
Finds name in Forth dictionary and returns ficlWord casted to FTH if it's a variable, otherwise #f.

FTH (const char *name, FTH value)
Defines constant name to value which can be a FTH Fixnum (in contrast to fth_define_constant below) or any other FTH object. Returns value.
FTH (const char *name, FTH value, const char *doc)
Defines constant name to value which can be a C integer (in contrast to fth_define above) or any other FTH object. doc can be NULL or a description of the constant for the help word. Returns value where C integers are converted to FTH Fixnums, any other objects remain untouched.
FTH (const char *name, FTH value, const char *doc)
Defines global variable name to value which can be a FTH Fixnum or any other FTH object, see the similar function fth_define() for constants above. Returns value.
int (const char *name)
Returns 1 if name is defined in the dictionary, otherwise 0.
void (FTH obj, FTH proc_or_xt)
Installs a hook on the specified global variable obj and adds proc-or-xt with stack effect ( val -- res ). The hook will be executed after every variable set via to. 
FTH test_var;

FTH
trace_cb(FTH val)
{
    test_var = fth_number_mul(val, FTH_TWO);
    return (val);
}

fth_variable_set("trace-foo", FTH_ONE);
FTH prc = fth_make_proc_from_func("trace-cb",
    trace_cb, 0, 1, 0, 0);
FTH obj = (FTH)FICL_WORD_NAME_REF("trace-foo");
fth_trace_var(obj, prc);
fth_string_eval(fth_make_string("2 to trace-foo"));
⇒ test_var == 4
fth_untrace_var(obj);
void (FTH obj)
Removes previously installed hook from obj.
FTH (FTH obj)
If obj is a global variable, return value, otherwise #f.
FTH (FTH obj, FTH value)
If obj is a global variable, set value and protect it from GC. Returns value.
FTH (const char *name)
Return FTH value from global variable or constant name.
FTH (const char *name, FTH value)
Set or create global variable name to value. Returns value.

General help for regexp can be found in regex(3) and re_format(7). For all matching functions below, matched results or #f are stored in the Regexp object FTH regexp. The last match results are also stored in the read-only variable FTH regexp_results and can be retrieved with ().

int (obj)
Returns 1 if obj is a Regexp object, otherwise 0.
FTH (const char *reg)
Returns a new Regexp object from reg which may contain regular expressions. 
FTH re = fth_make_regexp("bar");
FTH fs = fth_make_string("foobar");
fth_regexp_search(re, fs, 0, -1); ⇒ 3

FTH re = fth_make_regexp("(B|b)+");
FTH fs = fth_make_string("foobar");
fth_regexp_search(re, fs, 0, -1); ⇒ 3
int (const char *reg, const char *str)
Searches reg in str and returns first match's position or -1 if no match was found.
int (const char *reg, const char *str, int cflags)
Similar to fth_regexp_find() but with the extra option cflags, which can be set to an ored value from the following constants:
 
 
 
 
 
 
 
ficlInteger (FTH regexp, FTH string)
Searches regexp in string and returns first match's length or -1 if no match was found. 
FTH re = fth_make_regexp("foo");
FTH fs = fth_make_string("foobar");
fth_regexp_match(re, fs); ⇒ 3

FTH re = fth_make_regexp("(bar)");
FTH fs = fth_make_string("foobar");
fth_regexp_match(re, fs); ⇒ 3

FTH re = fth_make_regexp(".*(bar)");
FTH fs = fth_make_string("foobar");
fth_regexp_match(re, fs); ⇒ 6
fth_object_value_ref(re, 0); ⇒ "foobar"
fth_object_value_ref(re, 1); ⇒ "bar"
fth_object_value_ref(re, 2); ⇒ #f
FTH (FTH regexp, FTH string, FTH replace)
Replaces first occurrence of regexp in string with replace if found. References \1 to \9 in replace will be replaced by corresponding subexpressions. If there are no corresponding subexpressions, raises regexp-error exception. 
FTH re = fth_make_regexp("(bar)");
FTH fs = fth_make_string("foobar");
FTH rp = fth_make_string("BAR");
fth_regexp_replace(re, fs, rp); ⇒ "fooBAR"

FTH re = fth_make_regexp("(foo)");
FTH fs = fth_make_string("foo-bar");
FTH rp = fth_make_string("***\\1***");
fth_regexp_replace(re, fs, rp); ⇒ "***foo***-bar"
Searches regexp in string from start for range characters and returns first match's position or -1 if no match was found. If range is -1, the entire string will be searched. 
FTH re = fth_make_regexp("foo");
FTH fs = fth_make_string("foobar");
fth_regexp_search(re, fs, 0, 2); ⇒ 0 (means #t)

FTH re = fth_make_regexp("(bar)");
FTH fs = fth_make_string("foobar");
fth_regexp_search(re, fs, 0, 2); ⇒ -1 (means #f)
fth_regexp_search(re, fs, 3, 2); ⇒ 3
fth_object_value_ref(re, 0); ⇒ "bar"
fth_object_value_ref(re, 1); ⇒ "bar"
fth_object_value_ref(re, 2); ⇒ #f
FTH fth_regexp_var_ref(ficlInteger index)
Returns the element at index from the FTH regexp_results array. If index is -1, the entire array, if index is bigger than the array length, #f is returned.

int (obj)
Returns 1 if obj is a String object, otherwise 0. 
FTH fs = fth_make_string("hello");
FTH_STRING_P(fs); ⇒ 1
FTH fs = FTH_NIL;
FTH_STRING_P(fs); ⇒ 0
int (obj)
 
int (obj)
Return 1 if obj is a character, otherwise 0. 
FTH ch = CHAR_TO_FTH('A');
FTH_CHAR_P(ch); ⇒ 1
FTH ch = INT_TO_FIX(65);
FTH_CHAR_P(ch); ⇒ 1
FTH ch = INT_TO_FIX(10);
FTH_CHAR_P(ch); ⇒ 0
FTH (void)
Returns an empty String object. 
FTH fs = fth_make_empty_string(); ⇒ ""
fth_string_length(fs); ⇒ 0
FTH (const char *str)
Returns a new String object from C str. If C string is "" or NULL, returns String object "" in contrast to fth_make_string_or_false(). 
FTH fs = fth_make_string("hello"); ⇒ "hello"
fth_string_length(fs); ⇒ 5
FTH fs = fth_make_string(""); ⇒ ""
fth_string_length(fs); ⇒ 0
FTH (const char *fmt, ...)
Returns a String object according to the extended printf(3) fmt args. The extensions are:
fth_to_c_inspect
prints inspect string of any Fth object.
fth_to_c_string
prints string representation of any Fth object.
fth_to_c_string_2
as fth_to_c_string but encloses strings in double quotes.
fth_to_c_dump
prints dump string of any Fth object.
FTH arg = fth_make_array_var(1, fth_make_string("foo"));
FTH fs = fth_make_string_format("%I", arg);
    ⇒ '#<array[1]:  #<string[3]: "foo">>'
FTH fs = fth_make_string_format("%S", arg);
    ⇒ '#( "foo" )'
FTH fs = fth_make_string_format("%M", arg);
    ⇒ '#( "foo" )'
FTH fs = fth_make_string_format("%D", arg);
    ⇒ '#( "foo" )'
FTH (const char *str, ficlInteger len)
Returns a new String object constructed from C string str with at most len characters. If the C string str is shorter than len, returns a String object of str length only. 
FTH fs = fth_make_string_len("     ", 0); ⇒ ""
FTH fs = fth_make_string_len("     ", 3); ⇒ "   "
FTH fs = fth_make_string_len("xxxxx", 3); ⇒ "xxx"
FTH fs = fth_make_string_len("xxx", 5); ⇒ "xxx"
FTH (const char *str)
If C string is "", returns #f, otherwise like fth_make_string. 
FTH fs = fth_make_string_or_false("hello"); ⇒ "hello"
fth_string_length(fs); ⇒ 5
FTH fs = fth_make_string_or_false(""); ⇒ #f
fth_string_length(fs); ⇒ -1 (means #f)
FTH (FTH string1, FTH string2)
Returns new string from string1 + string2. 
FTH s1 = fth_make_string("foo");
FTH s2 = fth_make_string("bar");
fth_string_append(s1, s2); ⇒ "foobar"
FTH (FTH string)
Returns the string, not a copy, with first character capitalized and remaining characters changed to lowercase. 
FTH fs = fth_make_string("foO");
fth_string_capitalize(fs); ⇒ "Foo"
fth_printf("%S", fs); ⇒ "Foo"
char (FTH string, ficlInteger index)
Returns character as C char at position index; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("foo");
char c = fth_string_c_char_ref(fs, 1); ⇒ 111
char (FTH string, ficlInteger index, char c)
Stores C char character c at position index; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("foo");
char c = fth_string_c_char_set(fs, 1, 'e'); ⇒ 101
fth_printf("%S", fs); ⇒ "feo"
FTH (FTH string, ficlInteger index)
Returns character as FTH object at position index; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("foo");
FTH ch = fth_string_char_ref(fs, 1); ⇒ 111
FTH (FTH string, ficlInteger index, FTH ch)
Stores character ch at position index; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("foo");
FTH ch = fth_string_char_set(fs, 1, CHAR_TO_FTH('e')); ⇒ 101
fth_printf("%S", fs); ⇒ "feo"
FTH (FTH string)
Returns the string, not a copy, with possible trailing ‘\n’ removed. 
FTH fs = fth_make_string("foo\n");
fth_string_chomp(fs); ⇒ "foo"
FTH fs = fth_make_string("bar");
fth_string_chomp(fs); ⇒ "bar"
FTH (FTH string)
Returns a copy of String object string. 
FTH s1 = fth_make_string("foo");
FTH s2 = fth_string_copy(s1);
s1 == s2 ⇒ 0
fth_string_equal_p(s1, s2); ⇒ 1
FTH (FTH string, ficlInteger index)
Deletes and returns character at position index from string; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("foo");
fth_string_delete(fs, 1); ⇒ 111 ('o')
fth_printf("%S", fs); ⇒ "fo"
FTH (FTH string)
Returns the string, not a copy, all characters changed to downcase. 
FTH fs = fth_make_string("Foo");
fth_string_downcase(fs); ⇒ "foo"
fth_printf("%S", fs); ⇒ "foo"
int (FTH obj1, FTH obj2)
Compares two strings with strcmp(3) and returns 1 for equal and 0 for not equal (not -1 0 1 like strcmp). 
FTH s1 = fth_make_string("foo");
FTH s2 = fth_make_string("bar");
FTH s3 = fth_make_string("foo");
fth_string_equal_p(s1, s2); ⇒ 0
fth_string_equal_p(s1, s3); ⇒ 1
fth_string_equal_p(s3, s3); ⇒ 1
int (FTH string)
Evaluate string; values already on stack can be accessed, resulting values remain on stack. 
ficlVm *vm = FTH_FICL_VM();
FTH fs = fth_make_string("3 4 +");
fth_string_eval(fs); ⇒ puts 7 on stack
ficlStackPopInteger(vm->dataStack); ⇒ 7

ficlStackPushInteger(vm->dataStack, 7); ⇒ puts 7 on stack
FTH fs = fth_make_string("3 4 + +");
fth_string_eval(fs); ⇒ puts 14 on stack
ficlStackPopInteger(vm->dataStack); ⇒ 14

ficlStackPushInteger(vm->dataStack, 7); ⇒ puts 7 on stack
FTH fs = fth_make_string("3 4 + + . cr");
fth_string_eval(fs); ⇒ prints 14
FTH (FTH string, FTH char)
Fills string with char and returns changed String object. 
FTH fs = fth_make_string("foo");
fth_string_fill(fs, CHAR_TO_FTH('a')); ⇒ "aaa"
fth_printf("%S", fs); ⇒ "aaa"
FTH (FTH string, FTH key)
Returns from match on if string or regexp key exists in string, otherwise #f. 
FTH fs = fth_make_string("hello world");
FTH rs fth_make_string("l");
fth_string_find(fs, rs); ⇒ "llo world"
FTH rs = fth_make_string("ell");
fth_string_find(fs, rs); ⇒ "ello world"
FTH rs = fth_make_regexp("ell");
fth_string_find(fs, rs); ⇒ "ello world"
FTH rs = fth_make_regexp("k");
fth_string_find(fs, rs); ⇒ #f
FTH (FTH string, FTH args)
fmt is a printf(3) format string and args, which may be an array, a single argument or #f, the required arguments. See fth_make_string_format for extra format signs. 
FTH fmt = fth_make_string("%04d %8.2f %b %X %o");
FTH args = fth_make_array_var(5,
    INT_TO_FIX(128),
    fth_make_float(M_PI),
    INT_TO_FIX(255),
    INT_TO_FIX(255),
    INT_TO_FIX(255));
fth_string_format(fmt, args);
    ⇒ "0128     3.14 11111111 FF 377"

FTH fmt = fth_make_string("we print %S");
FTH arg = INT_TO_FIX(10);
fth_string_format(fmt, arg); ⇒ "we print 10"

FTH fs = fth_make_string("simple string");
fth_string_format(fs, FTH_FALSE); ⇒ "simple string"
fth_string_format(fs, FTH_NIL); ⇒ "simple string"

FTH fs = fth_make_empty_string();
fth_string_format(fs, args); ⇒ ""
int (FTH obj1, FTH obj2)
Compares two strings with strcmp(3) and returns 1 for greater than and 0 for less than. 
FTH s1 = fth_make_string("foo");
FTH s2 = fth_make_string("bar");
FTH s3 = fth_make_string("foo");
fth_string_greater_p(s1, s2); ⇒ 0
fth_string_greater_p(s1, s3); ⇒ 0
fth_string_greater_p(s3, s3); ⇒ 0
FTH (FTH string, FTH key)
Returns index of string key in string or -1 if not found. 
FTH fs = fth_make_string("hello world");
FTH rs fth_make_string("l");
fth_string_index(fs, rs); ⇒ 2
FTH rs = fth_make_string("orl");
fth_string_index(fs, rs); ⇒ 7
FTH rs = fth_make_string("k");
fth_string_index(fs, rs); ⇒ -1 (means #f)
FTH (FTH string, ficlInteger index, FTH value)
Inserts string representation of value to string at position index; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("foo");
fth_string_insert(fs, 1, INT_TO_FIX(10)); ⇒ "f10oo"
ficlInteger (FTH string)
If string is a String object, returns its length, otherwise -1. 
FTH fs = fth_make_string("hello");
fth_string_length(fs); ⇒ 5
fth_string_length((FTH)5); ⇒ -1 (means #f)
int (FTH obj1, FTH obj2)
Compares two strings with strcmp(3) and returns 1 for less than and 0 for greater than. 
FTH s1 = fth_make_string("foo");
FTH s2 = fth_make_string("bar");
FTH s3 = fth_make_string("foo");
fth_string_less_p(s1, s2); ⇒ 0
fth_string_less_p(s1, s3); ⇒ 0
fth_string_less_p(s3, s3); ⇒ 0
int (FTH string, FTH key)
Returns 1 if string or regexp key exists in string, otherwise 0. 
FTH fs = fth_make_string("hello world");
FTH rs fth_make_string("l");
fth_string_member_p(fs, rs); ⇒ 1
FTH rs = fth_make_string("ell");
fth_string_member_p(fs, rs); ⇒ 1
FTH rs = fth_make_string("k");
fth_string_member_p(fs, rs); ⇒ 0
FTH rs = fth_make_regexp("ell");
fth_string_member_p(fs, rs); ⇒ 1
int (FTH obj1, FTH obj2)
Compares two strings with strcmp(3) and returns 1 for not equal and 0 for not equal (not -1 0 1 like strcmp). 
FTH s1 = fth_make_string("foo");
FTH s2 = fth_make_string("bar");
FTH s3 = fth_make_string("foo");
fth_string_not_equal_p(s1, s2); ⇒ 1
fth_string_not_equal_p(s1, s3); ⇒ 0
fth_string_not_equal_p(s3, s3); ⇒ 0
FTH (FTH string)
Removes and returns last character of string. If string is empty, returns #f. 
FTH fs = fth_make_string("foo");
fth_string_pop(fs); ⇒ 111 ('o')
fth_string_pop(fs); ⇒ 111 ('o')
fth_string_pop(fs); ⇒ 102 ('f')
fth_string_pop(fs); ⇒ #f
FTH (FTH string, FTH value)
Appends string representation of value to string and returns changed String object. 
FTH fs = fth_make_string("foo");
fth_string_push(fs, fth_make_string(" ")); ⇒ "foo "
fth_string_push(fs, INT_TO_FIX(10)); ⇒ "foo 10"
char* (FTH string)
Returns C string from Fth string or NULL if not a String object. 
FTH fs = fth_make_string("hello");
fth_string_ref(fs); ⇒ "hello"
FTH fs = fth_make_empty_string();
fth_string_ref(fs); ⇒ ""
FTH fs = FTH_FALSE;
fth_string_ref(fs); ⇒ NULL
FTH (FTH string, FTH from, FTH to)
Returns the string, not a copy, with string from replaced by string to. If to is the empty string, deletes the from part from string. 
FTH fs = fth_make_string("foo");
FTH from = fth_make_string("o");
FTH to = fth_make_string("a");
fth_string_replace(fs, from, to); ⇒ "faa"
fth_printf("%S", fs); ⇒ "faa"

FTH fs = fth_make_string("foo");
FTH from = fth_make_string("oo");
FTH to = fth_make_string("a");
fth_string_replace(fs, from, to); ⇒ "fa"
fth_printf("%S", fs); ⇒ "fa"

FTH fs = fth_make_string("foo");
FTH from = fth_make_string("o");
FTH to = fth_make_string("");
fth_string_replace(fs, from, to); ⇒ "f"
fth_printf("%S", fs); ⇒ "f"
FTH (FTH string)
Returns the same String object string reversed. 
FTH fs = fth_make_string("foo");
fth_string_reverse(fs); ⇒ "oof"
FTH (FTH string, const char *str)
Add C string str to an already existing String object string. 
FTH fs = fth_make_empty_string(); ⇒ ""
fth_string_scat(fs, "hello"); ⇒ "hello"
FTH (FTH string, const char *fmt, ...)
Add extended printf(3) fmt args to an already existing String object. See fth_make_string_format. 
FTH fs = fth_make_string("we want to ");
fth_string_sformat(fs, "print %d times %f\n", 10, 3.14);
  ⇒ "we want to print 10 times 3.140000\n"
FTH (FTH string)
Removes and returns first character of string. If string is empty, returns #f. 
FTH fs = fth_make_string("foo");
fth_string_shift(fs); ⇒ 102 ('f')
fth_string_shift(fs); ⇒ 111 ('o')
fth_string_shift(fs); ⇒ 111 ('o')
fth_string_shift(fs); ⇒ #f
FTH (FTH string, const char *str, ficlInteger len)
Add C string str of length len to an already existing String object string. 
FTH fs = fth_make_empty_string(); ⇒ ""
fth_string_sncat(fs, ",  ", 2); ⇒ "hello, "
FTH (FTH string, FTH sep)
Splits string using sep as delimiter and returns result as array of strings. If sep is not a string or regexp, delimiter is " \t" (space and tab). 
FTH fs = fth_make_string("foo:bar:baz:");
FTH sp = fth_make_string(":");
fth_string_split(fs, sp); ⇒ #( "foo" "bar" "baz")
FTH sp = fth_make_regexp(":");
fth_string_split(fs, sp); ⇒ #( "foo" "bar" "baz")
FTH fs = fth_make_string("foo bar baz");
fth_string_split(fs, FTH_NIL); ⇒ #( "foo" "bar" "baz")
FTH (FTH string, ficlInteger start, ficlInteger end)
Returns new string from position start to, but excluding, position end; negative index counts from backward. Raises out-of-range exception if index is not in range of string. 
FTH fs = fth_make_string("hello world");
fth_string_substring(fs, 2, 4); ⇒ "ll"
fth_string_substring(fs, 0, -1); ⇒ "hello world"
fth_string_substring(fs, -4, -2); ⇒ "orl"
fth_string_substring(fs, -4, fth_string_length(fs)); ⇒ "orld"
FTH (FTH string)
Converts string to an array of characters. 
FTH fs = fth_make_string("foo");
fth_string_to_array(fs); ⇒ #( 102 111 111 )
FTH (FTH string, FTH value)
Adds string representation of value in front of string and returns changed String object. 
FTH fs = fth_make_string("foo");
fth_string_unshift(fs, fth_make_string(" ")); ⇒ " foo"
fth_string_unshift(fs, INT_TO_FIX(10)); ⇒ "10 foo"
FTH (FTH string)
Returns the string, not a copy, all characters changed to uppercase. 
FTH fs = fth_make_string("Foo");
fth_string_upcase(fs); ⇒ "FOO"
fth_printf("%S", fs); ⇒ "FOO"
FTH (const char *fmt, FTH args)
Returns formatted String object corresponding to C string fmt and Fth array args containing as much arguments as fmt requires. 
FTH args = fth_make_array_var(2,
    INT_TO_FIX(10),
    fth_make_float(3.14));
fth_string_vformat("print %d times %f", args);
    ⇒ "print 10 times 3.140000"
FTH (FTH string, const char *fmt, va_list ap)
The same as fth_string_sformat except for a va_list ap.

int (obj)
Returns 1 if obj is a symbol, otherwise 0.
int (FTH obj)
Returns 1 if obj is a String object or a symbol, otherwise 0.
char* (FTH obj)
Returns C string name of obj or NULL.
FTH (const char *name)
Returns value, the word address, of symbol name; if symbol doesn't exist, creates it.
int (FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are symbols with identical names, otherwise 0.
int (const char *name)
Returns 1 if name is a symbol, otherwise 0.
char* (FTH obj)
Returns C string name of symbol obj without first sign (') or NULL.

int (obj)
Returns 1 if obj is a keyword, otherwise 0.
FTH (const char *name)
Returns value, the word address, of keyword name; if keyword doesn't exist, creates it.
int (FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are keywords with identical names, otherwise 0.
int (const char *name)
Returns 1 if name is a keyword, otherwise 0.
char* (FTH obj)
Returns C string name of keyword obj without first sign (:) or NULL.

int (obj)
Returns 1 if obj is an exception, otherwise 0.
FTH (const char *name)
Returns a new exception name.
int (FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are exceptions with identical names, otherwise 0.
FTH (FTH exc)
Returns last message of exception exc. The last message was set after an exception was thrown with for example fth_throw.
void (FTH exc, FTH msg)
Sets message msg, a string or #f, as the last message of exception ex. This will be set automatically after an exception was thrown with for example fth_throw.
FTH (FTH exc)
Returns the message of exception exc.
void (FTH exc, FTH msg)
Sets message msg, a string or #f, to exception exc.
char* (FTH obj)
Returns C string name of exception obj without first sign (') or NULL.
FTH (const char *name, const char *message)
Creates and returns the new exception named name with message; message may be NULL.
int (FTH obj)
Returns 1 if obj is a symbol or an exception, otherwise 0.
FTH (FTH obj)
If obj is a symbol, converts it to an exception and returns it, if obj is an existing exception, returns it, otherwise #f.
FTH (FTH obj)
Returns symbol obj as exception.

This section mentions some utility functions for memory allocation, string handling, evaluating, etc.

The allocation functions always return a valid pointer. If memory is exhausted, abort the program.

void* (size_t size, size_t eltsize)
Allocates space for size objects, each eltsize bytes in length, and initializes the memory to zero, see calloc(3).
void* (size_t size)
Allocates size bytes of uninitialized memory, see malloc(3).
void* (void *p, size_t size)
Changes the size of the previously allocated memory referenced by p to size, see realloc(3).
void (void *p)
Causes the allocated memory referenced by p to be made available for future allocations. If p is NULL, no action occurs, see free(3).
char* (const char *s)
Allocates sufficient memory for a copy of the string s, does the copy, and returns a pointer to it, see strdup(3).
char* (const char *s, size_t size)
Copies at most size characters from the string s always NUL terminating the copied string, see strndup(3).

The string functions return always NUL terminated strings.

char* (char *d, size_t size, const char *s)
Appends s to d but not more than size - 1 chars; appends terminating ‘\0’.
char* (char *d, size_t size, const char *s, size_t count)
Appends count chars from s to d but not more than size - 1; appends terminating ‘\0’.
char* (char *d, size_t size, const char *s)
Copies s to d but not more than size - 1 chars; appends terminating ‘\0’.
char* (char *d, size_t size, const char *s, size_t count)
Copies count chars from s to d but not more than size - 1; appends terminating ‘\0’.
size_t (const char *s)
Computes the length of the string s. If s is NULL, returns 0, see strlen(3).
size_t (const char *s, size_t maxsize)
Attempts to compute the length of the string s, but never scans beyond the first maxsize bytes of s. If s is NULL, returns 0, see strnlen(3).

int (ficlVm *vm, const char *buffer)
Evaluates buffer as Forth input string. Returns the evaluation status, uses values on stack and leave evaluation results on stack, if any.
int (ficlVm *vm, ficlWord *word)
Executes ficlWord word. Returns the evaluation status, uses values on stack and leave execution results on stack, if any.
void (int argc, char **argv)
Starts the Read-Eval-Print-Loop. argc and argv are not used. Initializes the tecla(7) library, reads the history file, evaluates the input strings in a loop, and at the end writes the history file back. Calls before-repl-hook, before-prompt-hook, and after-repl-hook.
void (FTH exc, const char *fmt, ...)
Throws exception exc with text constructed from fmt and optional arguments. exc can be an exception, a symbol, or #f. fmt can be NULL or a printf-like format string with corresponding arguments.
void (FTH exc, FTH args)
Throws exception exc with text built from args. If args is not an array, its string representation is used. If args is nil or an empty array, a default string is used. If args is an array with one element, this string is used. If args is an array and its first element is a format string with N %s-format signs, args should have N more elements. 
/*
 * ARGS: any object
 */
fth_throw_error(FTH_BAD_ARITY, proc);
  ⇒ #<bad-arity in test-proc>
/*
 * ARGS: nil or #()
 */
fth_throw_error(FTH_BAD_ARITY, FTH_NIL);
  ⇒ #<bad-arity: proc has bad arity>
/*
 * ARGS: #( string )
 */
fth_throw_error(FTH_BAD_ARITY,
    FTH_LIST_1(fth_make_string("test-proc"));
  ⇒ #<bad-arity in test-proc>
/*
 * ARGS: #( fmt arg1 arg2 arg3 )
 */
fth_throw_error(FTH_BAD_ARITY,
    FTH_LIST_4(fth_make_string("%s: %s args require, got %s"),
               proc,
               FTH_TWO,
               FTH_THREE));
  ⇒ #<bad-arity in test-proc: 2 args required, got 3>
void (FTH exc, FTH args)
The same as fth_throw_error except for replacing format signs ~A and ~S with %s. This function exists for usage in snd(1) where these signs appear.

Miscellaneous

char* (const char *name, char *def)
Returns value of environment variable name. If name isn't defined, returns def, see getenv(3).
FILE* (const char *command, const char *type)
If the environment variable FTH_POPEN_SHELL is set, this shell will be used to execute command. If the environment variable is not set, us the original popen(3) function to execute comment.
int (int from, int to, char **argv)
Sets *argc* and *argc* to values from upto to from the char pointer array argv.
char* (int n)
Looks up the language-dependent error message string corresponding to the error number n, see strerror(3).
char* (ficlVm *vm)
Converts and returns a String object from data stack to a C string.
void (ficlVm *vm, char *s)
Converts the C string s to a String object and pushs it on data stack.
void (ficlVm *vm, char *s)
Pushs the C string s on data stack as Forth string in the form of addr len.

Overwrites default dictionary size (1024 * 1024).
Overwrites default number of locals (2048).
Overwrites default size of return stack (1024).
Overwrites default size of parameter stack (8192).

fth(1), tecla(7).

This manual page describes version 1.4.5. libfth is based on , , version 4.0.31 written by John Sadler.

libfth and this manual page were written by Michael Scholz ⟨mi-scholz@users.sourceforge.net⟩.

Please report bugs to the author.

2025/01/22 FreeBSD 14.3-RELEASE
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.