Hello-World application:

% 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 -I/usr/local/include -c hello.c 
% cc hello.o -o hello -L/usr/local/lib -lfth -lm

A test run looks like this:

% ./hello ⇒ Hello, World!

Hello-World library:

% 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 -I/usr/local/include -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

The new words hello-prim and hello-proc as well as the variable intro and the constant world are available.

% fth 
fth> dl-load ./libhello.so Init_libhello 
fth> intro hello-prim ⇒ "Hello, World!" 
fth> intro hello-proc ⇒ "Hello, World!" 
fth> "Goodbye" to intro 
fth> intro hello-prim ⇒ "Goodbye, World!" 
fth> "Bye" hello-proc ⇒ "Bye, World!" 
fth> bye 
%

If the new library is finished, one can install it with

% fth -ve "install libhello.so"

After installing you can load your new library with

dl-load libhello Init_libhello

Arrays

bool FTH_ARRAY_P(obj)

bool FTH_ASSOC_P(obj)

bool FTH_CONS_P(obj)

bool FTH_PAIR_P(obj)

All four return true if obj is an array object, otherwise false.

FTH fth_array_append(FTH array1, FTH array2)

void fth_array_clear(FTH array)

FTH fth_array_compact(FTH array)

FTH fth_array_copy(FTH array)

FTH fth_array_delete(FTH array, ficlInteger index)

FTH fth_array_delete_key(FTH array, FTH key)

FTH fth_array_each(FTH array, FTH (*func)(FTH value, FTH data), FTH data)

FTH fth_array_each_with_index(FTH array, FTH (*func)(FTH value, FTH data, ficlInteger idx), FTH data)

bool fth_array_equal_p(FTH obj1, FTH obj2)

FTH fth_array_fill(FTH array, FTH value)

FTH fth_array_find(FTH array, FTH key)

ficlInteger fth_array_index(FTH array, FTH key)

FTH fth_array_insert(FTH array, ficlInteger index, FTH value)

FTH fth_array_join(FTH array, FTH sep)

ficlInteger fth_array_length(FTH obj)

If obj is an Array object, return its length, otherwise -1.

FTH fth_array_map(FTH array, FTH (*func)(FTH value, FTH data), FTH data)

bool fth_array_member_p(FTH array, FTH key)

FTH fth_array_pop(FTH array)

FTH fth_array_push(FTH array, FTH value)

FTH fth_array_ref(FTH array, ficlInteger index)

Return value at position index. Negative index counts from backward. Raise out-of-range exception if index is not in array's range.

FTH fth_array_reject(FTH array, FTH proc_or_xt, FTH args)

FTH fth_array_reverse(FTH array)

FTH fth_array_set(FTH array, ficlInteger index, FTH value)

Store value at position index and return value. Negative index counts from backward. Raise out-of-range exception if index is not in array's range.

FTH fth_array_shift(FTH array)

FTH fth_array_sort(FTH array, FTH proc_or_xt)

FTH fth_array_subarray(FTH array, ficlInteger start, ficlInteger end)

FTH fth_array_to_array(FTH array)

FTH fth_array_to_list(FTH obj)

Return obj as List object.

FTH fth_array_uniq(FTH array)

FTH fth_array_unshift(FTH array, FTH value)

FTH fth_make_array_len(ficlInteger len)

FTH fth_make_array_var(ficlInteger len, ...)

FTH fth_make_array_with_init(ficlInteger len, FTH init)

Return Array with len entries each initialized to init.

FTH fth_make_empty_array(void)

Assocs:

FTH fth_acell_key(FTH cell)

FTH fth_acell_value(FTH cell)

FTH fth_array_assoc(FTH assoc, FTH key)

FTH fth_array_assoc_ref(FTH assoc, FTH key)

FTH fth_array_assoc_remove(FTH assoc, FTH key)

FTH fth_array_assoc_set(FTH assoc, FTH key, FTH value)

FTH fth_assoc(FTH assoc, FTH key, FTH value)

FTH fth_make_acell(FTH key, FTH value)

Lists:

bool FTH_LIST_P(obj)

Return true if obj is nil or a cons pointer (array object), otherwise false.

FTH fth_acons(FTH key, FTH value, FTH alist)

FTH fth_cadddr(FTH list)

FTH fth_caddr(FTH list)

FTH fth_cadr(FTH list)

FTH fth_car(FTH list)

If length of list is greather than 0, return first list entry, otherwise FTH_NIL.

FTH fth_cddr(FTH list)

FTH fth_cdr(FTH list)

If length of list is greather than 1, return new list without first entry of list, otherwise FTH_NIL.

FTH fth_cons(FTH value, FTH list)

Return Lisp-like cons pointer with value as car and list as cdr.

FTH fth_cons_2(FTH obj1, FTH obj2, FTH list)

Return Lisp-like cons pointer with 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, return FTH_NIL, otherwise return new List object with each element of args append with fth_array_append.

FTH fth_list_assoc(FTH alist, FTH key)

