LIBFTH(3) 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 FTH_ARRAY_P(obj)
Returns 1 if obj is an Array object, otherwise 0.
FTH fth_array_append(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_clear(FTH array)
Clears array and sets all elements to #f.
FTH fth_array_compact(FTH array)
Returns Array object with all nil elements removed.
FTH fth_array_copy(FTH array)
Returns copy of array with all elements new created in contrast to fth_array_to_array.
FTH fth_array_delete(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_delete_key(FTH array, FTH key)
Deletes and returns key from array if found, or #f.
FTH fth_array_each(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_each_with_index(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_array_equal_p(FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are Array objects of same length and contents, otherwise 0.
FTH fth_array_fill(FTH array, FTH value)
Sets all elements of array to value.
FTH fth_array_find(FTH array, FTH key)
Returns key if key exists in array.
ficlInteger fth_array_index(FTH array, FTH key)
Returns index of key in ary, or -1 if not found.
FTH fth_array_insert(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_join(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_array_length(FTH obj)
Returns length if obj is an Array object, otherwise -1.
FTH fth_array_map(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_member_p(FTH array, FTH key)
Returns 1 if key exists in ary, otherwise 0.
FTH fth_array_pop(FTH array)
Removes and returns last element of array. If array is empty, returns #f.
FTH fth_array_push(FTH array, FTH value)
Appends value, which may be any object, to array.
FTH fth_array_ref(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_reject(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_reverse(FTH array)
Returns array in reversed order.
FTH fth_array_set(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_shift(FTH array)
Removes and returns first element of array. If array is empty, returns #f.
FTH fth_array_sort(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_subarray(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_to_array(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_array_to_list(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_uniq(FTH array)
Returns array without duplicated elements.
FTH fth_array_unshift(FTH array, FTH value)
Preprends value to array.
FTH fth_make_array_len(ficlInteger len)
Returns Array object with len entries.
FTH fth_make_array_var(ficlInteger len, ...)
Returns Array object with len entries, initialized with values taken from the function argument list.
FTH fth_make_array_with_init(ficlInteger len, FTH init)
Returns Array object with len entries each initialized to init.
FTH fth_make_empty_array(void)
Returns an empty Array object with length 0.

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

int FTH_LIST_P(obj)
Returns 1 if obj is a list (nil or List object), otherwise 0.
int FTH_CONS_P(obj)
 
int FTH_PAIR_P(obj)
Return 1 if obj is a List object, otherwise 0.
FTH fth_car(FTH list)
 
FTH fth_cadr(FTH list)
 
FTH fth_caddr(FTH list)
 
FTH fth_cadddr(FTH list)
First, second, third, or fourth element of list or nil if list is shorter.
FTH fth_cdr(FTH list)
 
FTH fth_cddr(FTH list)
Rest, the cdr or cddr, of list without first or first and second element.
FTH fth_cons(FTH value, FTH list)
 
FTH fth_cons_2(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_list_append(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_copy(FTH list)
Returns copy of list with all elements new created in contrast to fth_list_to_array.
ficlInteger fth_list_length(FTH obj)
Returns length if obj is a list (nil or List object), otherwise -1.
FTH fth_list_member_p(FTH list, FTH key)
Returns #t if key exists in list, otherwise #f.
FTH fth_list_ref(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_reverse(FTH list)
Returns new list with elements reversed.
FTH fth_list_set(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_to_array(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 fth_make_empty_list(void)
Returns an empty List object with length 0.
FTH fth_make_list_len(ficlInteger len)
Returns List object with len entries.
FTH fth_make_list_var(ficlInteger len, ...)
Returns List object with len entries, initialized with values taken from function argument list.
FTH fth_make_list_with_init(ficlInteger len, FTH init)
Returns List object with len entries each initialized to init.

FTH fth_acons(FTH key, FTH value, FTH alist)
Returns new Lisp-like associated list from key-value pair and alist.
FTH fth_list_assoc(FTH alist, FTH key)
If key matches, returns corresponding key-value pair, otherwise #f.
FTH fth_list_assoc_ref(FTH alist, FTH key)
If key matches, returns corresponding value, otherwise #f.
FTH fth_list_assoc_remove(FTH alist, FTH key)
If key matches, removes key-value pair from alist. Returns current alist.
FTH fth_list_assoc_set(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 fth_file_atime(const char *name)
If name is a file, returns last access time.
FTH fth_file_basename(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 fth_file_chmod(const char *name, mode_t mode)
Changes access mode of file name to mode, see chmod(2).
void fth_file_copy(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 fth_file_ctime(const char *name)
If name is a file, returns status change time.
void fth_file_delete(const char *name)
If file name exists, delete it, otherwise do nothing, see unlink(2).
FTH fth_file_dirname(const char *name)
Returns directory part of name.
int fth_file_install(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 fth_file_length(const char *name)
If name is a file, returns length in bytes.
FTH fth_file_match_dir(FTH string, FTH regexp)
Returns an array of filenames in directory string matching regexp.
void fth_file_mkdir(const char *name, mode_t mode)
Creates directory name with access mode, see mkdir(2).
void fth_file_mkfifo(const char *name, mode_t mode)
Creates fifo file name with access mode, see mkfifo(2).
FTH fth_file_mtime(const char *name)
If name is a file, returns last modification time.
FTH fth_file_realpath(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 fth_file_rename(const char *src, const char *dst)
Renames src to dst, see rename(2).
void fth_file_rmdir(const char *name)
Removes empty directory name, see rmdir(2).
FTH fth_file_split(const char *name)
Splits name in dirname and basename and returns the result in an array of two strings.
void fth_file_symlink(const char *src, const char *dst)
Creates symlink from src to dst, see symlink(2).

int fth_file_block_p(const char *name)
Returns 1 if name is a block special file, see test(1) option -b.
int fth_file_character_p(const char *name)
Returns 1 if name is a character special file, see test(1) option -c.
int fth_file_directory_p(const char *name)
Returns 1 if name is a directory, see test(1) option -d.
int fth_file_executable_p(const char *name)
Returns 1 if name is an executable file, see test(1) option -x.
int fth_file_exists_p(const char *name)
Returns 1 if name is an existing file, see test(1) option -e.
int fth_file_fifo_p(const char *name)
Returns 1 if name is a named pipe, see test(1) option -p.
int fth_file_grpowned_p(const char *name)
Returns 1 if name matches effective group id, see test(1) option -G.
int fth_file_owned_p(const char *name)
Returns 1 if name matches effective user id, see test(1) option -O.
int fth_file_readable_p(const char *name)
Returns 1 if name is a readable file, see test(1) option -r.
int fth_file_setgid_p(const char *name)
Returns 1 if name has group id flag set, see test(1) option -g.
int fth_file_setuid_p(const char *name)
Returns 1 if name has user id flag set, see test(1) option -u.
int fth_file_socket_p(const char *name)
Returns 1 if name is a socket, see test(1) option -S.
int fth_file_sticky_p(const char *name)
Returns 1 if name has sticky bit set, see test(1) option -k.
int fth_file_symlink_p(const char *name)
Returns 1 if name is a symbolic link, see test(1) option -h.
int fth_file_writable_p(const char *name)
Returns 1 if name is a writable file, see test(1) option -w.
int fth_file_zero_p(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 FTH_HASH_P(obj)
Returns 1 if obj is a Hash object, otherwise 0.
void fth_hash_clear(FTH hash)
Removes all entries from hash, hash's length becomes zero.
FTH fth_hash_copy(FTH hash)
Returns copy of hash using object-copy for all elements.
FTH fth_hash_delete(FTH hash, FTH key)
Deletes key-value pair associated with key and returns key-value array, or #f if not found.
FTH fth_hash_each(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_hash_equal_p(FTH obj1, FTH obj2)
Returns #t if obj1 and obj2 are Hash objects with same length and contents.
FTH fth_hash_find(FTH hash, FTH key)
Returns key-value array if key exists, or #f if not found.
FTH fth_hash_keys(FTH hash)
Returns array of keys.
ficlInteger fth_hash_length(FTH obj)
Returns length if obj is a Hash object, otherwise -1.
FTH fth_hash_map(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_member_p(FTH hash, FTH key)
Returns #t if key exists, otherwise #f.
FTH fth_hash_ref(FTH hash, FTH key)
Returns associated value, or #f if key was not found.
FTH fth_hash_set(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_to_array(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_values(FTH hash)
Returns array of values.
FTH fth_make_hash(void)
Returns fresh empty Hash object.
FTH fth_make_hash_len(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_properties(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_property_ref(FTH obj, FTH key)
Returns obj's value associated with key from the global properties hash variable, or #f.
void fth_property_set(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_object_properties(FTH obj)
Returns obj's properties, or #f if empty.
FTH fth_object_property_ref(FTH obj, FTH key)
Returns obj's property value associated with key, or #f if not found.
void fth_object_property_set(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_word_properties(FTH obj)
Returns properties of obj, a ficlWord or Proc object, or #f.
FTH fth_word_property_ref(FTH obj, FTH key)
Returns value associated with key of property hash of obj, a ficlWord or Proc object, or #f.
void fth_word_property_set(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 FTH_HOOK_P(obj)
Returns 1 if obj is a Hook object, otherwise 0.
void fth_add_hook(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_apply(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_arity(FTH hook)
Returns hook's required arguments.
void fth_hook_clear(FTH hook)
Removes all of hook's procedures.
int fth_hook_empty_p(FTH hook)
Returns 1 if hook has no hook procedures, otherwise 0.
int fth_hook_equal_p(FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are Hook objects with same arity and procedures, otherwise 0.
int fth_hook_member_p(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_names(FTH hook)
Returns array of all of hook's procedure names (strings).
FTH fth_hook_to_array(FTH hook)
Returns array of all of hook's procedures.
FTH fth_make_hook(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 fth_make_hook_with_arity(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 fth_make_simple_hook(int arity)
Returns new Hook object with arity required arguments, 0 optional arguments and no rest arguments.
FTH fth_remove_hook(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_run_hook(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_run_hook_again(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_run_hook_bool(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 FTH_IO_P(obj)
Returns 1 if obj is an IO object, otherwise 0.
void fth_io_close(FTH io)
Flushes and closes io object and sets closed? to 1.
int fth_io_closed_p(FTH obj)
Returns 1 if io object is closed, otherwise 0.
int fth_io_eof_p(FTH io)
Returns 1 if EOF is reached, otherwise 0.
int fth_io_equal_p(FTH obj1, FTH obj2)
Returns #t if obj1 and obj2 are IO objects with equal filenames, modes and file positions.
char* fth_io_filename(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_fileno(FTH io)
Returns file descriptor of io.
void fth_io_flush(FTH io)
Flushes io object.
int fth_io_getc(FTH io)
Returns next character from io object or EOF.
int fth_io_input_p(FTH obj)
 
int fth_io_output_p(FTH obj)
Returns 1 if obj is an in- or output IO object, otherwise 0.
ficl2Integer fth_io_length(FTH obj)
Returns length of OBJ.
int fth_io_mode(FTH io)
Returns access mode of io object.
FTH fth_io_nopen(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 fth_io_open(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_io_popen(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_pos_ref(FTH io)
Returns current io object position.
void fth_io_pos_set(FTH io, ficl2Integer pos)
Sets io object position to pos.
void* fth_io_ptr(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_putc(FTH io, int c)
Writes character c to io object.
char* fth_io_read(FTH io)
Returns next line from io object or NULL if EOF.
FTH fth_io_read_line(FTH io)
Returns next line as FTH string from io object or #f if EOF. Required for fth_object_apply.
FTH fth_io_readlines(FTH io)
Returns the entire io object contents as an array of strings, line by line.
void fth_io_rewind(FTH io)
Rewinds position to begin of io object.
FTH fth_io_sopen(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_to_string(FTH io)
Returns contents of io object as string if possible.
void fth_io_write(FTH io, const char *line)
Writes line to io object.
void fth_io_write_and_flush(FTH io, const char *line)
Writes line to io object and flush the IO object.
void fth_io_write_format(FTH io, FTH fmt, FTH args)
Writes formatted string to io object.
void fth_io_writelines(FTH io, FTH array-of-lines)
Writes array-of-lines to io object.
FTH fth_readlines(const char *name)
Opens file name, reads its contents in an array, closes file and returns the array.
void fth_writelines(const char *name, FTH array-of-lines)
Opens file name, writes the contents of array-of-lines to it and closes file.
int fth_get_exit_status(void)
Returns exit status of last extern process from fth_file_shell, fth_file_system, etc.
int fth_set_exit_status(int status)
Sets global variable fth_exit_status.
FTH fth_set_io_stdin(FTH io)
 
FTH fth_set_io_stdout(FTH io)
 
FTH fth_set_io_stderr(FTH io)
They set io as the current input, output, and error IO object and return the old one.
FTH fth_gethostbyaddr(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_gethostbyname(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_getservbyname(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_getservbyport(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* fth_tmpfile(void)
 
FTH fth_io_tmpfile(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).

Initialization Functions
void fth_init(void)
This function must be called before any libfth.so action can take place.
void fth_exit(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 fth_reset(void)
Resets Ficl System and Ficl Vm and restarts Fth.

Evaluation Functions

int fth_catch_eval(const char *buffer)
 
int fth_catch_exec(ficlWord *word)
Execute C string buffer or ficlWord word and return status only as FTH_OKAY, FTH_BYE (exit), or FTH_ERROR.
FTH fth_eval(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.

Loading Source Files

void fth_add_load_lib_path(const char *path)
 
void fth_unshift_load_lib_path(const char *path)
Add path at the front or back of the global array variable *load-lib-path* if not already there.
void fth_add_load_path(const char *path)
 
void fth_unshift_load_path(const char *path)
Add path at the front or back of the global array variable *load-path* if not already there.
void fth_add_loaded_files(const char *file)
Pushs file at the end of the global array variable *loaded-files* if not already there.
char* fth_basename(const char *path)
Returns the part of path after the last ‘/’.
FTH fth_find_file(FTH name)
Returns full path of name or #f.
void fth_install_file(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 fth_dl_load(const char *lib, const char *func)
 
FTH fth_load_file(const char *name)
 
FTH fth_require_file(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 fth_load_init_file(const char *init_file)
 
FTH fth_load_global_init_file(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.

Various Functions

void fth_add_feature(const char *name)
 
int fth_provided_p(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_apropos(FTH regexp)
 
FTH fth_find_in_wordlist(const char *name)
Return array with found words from the current word list matching regexp or name.
FTH fth_gethostname(void)
 
int fth_sethostname(FTH fs)
Get and set hostname, see gethostname(3) and sethostname(3).
FTH fth_getrusage(void)
Returns an array of 16 elements with all slots of struct rusage. See getrusage(2) for more information.
char* fth_parse_word(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 fth_uname(void)
Returns Hash object with five slots containing entries from uname(3), which are:
'sysname
 
'nodename
 
'release
 
'version
 
'machine
 
char* fth_version(void)
 
char* fth_short_version(void)
Return short or long version strings.
FTH fth_wordlist_each(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 FTH_EXACT_P(obj)
 
int fth_exact_p(obj)
Return 1 if obj is an exact number, otherwise 0.
int FTH_FIXNUM_P(obj)
 
int fth_fixnum_p(obj)
Return 1 if obj is a fixnum, otherwise 0.
int FTH_NUMBER_P(obj)
 
int fth_number_p(obj)
 
int FTH_FLOAT_P(obj)
Return 1 if obj is any kind of a number, otherwise 0.
int FTH_INTEGER_P(obj)
 
int FTH_LONG_LONG_P(obj)
 
int fth_integer_p(obj)
 
int FTH_UNSIGNED_P(obj)
 
int fth_unsigned_p(obj)
Return 1 if obj is integer, otherwise 0.
int fth_isinf(ficlFloat f)
 
int fth_isnan(ficlFloat f)
Return 1 if f is infinite or not-a-number, otherwise 0.
int FTH_LLONG_P(obj)
 
int FTH_ULLONG_P(obj)
 
int fth_ullong_p(obj)
Return 1 if obj is a Llong object, otherwise 0.
FTH fth_make_float(ficlFloat f)
 
FTH fth_float_copy(FTH x)
Return a Float object.
FTH fth_make_llong(ficl2Integer d)
 
FTH fth_make_ullong(ficl2Unsigned ud)
 
FTH fth_llong_copy(FTH obj)
Return a Llong object.
FTH fth_make_int(ficlInteger n)
 
FTH fth_make_unsigned(ficlUnsigned u)
 
FTH fth_make_long_long(ficl2Integer d)
 
FTH fth_make_ulong_long(ficl2Unsigned ud)
Return a Fixnum or a Llong object depending on input.
ficlFloat fth_float_ref(FTH x)
 
ficlFloat fth_real_ref(FTH x)
 
ficlInteger fth_int_ref(FTH x)
 
ficlUnsigned fth_unsigned_ref(FTH x)
 
ficl2Integer fth_long_long_ref(FTH x)
 
ficl2Unsigned fth_ulong_long_ref(FTH x)
They convert any number x to the corresponding return type.
ficlFloat fth_float_ref_or_else(FTH x, ficlFloat fallback)
 
ficlInteger fth_int_ref_or_else(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 FTH_COMPLEX_P(obj)
Returns 1 if obj is a Complex object, otherwise 0.
FTH fth_make_complex(ficlComplex z)
 
FTH fth_make_polar(ficlFloat real, ficlFloat theta)
 
FTH fth_make_rectangular(ficlFloat real, ficlFloat image)
Return a Complex object.
ficlComplex fth_complex_ref(FTH x)
They convert any number x to ficlComplex.
ficlComplex ficlStackPopComplex(ficlStack *stack)
 
void ficlStackPushComplex(ficlStack *stack, ficlComplex cp)
The Complex number stack functions to push to and pop from stack Complex objects.

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

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

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

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

int fth_gc_marked_p(FTH obj)
 
int fth_gc_protected_p(FTH obj)
 
int fth_gc_permanent_p(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_gc_mark(FTH obj)
 
void fth_gc_unmark(FTH obj)
 
FTH fth_gc_protect(FTH obj)
 
FTH fth_gc_unprotect(FTH obj)
 
FTH fth_gc_permanent(FTH obj)
They mark or unmark obj to protect or unprotect it from garbage collection.
FTH fth_gc_on(void)
 
FTH fth_gc_off(void)
 
void fth_gc_run(void)
They turn garbage collection on or off and run garbage collection.

void* fth_instance_ref_gen(FTH obj)
 
FTH fth_instance_ref_obj(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_instance_p(FTH obj)
 
int fth_object_is_instance_of(FTH obj, FTH type)
Return #t if obj is an instance resp. an instance of type.
FTH fth_make_instance(FTH obj, void *gen)
Returns new instance of object-type obj with gen struct wrapped in.
int fth_instance_flag_p(FTH obj, int flag)
 
int fth_instance_type_p(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_object_type_p(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 fth_make_object_type_from(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_object_name(FTH obj)
Returns object-type name of obj as a string.

FTH fth_set_object_apply(FTH obj, void *fnc, int req, int opt, int rest)
 
FTH fth_set_object_copy(FTH obj, FTH (*fnc)(FTH obj))
 
FTH fth_set_object_dump(FTH obj, FTH (*fnc)(FTH obj))
 
FTH fth_set_object_equal_p(FTH obj, FTH (*fnc)(FTH obj1, FTH obj2))
 
FTH fth_set_object_free(FTH obj, void (*fnc)(FTH obj))
 
FTH fth_set_object_inspect(FTH obj, FTH (*fnc)(FTH obj))
 
FTH fth_set_object_length(FTH obj, FTH (*fnc)(FTH obj))
 
FTH fth_set_object_mark(FTH obj, void (*fnc)(FTH obj))
 
FTH fth_set_object_to_array(FTH obj, FTH (*fnd)(FTH obj))
 
FTH fth_set_object_to_string(FTH obj, FTH (*fnc)(FTH obj))
 
FTH fth_set_object_value_ref(FTH obj, FTH (*fnc)(FTH obj, FTH index))
 
FTH fth_set_object_value_set(FTH obj, FTH (*fnc)(FTH obj, FTH index, FTH value))
They set fnc as object-xxx function to object-type obj.

ficlInteger fth_cycle_next(FTH obj)
 
ficlInteger fth_cycle_pos_0(FTH obj)
 
ficlInteger fth_cycle_pos_ref(FTH obj)
 
ficlInteger fth_cycle_pos_set(FTH obj, ficlInteger index)
 
FTH fth_object_cycle_ref(FTH obj)
 
FTH fth_object_cycle_set(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_hash_id(FTH obj)
Returns hash id computed from string representation of obj. Objects with the same contents have the same id.
FTH fth_object_apply(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_object_copy(FTH obj)
Returns copy of obj. Copies any element if obj is an instance.
FTH fth_object_dump(FTH obj)
 
char* fth_to_c_dump(FTH obj)
Return dump string of obj which may be evaled to reinstate the object from a file.
int fth_object_empty_p(FTH obj)
Returns 1 if length of obj is zero, otherwise 0.
int fth_object_equal_p(FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 have equal contents, otherwise 0.
FTH fth_object_id(FTH obj)
Returns object id of obj, a uniq number.
FTH fth_object_find(FTH obj, FTH key)
 
ficlInteger fth_object_index(FTH obj, FTH key)
 
int fth_object_member_p(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_object_inspect(FTH obj)
 
char* fth_to_c_inspect(FTH obj)
Return inspect string of obj.
ficlInteger fth_object_length(FTH obj)
Returns length of obj.
int fth_object_range_p(FTH obj, ficlInteger index)
Returns 1 if index is in range of obj, otherwise 0.
FTH fth_object_sort(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_object_to_array(FTH obj)
Returns obj as array.
FTH fth_object_to_string(FTH obj)
 
char* fth_to_c_string(FTH obj)
Return string representation of obj.
FTH fth_object_value_ref(FTH obj, ficlInteger index)
 
FTH fth_object_value_set(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 ficl_to_fth(FTH obj)
 
FTH fth_to_ficl(FTH obj)
Convert ficlInteger to Fixnum or Fixnum to ficlInteger, the rest stays.
FTH fth_pop_ficl_cell(ficlVm *vm)
 
void fth_push_ficl_cell(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_close(FTH port)
 
void fth_port_flush(FTH port)
Flush or close port. If port is #f, do nothing.
void fth_port_display(FTH port, FTH obj)
Writes string representation of obj to port. If port is #f, prints to Ficl output.
int fth_port_getc(FTH port)
 
char* fth_port_gets(FTH port)
Return next character or next line from port IO object. If port is #f, read from Ficl input.
void fth_port_putc(FTH port, int c)
 
void fth_port_puts(FTH port, const char *str)
Write character or string to port. If port is #f, write to Ficl output.
in_cb fth_set_read_cb(in_cb cb)
 
out_cb fth_set_print_cb(out_cb cb)
 
out_cb fth_set_error_cb(out_cb cb)
 
out_cb fth_set_print_and_error_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_to_string(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 fth_debug(const char *fmt, ...)
Writes the formatted string to FILE *stderr wrapped in #<DEBUG(C): ...> and returns the written bytes.
void fth_die(const char *fmt, ...)
 
int fth_warning(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 fth_error(const char *str)
 
int fth_errorf(const char *fmt, ...)
 
int fth_verrorf(const char *fmt, va_list ap)
Write formatted string to Ficl error output. They return the written bytes.
char* fth_format(const char *fmt, ...)
 
char* fth_vformat(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 fth_fprintf(FILE *fp, const char *fmt, ...)
 
int fth_ioprintf(FTH io, const char *fmt, ...)
 
int fth_port_printf(FTH port, const char *fmt, ...)
 
int fth_vfprintf(FILE *fp, const char *fmt, va_list ap)
 
int fth_vioprintf(FTH io, const char *fmt, va_list ap)
 
int fth_port_vprintf(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* fth_read(void)
 
int fth_print(const char *str)
 
int fth_printf(const char *fmt, ...)
 
int fth_vprintf(const char *fmt, va_list ap)
Read from Ficl input or write to Ficl output. The write-functions return the written bytes.
int fth_asprintf(char **result, const char *fmt, ...)
 
int fth_vasprintf(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 fth_snprintf(char *buffer, size_t size, const char *fmt, ...)
 
int fth_vsnprintf(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_word_defined_p(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_word_type_p(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 FTH_PROC_P(obj)
Returns 1 if obj is a Proc object, otherwise 0.
int FTH_WORD_P(obj)
Returns 1 if obj is a ficlWord, otherwise 0.
ficlWord* fth_define_procedure(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* fth_define_void_procedure(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_documentation_ref(FTH obj)
Returns documentation property string of obj or #f.
void fth_documentation_set(FTH obj, FTH doc)
Sets documentation property string of any obj to doc.
FTH fth_get_optarg(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_get_optkey(FTH key, FTH def)
 
int fth_get_optkey_fix(FTH key, int def)
 
ficlInteger fth_get_optkey_int(FTH key, ficlInteger def)
 
ficl2Integer fth_get_optkey_2int(FTH key, ficl2Integer def)
 
char* fth_get_optkey_str(FTH key, char *def)
Return either default value def or a value found on stack specified by keyword key.
FTH fth_make_proc(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 fth_make_proc_from_func(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_apply(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_arity(FTH proc)
If proc is a Proc object, returns required arguments as C int, otherwise returns 0.
FTH fth_proc_call(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_proc_name(FTH obj)
If obj is a ficlWord, returns name as C string, otherwise returns "not-a-proc".
FTH fth_proc_source_ref(FTH proc)
Returns source string property of proc, or #f if not available.
void fth_proc_source_set(FTH proc, FTH source)
Sets source string property of proc to source.
ficlWord* fth_proc_to_xt(FTH proc)
Returns the actual word (the execution token xt) of proc.
FTH fth_source_file(FTH obj)
Returns source file where obj was created, or #f if a C-primitive or not defined.
FTH fth_source_line(FTH obj)
Returns source line number where obj was created or #f if a C-primitive or not defined.
FTH fth_source_ref(FTH obj)
Returns source string of obj, a proc or xt, or #f if not found.
void fth_source_set(FTH obj, FTH source)
Sets source string of obj, a proc or xt, to source.
ficlWord* fth_word_doc_set(ficlWord *word, const char *str)
Sets word's documentation property to str.
FTH fth_xt_apply(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 fth_xt_call(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* fth_word_ref(const char *name)
Finds name in Forth dictionary and returns ficlWord.
FTH fth_proc_ref(const char *name)
Finds name in Forth dictionary and returns ficlWord casted to FTH.
ficlWord* fth_variable_obj(const char *name)
Finds name in Forth dictionary and returns ficlWord casted to FTH if it's a variable, otherwise #f.

FTH fth_define(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 fth_define_constant(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 fth_define_variable(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 fth_defined_p(const char *name)
Returns 1 if name is defined in the dictionary, otherwise 0.
void fth_trace_var(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_untrace_var(FTH obj)
Removes previously installed hook from obj.
FTH fth_var_ref(FTH obj)
If obj is a global variable, return value, otherwise #f.
FTH fth_var_set(FTH obj, FTH value)
If obj is a global variable, set value and protect it from GC. Returns value.
FTH fth_variable_ref(const char *name)
Return FTH value from global variable or constant name.
FTH fth_variable_set(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 fth_regexp_var_ref().
int FTH_REGEXP_P(obj)
Returns 1 if obj is a Regexp object, otherwise 0.
FTH fth_make_regexp(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 fth_regexp_find(const char *reg, const char *str)
Searches reg in str and returns first match's position or -1 if no match was found.
int fth_regexp_find_flags(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_match(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_replace(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"
ficlInteger fth_regexp_search(FTH regexp, FTH string, ficlInteger start, ficlInteger range)
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 FTH_STRING_P(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 FTH_CHAR_P(obj)
 
int fth_char_p(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 fth_make_empty_string(void)
Returns an empty String object. 
FTH fs = fth_make_empty_string(); ⇒ ""
fth_string_length(fs); ⇒ 0
FTH fth_make_string(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 fth_make_string_format(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 fth_make_string_len(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 fth_make_string_or_false(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_string_append(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_capitalize(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_c_char_ref(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_c_char_set(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_char_ref(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_char_set(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_chomp(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_copy(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_delete(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_downcase(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_string_equal_p(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_eval(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_fill(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_find(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_format(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_string_greater_p(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_index(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_insert(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_length(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_string_less_p(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_member_p(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_string_not_equal_p(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_pop(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_push(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_ref(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_replace(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_reverse(FTH string)
Returns the same String object string reversed. 
FTH fs = fth_make_string("foo");
fth_string_reverse(fs); ⇒ "oof"
FTH fth_string_scat(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_sformat(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_shift(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_sncat(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_split(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_substring(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_to_array(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_unshift(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_upcase(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 fth_string_vformat(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_vsformat(FTH string, const char *fmt, va_list ap)
The same as fth_string_sformat except for a va_list ap.

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

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

int FTH_EXCEPTION_P(obj)
Returns 1 if obj is an exception, otherwise 0.
FTH fth_exception(const char *name)
Returns a new exception name.
int fth_exception_equal_p(FTH obj1, FTH obj2)
Returns 1 if obj1 and obj2 are exceptions with identical names, otherwise 0.
FTH fth_exception_last_message_ref(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_exception_last_message_set(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_exception_message_ref(FTH exc)
Returns the message of exception exc.
void fth_exception_message_set(FTH exc, FTH msg)
Sets message msg, a string or #f, to exception exc.
char* fth_exception_ref(FTH obj)
Returns C string name of exception obj without first sign (') or NULL.
FTH fth_make_exception(const char *name, const char *message)
Creates and returns the new exception named name with message; message may be NULL.
int fth_symbol_or_exception_p(FTH obj)
Returns 1 if obj is a symbol or an exception, otherwise 0.
FTH fth_symbol_or_exception_ref(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_symbol_to_exception(FTH obj)
Returns symbol obj as exception.

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

Memory Allocation

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

void* fth_calloc(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* fth_malloc(size_t size)
Allocates size bytes of uninitialized memory, see malloc(3).
void* fth_realloc(void *p, size_t size)
Changes the size of the previously allocated memory referenced by p to size, see realloc(3).
void fth_free(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* fth_strdup(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* fth_strndup(const char *s, size_t size)
Copies at most size characters from the string s always NUL terminating the copied string, see strndup(3).

String Functions

The string functions return always NUL terminated strings.

char* fth_strcat(char *d, size_t size, const char *s)
Appends s to d but not more than size - 1 chars; appends terminating ‘\0’.
char* fth_strncat(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* fth_strcpy(char *d, size_t size, const char *s)
Copies s to d but not more than size - 1 chars; appends terminating ‘\0’.
char* fth_strncpy(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 fth_strlen(const char *s)
Computes the length of the string s. If s is NULL, returns 0, see strlen(3).
size_t fth_strnlen(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).

Evaluate, Repl, and Throw Exception

int fth_evaluate(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 fth_execute_xt(ficlVm *vm, ficlWord *word)
Executes ficlWord word. Returns the evaluation status, uses values on stack and leave execution results on stack, if any.
void fth_repl(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_throw(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_throw_error(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_throw_list(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* fth_getenv(const char *name, char *def)
Returns value of environment variable name. If name isn't defined, returns def, see getenv(3).
FILE* fth_popen(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 fth_set_argv(int from, int to, char **argv)
Sets *argc* and *argc* to values from upto to from the char pointer array argv.
char* fth_strerror(int n)
Looks up the language-dependent error message string corresponding to the error number n, see strerror(3).
char* pop_cstring(ficlVm *vm)
Converts and returns a String object from data stack to a C string.
void push_cstring(ficlVm *vm, char *s)
Converts the C string s to a String object and pushs it on data stack.
void push_forth_string(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 Ficl, Forth-inspired command language, 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 NetBSD 10.99.12