If key matches, return corresponding key-value pair, otherwise FTH_FALSE.

FTH fth_list_assoc_ref(FTH alist, FTH key)

If key matches, return corresponding value, otherwise FTH_FALSE.

FTH fth_list_assoc_remove(FTH alist, FTH key)

If key matches, remove key-value pair from alist. Return current assoc-list.

FTH fth_list_assoc_set(FTH alist, FTH key, FTH value)

If key matches, set key-value pair, otherwise add new pair to alist. Return current assoc-list.

FTH fth_list_copy(FTH list)

Return copy of list using object-copy for all elements.

ficlInteger fth_list_length(FTH obj)

If obj is a list (or array), return length of list, if obj is nil, return 0 otherwise -1.

FTH fth_list_member_p(FTH list, FTH key)

Return FTH_TRUE if key exists in list, otherwise FTH_FALSE.

FTH fth_list_ref(FTH list, ficlInteger index)

Return element at position index. Negative index counts from backward. Raise out-of-range exception if index is not in list's range.

FTH fth_list_reverse(FTH list)

Return new list with elements reversed.

FTH fth_list_set(FTH list, ficlInteger index, FTH value)

Store value at position index and return value. Negative index counts from backward. Raise out-of-range exception if index is not in list's range.

FTH fth_list_to_array(FTH list)

FTH fth_make_empty_list(void)

FTH fth_make_list_len(ficlInteger len)

FTH fth_make_list_var(ficlInteger len, ...')

FTH fth_make_list_with_init(ficlInteger len, FTH init)

File Functions

General file functions:

FTH fth_file_atime(const char *name)

FTH fth_file_basename(const char *name, const char *ext)

void fth_file_chmod(const char *name, mode_t mode)

void fth_file_copy(const char *src, const char *dst)

FTH fth_file_ctime(const char *name)

void fth_file_delete(const char *name)

FTH fth_file_dirname(const char *name)

bool fth_file_install(const char *src, const char *dst, mode_t mode)

FTH fth_file_length(const char *name)

FTH fth_file_match_dir(FTH string, FTH regexp)

void fth_file_mkdir(const char *name, mode_t mode)

void fth_file_mkfifo(const char *name, mode_t mode)

FTH fth_file_mtime(const char *name)

FTH fth_file_realpath(const char *name)

void fth_file_rename(const char *src, const char *dst)

void fth_file_rmdir(const char *name)

FTH fth_file_split(const char *name)

void fth_file_symlink(const char *src, const char *dst)

File test functions:

bool fth_file_block_p(const char *name)

bool fth_file_character_p(const char *name)

bool fth_file_directory_p(const char *name)

bool fth_file_executable_p(const char *name)

bool fth_file_exists_p(const char *name)

bool fth_file_fifo_p(const char *name)

bool fth_file_grpowned_p(const char *name)

bool fth_file_owned_p(const char *name)

bool fth_file_readable_p(const char *name)

bool fth_file_setgid_p(const char *name)

bool fth_file_setuid_p(const char *name)

bool fth_file_socket_p(const char *name)

bool fth_file_sticky_p(const char *name)

bool fth_file_symlink_p(const char *name)

bool fth_file_writable_p(const char *name)

bool fth_file_zero_p(const char *name)

Hashs

bool FTH_HASH_P(obj)

Return true if obj is a hash object, otherwise false.

void fth_hash_clear(FTH hash)

FTH fth_hash_copy(FTH hash)

FTH fth_hash_delete(FTH hash, FTH key)

FTH fth_hash_each(FTH hash, FTH (*f)(FTH key, FTH val, FTH data), FTH data)

bool fth_hash_equal_p(FTH obj1, FTH obj2)

FTH fth_hash_find(FTH hash, FTH key)

FTH fth_hash_keys(FTH hash)

FTH fth_hash_map(FTH hash, FTH (*f)(FTH key, FTH val, FTH data), FTH data)

bool fth_hash_member_p(FTH hash, FTH key)

FTH fth_hash_ref(FTH hash, FTH key)

void fth_hash_set(FTH hash, FTH key, FTH value)

FTH fth_hash_to_array(FTH hash)

FTH fth_hash_values(FTH hash)

FTH fth_make_hash(void)

FTH fth_make_hash_len(int hashsize)

Property functions:

FTH fth_hash_id(FTH obj)

FTH fth_object_id(FTH obj)

FTH fth_object_properties(FTH obj)

FTH fth_object_property_ref(FTH obj, FTH key)

void fth_object_property_set(FTH obj, FTH key, FTH value)

FTH fth_properties(FTH obj)

FTH fth_property_ref(FTH obj, FTH key)

void fth_property_set(FTH obj, FTH key, FTH value)

FTH fth_word_properties(FTH obj)

FTH fth_word_property_ref(FTH obj, FTH key)

void fth_word_property_set(FTH obj, FTH key, FTH value)

Hooks

bool FTH_HOOK_P(obj)

Return true if obj is a hook object, otherwise false.

void fth_add_hook(FTH hook, FTH proc)

Add hook procedure proc to hook. Raise bad-arity exception if proc's arity doesn't match hook's arity.

FTH fth_hook_apply(FTH hook, FTH args, const char *caller)

int fth_hook_arity(FTH hook)

void fth_hook_clear(FTH hook)

Remove all hook procedures from hook.

bool fth_hook_empty_p(FTH hook)

Return true if no hook procedure exist in hook, otherwise false.

bool fth_hook_equal_p(FTH obj1, FTH obj2)

bool fth_hook_member_p(FTH hook, FTH name)

FTH fth_hook_names(FTH hook)

FTH fth_hook_to_array(FTH hook)

Return array of all hook procedures.

FTH fth_make_hook(const char *name, int arity, const char *doc)

Return a Hook object called name with arity required arguments, 0 optional arguments and no rest arguments. An optional documentation doc can be provided.

FTH fth_make_hook_with_arity(const char *n, int req, int opt, bool rest, const char *d)

FTH fth_make_simple_hook(int arity)

Return a Hook object with arity required arguments, 0 optional arguments and no rest arguments.

FTH fth_remove_hook(FTH hook, FTH name)

FTH fth_run_hook(FTH hook, int len, ...)

FTH fth_run_hook_again(FTH hook, int len, ...)

FTH fth_run_hook_bool(FTH hook, int len, ...)

IO functions

bool FTH_IO_P(obj)

Return true if obj is an IO object, otherwise false.

void fth_io_close(FTH io)

bool fth_io_closed_p(FTH obj)

bool fth_io_eof_p(FTH io)

bool fth_io_equal_p(FTH obj1, FTH obj2)

char* fth_io_filename(FTH io)

int fth_io_fileno(FTH io)

void fth_io_flush(FTH io)

int fth_io_getc(FTH io)

bool fth_io_input_p(FTH obj)

ficl2Integer fth_io_length(FTH obj)

int fth_io_mode(FTH io)

FTH fth_io_nopen(const char *host, int port, int type)

FTH fth_io_open(const char *name, int fam)

bool fth_io_output_p(FTH obj)

FTH fth_io_popen(FTH cmd, int fam)

ficl2Integer fth_io_pos_ref(FTH io)

void fth_io_pos_set(FTH io, ficl2Integer pos)

void* fth_io_ptr(FTH io)

void fth_io_putc(FTH io, int c)

char* fth_io_read(FTH io)

FTH fth_io_read_line(FTH io)

FTH fth_io_readlines(FTH io)

void fth_io_rewind(FTH io)

FTH fth_io_sopen(FTH string, int fam)

FTH fth_io_to_string(FTH io)

void fth_io_write(FTH io, const char *line)

void fth_io_write_and_flush(FTH io, const char *line)

void fth_io_write_format(FTH io, FTH fmt, FTH args)

void fth_io_writelines(FTH io, FTH array)

FTH fth_readlines(const char *name)

int fth_set_exit_status(int status)

FTH fth_set_io_stderr(FTH io)

FTH fth_set_io_stdin(FTH io)

FTH fth_set_io_stdout(FTH io)

void fth_writelines(const char *name, FTH array)

Miscellaneous

Predicate functions:

bool fth_boolean_p(FTH obj)

bool fth_instance_flag_p(FTH obj, int flags)

bool fth_instance_type_p(FTH obj, int type)

bool fth_word_defined_p(FTH obj)

bool fth_word_type_p(FTH obj, int type)

Initialization functions:

void fth_exit(int n)

void fth_make_ficl(unsigned int d_size, unsigned int s_size, unsigned int r_size, unsigned int l_size)

void fth_reset(void)

Evaluation functions:

void fth_add_feature(const char *name)

Push C string name to environment word list for later review with provided? and *features*.

int fth_catch_eval(const char *buffer)

int fth_catch_exec(ficlWord *word)

FTH fth_eval(const char *buffer)

Evaluate C string buffer. If buffer is NULL, return #undef, if buffer evaluates to FTH_BYE, exit program, if buffer evaluates to no value, return #undef, if buffer evaluates to a single value, remove it from stack and return it, if buffer evaluates to more than one value, remove them from stackand and return them as Fth array.

void fth_init(void)

This function must be called before any libfth.so action can take place.

bool fth_provided_p(const char *name)

Test if feature name exists in environment word list.

Loading source files:

void fth_add_load_lib_path(const char *path)

Push path at the end of global array variable *load-lib-path* if not already there.

void fth_add_load_path(const char *path)

Push path at the end of global array variable *load-path* if not already there.

void fth_add_loaded_files(const char *file)

Push file at the end of global array variable *loaded-files* if not already there.

char* fth_basename(const char *path)

FTH fth_dl_load(const char *lib, const char *func)

Load C string name as dynamic library if not already loaded and add name to global array *loaded-files*. C string func will be called after load was successful. Before loading the dynamic library run hook before-load-hook if not empty. If this hook returns #f, return immediately without loading the library and return FTH_FALSE. If loading finishes successfully or library was already loaded, return FTH_TRUE, otherwise raise so-file-error exception. After loading the dynamic library run hook after-load-hook if not empty. If name has no file extension, ".so" will be added. If name or name plus ".so" doesn't exist, try all path names from *load-lib-path* with name.

FTH fth_find_file(FTH name)

void fth_install(void)

void fth_install_file(FTH fname)

FTH fth_load_file(const char *name)

Load C string name as Fth source file and add name to global array *loaded-files*. Before loading source file run hook before-load-hook if not empty. If this hook returns #f, nothing is loaded and return value is FTH_FALSE. If loading finishes successfully, return value is FTH_TRUE, otherwise throw an exception. After loading source file run hook after-load-hook if not empty. If name has no file extension, FTH_FILE_EXTENSION ‘.fs' will be added. If name or name plus FTH_FILE_EXTENSION doesn't exist, try all path names from *load-path* with name.

FTH fth_load_global_init_file(void)

Load FTH_GLOBAL_INIT_FILE ${prefix}/etc/fthrc as Forth source file if it exists, otherwise do nothing. Run before-load-hook and after-load-hook if not empty.

FTH fth_load_init_file(const char *init_file)

Load C string init_file 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. Run before-load-hook and after-load-hook if not empty.

FTH fth_require_file(const char *name)

Load C string name as Fth source file if not already loaded and add name to global array *loaded-files*. Before loading source file run hook before-load-hook if not empty. If this hook returns #f, nothing is loaded and return value is FTH_FALSE. If loading finishes successfully, return value is FTH_TRUE, otherwise throw an exception. After loading source file run hook after-load-hook if not empty. If name has no file extension, FTH_FILE_EXTENSION ‘.fs' will be added. If name or name plus FTH_FILE_EXTENSION doesn't exist, try all path names from *load-path* with name.

void fth_unshift_load_lib_path(const char *path)

Prepend path to the beginning of global array variable *load-lib-path* if not already there.

void fth_unshift_load_path(const char *path)

Prepend path to the beginning of global array variable *load-path* if not already there.

Rest:

FTH fth_apropos(FTH regexp)

void fth_begin_values_to_obj(ficlVm *vm, char *name, FTH args)

FTH fth_find_in_wordlist(const char *name)

char* fth_parse_word(void)

char* fth_short_version(void)

char* fth_version(void)

FTH fth_word_ref(const char *name)

Find name in Forth dictionary and return ficlWord.

FTH fth_wordlist_each(bool (*func)(ficlWord *word, FTH data), FTH data)

Numbers

bool FTH_NUMBER_P(obj)

bool fth_number_p(obj)

Both return true if obj is any kind of a number, otherwise false.

bool FTH_FIXNUM_P(obj)

bool fth_fixnum_p(obj)

Both return true if obj is a fixnum, otherwise false.

bool FTH_LONG_LONG(obj)

bool FTH_INTEGER_P(obj)

bool fth_integer_p(obj)

All three return true if obj is an integer, otherwise false.

bool FTH_UNSIGNED_P(obj)

bool fth_unsigned_p(obj)

Both return true if obj is a unsigned integer, otherwise false.

bool FTH_OFF_T_P(obj)

Return true if obj is an off_t object, otherwise false.

bool FTH_UOFF_T_P(obj)

bool fth_uoff_t_p(obj)

Both return true if obj is an unsigned off_t object, otherwise false.

bool FTH_FLOAT_P(obj)

Return true if obj is a float object, otherwise false.

bool FTH_EXACT_P(obj)

bool fth_exact_p(obj)

Both return true if obj is an exact number, otherwise false.

ficlComplex(fth_complex_ref, FTH x)

Return C ficlComplex from x.

FTH fth_float_copy(FTH x)

ficlFloat fth_float_ref(FTH x)

Return C ficlFloat from x.

ficlFloat fth_float_ref_or_else(FTH x, ficlFloat fallback)

Return C ficlFloat from x. If x doesn't fit in Fixnum, FTH off_t, FTH float, FTH complex, or any bignum, return fallback.

ficlInteger fth_int_ref(FTH x)

Return C ficlInteger from x.

ficlInteger fth_int_ref_or_else(FTH x, ficlInteger fallback)

Return C ficlInteger from x. If x doesn't fit in Fixnum, FTH off_t, FTH float, FTH complex, or any bignum, return fallback.

bool fth_isinf(ficlFloat f)

bool fth_isnan(ficlFloat f)

ficl2Integer fth_long_long_ref(FTH x)

Return C ficl2Integer from x.

FTH fth_make_int(ficlInteger n)

Return a FTH fixnum or a FTH off_t object depending on n.

FTH fth_make_float(ficlFloat f)

Return a FTH float object from f.

FTH fth_make_long_long(ficl2Integer d)

Return a FTH fixnum or a FTH off_t object depending on d.

FTH fth_make_off_t(ficl2Integer d)

ficlFloat fth_real_ref(FTH x)

FTH fth_make_ulong_long(ficl2Unsigned ud)

Return a FTH unsigned fixnum or a FTH uoff_t object depending on ud.

FTH fth_make_unsigned(ficlUnsigned u)

Return a FTH unsigned fixnum or a FTH uoff_t object depending on u.

FTH fth_make_uoff_t(ficl2Unsigned ud)

FTH fth_off_t_copy(FTH obj)

ficl2Unsigned fth_ulong_long_ref(FTH x)

Return C ficl2Unsigned from x.

ficlUnsigned fth_unsigned_ref(FTH x)

Return C ficlUnsigned from x.

Random numbers:

ficlFloat fth_frandom(ficlFloat f)

Return -f f.

ficlFloat fth_random(ficlFloat f)

Return 0 ... f.

void fth_srand(ficlInteger n)

Complex numbers:

bool FTH_COMPLEX_P(obj)

Return true if obj is a complex object, otherwise false.

ficlComplex ficlStackPopComplex(ficlStack *stack)

void ficlStackPushComplex(ficlStack *stack, ficlComplex cp)

FTH fth_make_complex(ficlComplex z)

Return a FTH complex object from z.

FTH fth_make_polar(ficlFloat real, ficlFloat theta)

FTH fth_make_rectangular(ficlFloat real, ficlFloat image)

Big and rational numbers

bool FTH_BIGNUM_P(obj)

Return true if obj is a bignum object, otherwise false.

bool FTH_BIGFLOAT_P(obj)

Return true if obj is a bigfloat object, otherwise false.

bool FTH_RATIO_P(obj)

Return true if obj is a ratio object, otherwise false.

bool FTH_RAND_STATE_P(obj)

Return true if obj is a rand-state object, otherwise false.

FTH fth_denominator(FTH x)

Return denominator from x or 1.

FTH fth_exact_to_inexact(FTH x)

FTH fth_inexact_to_exact(FTH x)

FTH fth_make_bignum(ficlBignum bn)

FTH fth_make_bignum(FTH m)

FTH fth_make_ratio(FTH num, FTH den)

Return a FTH 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)

FTH fth_numerator(FTH x)

Return numerator from x or 0.

FTH fth_ratio_floor(FTH x)

FTH fth_rationalize(FTH x, FTH err)

Return inexact number within err of x.

FTH fth_number_add(FTH x, FTH y)

FTH fth_number_div(FTH x, FTH y)

bool fth_number_equal_p(FTH x, FTH y)

bool fth_number_less_p(FTH x, FTH y)

FTH fth_number_mul(FTH x, FTH y)

FTH fth_number_sub(FTH x, FTH y)

Objects

GC related functions:

void fth_gc_mark(FTH obj)

FTH fth_gc_off(void)

FTH fth_gc_on(void)

FTH fth_gc_permanent(FTH obj)

FTH fth_gc_protect(FTH obj)

Protect obj from garbage collection until fth_gc_unprotect.

FTH fth_gc_protect_set(FTH out, FTH in)

void fth_gc_unmark(FTH obj)

FTH fth_gc_unprotect(FTH obj)

Unprotect obj from garbage collection.

Object type related functions:

void* fth_instance_ref_gen(FTH obj)

Return GEN-struct of obj.

FTH fth_make_object_type(const char *name)

Add name to feature environment list, create a constant fth-name of object-type and return new object-type name.

FTH fth_make_object_type_from(const char *name, FTH base)

bool fth_object_type_p(FTH obj)

Instance related functions:

bool fth_instance_p(FTH obj)

FTH fth_make_instance(FTH obj, void *gen)

Return new instance of Object type obj with gen wrapped in.

bool fth_object_is_instance_of(FTH obj, FTH type)

Return true if obj is an instance of type, otherwise false.

Object set functions:

FTH fth_set_object_apply(FTH obj, void *apply, int req, int opt, int rest)

FTH fth_set_object_copy(FTH obj, FTH (*copy)(FTH obj))

FTH fth_set_object_dump(FTH obj, FTH (*dump)(FTH obj))

FTH fth_set_object_equal_p(FTH obj, FTH (*equal_p)(FTH obj1, FTH obj2))

FTH fth_set_object_free(FTH obj, void (*free)(FTH obj))

FTH fth_set_object_inspect(FTH obj, FTH (*inspect)(FTH obj))

FTH fth_set_object_length(FTH obj, FTH (*length)(FTH obj))

FTH fth_set_object_mark(FTH obj, void (*mark)(FTH obj))

FTH fth_set_object_to_array(FTH obj, FTH (*to_array)(FTH obj))

FTH fth_set_object_to_string(FTH obj, FTH (*to_string)(FTH obj))

FTH fth_set_object_value_ref(FTH obj, FTH (*value_ref)(FTH obj, FTH index))

FTH fth_set_object_value_set(FTH obj, FTH (*value_set)(FTH obj, FTH index, FTH value))

Object functions:

FTH fth_object_apply(FTH obj, FTH args)

FTH fth_object_copy(FTH obj)

FTH fth_object_dump(FTH obj)

bool fth_object_empty_p(FTH obj)

bool fth_object_equal_p(FTH obj1, FTH obj2)

Test if obj1 is equal obj2.

FTH fth_object_find(FTH obj, FTH key)

FTH fth_object_index(FTH obj, FTH key)

FTH fth_object_inspect(FTH obj)

ficlInteger fth_object_length(FTH obj)

bool fth_object_member_p(FTH obj, FTH key)

char* fth_object_name(FTH obj)

bool fth_object_range_p(FTH obj, ficlInteger index)

FTH fth_object_sort(FTH obj, FTH proc)

FTH fth_object_to_array(FTH obj)

FTH fth_object_to_string(FTH obj)

Return Fth string representation of obj.

FTH fth_object_to_string_2(FTH obj)

Like fth_object_to_string but if obj is a string, wrap string to "string".

FTH fth_object_value_ref(FTH obj, ficlInteger index)

FTH fth_object_value_set(FTH obj, ficlInteger index, FTH value)

char* fth_to_c_dump(FTH obj)

char* fth_to_c_inspect(FTH obj)

char* fth_to_c_string(FTH obj)

char* fth_to_c_string_2(FTH obj)

If obj is a string, wrap string to "string".

Cycle through objects:

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)

Stack access functions:

FTH ficl_to_fth(FTH obj)

FTH fth_pop_ficl_cell(ficlVm *vm)

void fth_push_ficl_cell(ficlVm *vm, FTH obj)

FTH fth_to_ficl(FTH obj)

Ports

void fth_port_close(FTH port)

Close port; if port is FTH_FALSE, do nothing.

void fth_port_display(FTH port, FTH obj)

Put string representation of Fth object obj to output port port. If port is FTH_FALSE, print to standard out.

void fth_port_flush(FTH port)

Flush port; if port is FTH_FALSE, do nothing.

int fth_port_getc(FTH port)

char* fth_port_gets(FTH port)

void fth_port_putc(FTH port, int c)

void fth_port_puts(FTH port, const char *str)

Put C string str to output port port. If port is FTH_FALSE, print to standard out.

out_cb fth_set_error_cb(out_cb cb)

out_cb fth_set_print_and_error_cb(out_cb cb)

out_cb fth_set_print_cb(out_cb cb)

in_cb fth_set_read_cb(in_cb cb)

FTH fth_port_to_string(FTH port)

Return content of port as Fth string. If port is FTH_FALSE, return FTH_FALSE.

Printf

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 conversions prepend a zero before output, for x and X conversions prepend a ‘0x' respective ‘0X' before output. For a, A, e, E, f, F, g and G conversions the result will always have a decimal point.

‘-'

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

aAeEfFgG

Floating point output like sprintf(3).

bBdoOpuUxX

Integer output in binary, decimal, octal, void pointer, unsigned and hexadecimal form.

c

Single character output.

D

Dump string output of any Forth object with object-dump.

I

Inspect string output of any Forth object with object-inspect.

M

String representation of any Forth object with object->string, in addition, strings will be enclosed in double quotations ("string").

qQs

C string char * output.

S

String representation of any Forth object with object->string.

int fth_asprintf(char **result, const char *fmt, ...)

int fth_debug(const char *fmt, ...)

int fth_error(const char *str)

int fth_errorf(const char *fmt, ...)

char* fth_format(const char *fmt, ...)

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_port_vprintf(FTH port, const char *fmt, va_list ap)

int fth_print(const char *str)

int fth_printf(const char *fmt, ...)

int fth_snprintf(char *buffer, size_t size, const char *fmt, ...)

int fth_sprintf(char *buffer, const char *fmt, ...)

int fth_vasprintf(char **result, const char *fmt, va_list ap)

int fth_verrorf(const char *fmt, va_list ap)

char* fth_vformat(const char *fmt, va_list ap)

int fth_vfprintf(FILE *fp, const char *fmt, va_list ap)

int fth_vioprintf(FTH io, const char *fmt, va_list ap)

int fth_vprintf(const char *fmt, va_list ap)

int fth_vsnprintf(char *buffer, size_t size, const char *fmt, va_list ap)

int fth_vsprintf(char *buffer, const char *fmt, va_list ap)

int fth_warning(const char *fmt, ...)

Procs

bool FTH_PROC_P(obj)

Return true if obj is a proc object, otherwise false.

bool FTH_WORD_P(obj)

Return true if obj is a ficlWord, otherwise false.

ficlWord* fth_define_procedure(const char *name, FTH (*func)(), int req, int opt, int rest, const char *doc)

Return new ficlWord name tied to C function func with req required arguments, opt optional arguments and rest (true) or no rest (false) 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)

Return new ficlWord name tied to C function func with req required arguments, opt optional arguments and rest (true) or no rest (false) 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)

Return documentation property string of obj or FTH_FALSE.

void fth_documentation_set(FTH obj, FTH doc)

Set documentation property string of any obj to doc.

FTH fth_get_optarg(ficlInteger req, FTH def)

FTH fth_get_optkey(FTH key, FTH def)

ficl2Integer fth_get_optkey_2int(FTH key, ficl2Integer def)

ficlInteger fth_get_optkey_int(FTH key, ficlInteger def)

int fth_get_optkey_fix(FTH key, int def)

char* fth_get_optkey_str(FTH key, char *def)

FTH fth_make_proc(ficlWord *word, int req, int opt, bool rest)

FTH fth_make_proc_from_func(const char *, FTH (*)(), bool, int, int, bool)

FTH fth_proc_apply(FTH proc, FTH args, const char *caller)

If proc is a Proc object, execute its ficlWord with Array object args as arguments on stack. caller can be any C string used for error message. Raise bad-arity exception if proc has more required arguments than len. Raise eval-error exception if an error occured during evaluation.

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

int fth_proc_arity(FTH proc)

If proc is a Proc object, return required arguments as C int, otherwise return 0.

FTH fth_proc_call(FTH proc, const char *caller, int len, ...)

If proc is a Proc object, execute its ficlWord with len arguments on stack. caller can be any C string used for error message. Raise bad-arity exception if proc has more required arguments than len. Raise eval-error exception if an error occured during evaluation.

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

char* fth_proc_name(FTH obj)

If obj is a ficlWord, return name as C string, otherwise return "not-a-proc".

FTH fth_proc_source_ref(FTH proc)

Return source string property of proc, or FTH_FALSE if not available.

void fth_proc_source_set(FTH proc, FTH source)

Set source string property of proc to source.

ficlWord* fth_proc_to_xt(FTH proc)

FTH fth_source_file(FTH obj)

FTH fth_source_line(FTH obj)

FTH fth_source_ref(FTH obj)

void fth_source_set(FTH obj, FTH source)

ficlWord* fth_word_doc_set(ficlWord *word, const char *str)

FTH proc_from_proc_or_xt(FTH proc_or_xt, int req, int opt, bool rest)

Define Variables

FTH fth_define(const char *name, FTH value)

Define constant name to value which can be a FTH Fixnum (in contrast to fth_define_constant below) or any other FTH object. Return value.

FTH fth_define_constant(const char *name, FTH value, const char *doc)

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

Define 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. Return value.

bool fth_defined_p(const char *name)

Return true if name is defined in the dictionary, otherwise false.

void fth_trace_var(FTH obj, FTH proc_or_xt)

FTH fth_trace_var_execute(ficlWord *word)

void fth_untrace_var(FTH obj)

FTH fth_var_ref(FTH obj)

FTH fth_var_set(FTH obj, FTH 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 if not existing) global variable name to value. Return value.

Regexp object type

bool FTH_REGEXP_P(obj)

Return true if obj is a regexp object, otherwise false.

FTH fth_make_regexp(const char *reg)

Return new regexp object from reg which may contain regular expression.

int fth_regexp_find(const char *reg, const char *str)

Return match index or -1 if not found.

ficlInteger fth_regexp_match(FTH regexp, FTH string)

Return match length or -1 if not found.

FTH fth_regexp_replace(FTH regexp, FTH string, FTH replace)

Replace 1st occurrence of regexp in string with replace if found. References \1 to \9 in replace will be replaced by corresponding subexpressions. If no corresponding subexpression exist, an regexp-error exception will be raised.

ficlInteger fth_regexp_search(FTH regexp, FTH string, ficlInteger start, ficlInteger range)

Return match index or -1 if not found. If range is -1, search entire string.

String object type

bool FTH_STRING_P(obj)

Return true if obj is a string object, otherwise false.

bool FTH_CHAR_P(obj)

bool fth_char_p(obj)

Both return true if obj is an ASCII character, otherwise false.

FTH fth_make_empty_string(void)

FTH fth_make_string(const char *str)

Return a new Fth string object constructed from C string str.

FTH fth_make_string_format(const char *fmt, ...)

FTH fth_make_string_len(const char *str, ficlInteger len)

Return a new Fth string object constructed from C string str with at most len characters.

FTH fth_make_string_or_false(const char *str)

FTH fth_string_append(FTH string1, FTH string2)

FTH fth_string_capitalize(FTH string)

FTH fth_string_char_ref(FTH string, ficlInteger index)

FTH fth_string_char_set(FTH string, ficlInteger index, FTH value)

FTH fth_string_chomp(FTH string)

FTH fth_string_copy(FTH string)

char fth_string_c_char_ref(FTH string, ficlInteger index)

char fth_string_c_char_set(FTH string, ficlInteger index, char c)

FTH fth_string_delete(FTH string, ficlInteger index)

FTH fth_string_downcase(FTH string)

bool fth_string_equal_p(FTH obj1, FTH obj2)

int fth_string_eval(FTH string)

FTH fth_string_fill(FTH string, FTH fill_char)

FTH fth_string_find(FTH string, FTH key)

FTH fth_string_format(FTH string, FTH args_list)

bool fth_string_greater_p(FTH obj1, FTH obj2)

FTH fth_string_index(FTH string, FTH key)

FTH fth_string_insert(FTH string, ficlInteger index, FTH value)

ficlInteger fth_string_length(FTH string)

bool fth_string_less_p(FTH obj1, FTH obj2)

bool fth_string_member_p(FTH string, FTH key)

bool fth_string_not_equal_p(FTH obj1, FTH obj2)

FTH fth_string_pop(FTH string)

FTH fth_string_push(FTH string, FTH add_str)

char* fth_string_ref(FTH string)

Return C string from Fth string or NULL.

FTH fth_string_replace(FTH string, FTH from, FTH to)

FTH fth_string_reverse(FTH string)

FTH fth_string_scat(FTH string, const char *str)

FTH fth_string_sformat(FTH string, const char *fmt, ...)

FTH fth_string_shift(FTH string)

FTH fth_string_sncat(FTH string, const char *str, ficlInteger len)

FTH fth_string_split(FTH string, FTH sep_str)

FTH fth_string_substring(FTH string, ficlInteger start, ficlInteger end)

FTH fth_string_to_array(FTH string)

FTH fth_string_unshift(FTH string, FTH add_str)

FTH fth_string_upcase(FTH string)

FTH fth_string_vformat(const char *fmt, FTH args)

FTH fth_string_vsformat(FTH string, const char *fmt, va_list ap)

Symbols

bool FTH_SYMBOL_P(obj)

Return true if obj is a symbol, otherwise false.

bool fth_string_or_symbol_p(FTH obj)

char* fth_string_or_symbol_ref(FTH obj)

FTH fth_symbol(const char *name)

Return value, the word address, of symbol name; if symbol doesn't exist, creat it.

bool fth_symbol_equal_p(FTH obj1, FTH obj2)

bool fth_symbol_p(const char *name)

char* fth_symbol_ref(FTH obj)

Return C string name of symbol obj without first sign (') or NULL.

Keywords

bool FTH_KEYWORD_P(obj)

Return true if obj is a keyword, otherwise false.

FTH fth_keyword(const char *name)

Return value, the word address, of keyword name; if keyword doesn't exist, creat it.

bool fth_keyword_equal_p(FTH obj1, FTH obj2)

bool fth_keyword_p(const char *name)

char* fth_keyword_ref(FTH obj)

Exceptions

bool FTH_EXCEPTION_P(obj)

Return true if obj is an exception, otherwise false.

FTH fth_exception(const char *name)

Return a new Exception object name.

bool fth_exception_equal_p(FTH obj1, FTH obj2)

FTH fth_exception_last_message_ref(FTH exc)

void fth_exception_last_message_set(FTH exc, FTH msg)

FTH fth_exception_message_ref(FTH exc)

void fth_exception_message_set(FTH exc, FTH msg)

char* fth_exception_ref(FTH obj)

FTH fth_make_exception(const char *name, const char *message)

bool fth_symbol_or_exception_p(FTH obj)

FTH fth_symbol_or_exception_ref(FTH obj)

FTH fth_symbol_to_exception(FTH obj)

Utilities

void* fth_calloc(size_t size, size_t eltsize)

int fth_evaluate(ficlVm *vm, const char *buffer)

int fth_execute_xt(ficlVm *vm, ficlWord *word)

void fth_free(void *p)

char* fth_getenv(const char *name, char *def)

void* fth_malloc(size_t size)

void* fth_realloc(void *p, size_t size)

void fth_repl(int argc, char **argv)

char* fth_strcat(char *d, size_t size, const char *s)

Append s to d but doesn't exceed entire size - 1; append terminating ‘\0'.

char* fth_strcpy(char *d, size_t size, const char *s)

Copy s to d but not more than size - 1 chars; append terminating ‘\0'.

char* fth_strdup(const char *s)

char* fth_strerror(int n)

size_t fth_strlen(const char *s)

char* fth_strncat(char *d, size_t size, const char *s, size_t count)

Append count chars from s to d but doesn't exceed entire size - 1; append terminating ‘\0'.

char* fth_strncpy(char *d, size_t size, const char *s, size_t count)

Copy count chars from s to d but not more than size - 1 chars; append terminating ‘\0'.

void fth_throw(FTH exc, const char *fmt, ...)

void fth_throw_error(FTH exc, FTH args)

Throw exception exc with text built from args. If args is not an array, its string representation is used. If args is FTH_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 like fth_throw_error except for replacing format signs ~A and ~S with %s.

char* pop_cstring(ficlVm *vm)

char* pop_forth_string(ficlVm *vm)

void push_cstring(ficlVm *vm, char *s)

void push_forth_string(ficlVm *vm, char *string)