Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIBFTH(3)	       FreeBSD Library Functions Manual		     LIBFTH(3)

NAME
     libfth -- Forth script and	extension language library

LIBRARY
     library "libfth"

SYNOPSIS
     #include <fth.h>

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

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

   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 back-
	  ward.	 Raise an 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 an 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), other-
	  wise 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, oth-
	  erwise 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	back-
	  ward.	 Raise an 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 an 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 a 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 argu-
	  ments	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)

     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 al-
	  ready	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 a 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 success-
	  fully, return	value is FTH_TRUE, otherwise throw an exception.  Af-
	  ter 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,	noth-
	  ing is loaded	and return value is FTH_FALSE.	If loading finishes
	  successfully,	return value is	FTH_TRUE, otherwise throw an excep-
	  tion.	 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	printf(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_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
     bool 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
     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 er-
	  ror message.	Raise a	bad-arity exception if proc has	more required
	  arguments than len.  Raise an	eval-error exception if	an error oc-
	  cured	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
	  single value on stack, return	it, if proc leaves more	than one val-
	  ues 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,	other-
	  wise 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 a
	  bad-arity exception if proc has more required	arguments than len.
	  Raise	an 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
	  single value on stack, return	it, if proc leaves more	than one val-
	  ues 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 avail-
	  able.
     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 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.  Raise an
	  eval-error exception if an error occured during evaluation.

	  If the xt with name doesn't leave a return value on stack, return
	  FTH_FALSE, if	a single value remains on stack, return	it, if more
	  than one values remain on stack, return 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.  Raise an	eval-error ex-
	  ception if an	error occured during evaluation.

	  If the xt with name doesn't leave a return value on stack, return
	  FTH_FALSE, if	a single value remains on stack, return	it, if more
	  than one values remain on stack, return 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"
     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 un-
	  touched.
     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 con-
	  stants 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.  Re-
	  turn 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 expres-
	  sion.
		FTH fs = fth_make_string("foobar");
		FTH re = fth_make_regexp("bar");
		fth_regexp_search(re, fs, 0, -1); => 3

		FTH fs = fth_make_string("foobar");
		FTH re = fth_make_regexp("(B|b)+");
		fth_regexp_search(re, fs, 0, -1); => 3
     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 fs = fth_make_string("foobar");
		FTH re = fth_make_regexp("foo");
		fth_regexp_match(re, fs); => 3

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

		FTH fs = fth_make_string("foobar");
		FTH re = fth_make_regexp(".*(bar)");
		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)
	  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.
		FTH fs = fth_make_string("foobar");
		FTH re = fth_make_regexp("(bar)");
		FTH rp = fth_make_string("BAR");
		fth_regexp_replace(re, fs, rp);	=> "fooBAR"

		FTH fs = fth_make_string("foo-bar");
		FTH re = fth_make_regexp("(foo)");
		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)
	  Return match index or	-1 if not found.  If range is -1, search en-
	  tire string.
		FTH fs = fth_make_string("foobar");
		FTH re = fth_make_regexp("foo");
		fth_regexp_search(re, fs, 0, 2); => 0 (means #t)

		FTH fs = fth_make_string("foobar");
		FTH re = fth_make_regexp("(bar)");
		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

   String object type
     bool FTH_STRING_P(obj)
	  Return true if obj is	a Fth string object, otherwise false.
		FTH fs = fth_make_string("hello");
		FTH_STRING_P(fs); => 1
		FTH fs = FTH_NIL;
		FTH_STRING_P(fs); => 0
     bool FTH_CHAR_P(obj)
     bool fth_char_p(obj)
	  Both return true if obj is an	ASCII character, otherwise false.
		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)
	  Return a Fth string object of	length 0.
		FTH fs = fth_make_empty_string(); => ""
		fth_string_length(fs); => 0
     FTH fth_make_string(const char *str)
	  Return a new Fth string object constructed from C string str.	 If C
	  string is "" or NULL,	return Fth string "" 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, ...)
	  Return a Fth string object according to the extended printf(3) fmt
	  args.	 The extensions	are:
	  I fth_to_c_inspect
	       print inspect string of any Fth object.
	  S fth_to_c_string
	       print string representation of any Fth object.
	  M fth_to_c_string_2
	       as fth_to_c_string but encloses strings in double quotes.
	  D fth_to_c_dump
	       print 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)
	  Return a new Fth string object constructed from C string str with at
	  most len characters.	If the C string	str is shorter than len, re-
	  turn a Fth 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 "", return #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 false)
     FTH fth_string_append(FTH string1,	FTH string2)
	  Return 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)
	  Return the string, not a copy, changed to first char upcase and the
	  rest downcase.
		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)
	  Return character as C	char at	position index;	negative index counts
	  from backward.  Raise	an 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)
	  Store	C char character c at position index; negative index counts
	  from backward.  Raise	an 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)
	  Return character as FTH object at position index; negative index
	  counts from backward.	 Raise an 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)
	  Store	Fth object character ch	at position index; negative index
	  counts from backward.	 Raise an 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)
	  Return 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)
	  Return a new copy of the Fth 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)
	  Delete and return character at position index	from string; negative
	  index	counts from backward.  Raise an	out-of-range exception if in-
	  dex 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)
	  Return the string, not a copy, changed to all	chars downcase.
		FTH fs = fth_make_string("Foo");
		fth_string_downcase(fs); => "foo"
		fth_printf("%S", fs); => "foo"
     bool fth_string_equal_p(FTH obj1, FTH obj2)
	  Compare two strings with strcmp(3) and return	true for equal and
	  false	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 fill_char)
	  Fill string with fill_char and return	changed	Fth 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)
	  Return match if string or regexp key exist 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_list)
	  Return a formatted string created from the extended printf(3)	format
	  string string	and possible arguments in args_list.  args_list	can be
	  an array, any	single object, FTH_FALSE or FTH_NIL.  If args_list is
	  an array, it should have as many elements as required	by the format
	  string, if args_list is a single object, the format string should
	  only have one	format sign, if	args_list is FTH_FALSE or FTH_NIL,
	  args_list is ignored and the format string itself is returned.  If
	  string is the	empty string, an empty string is returned, no matter
	  what's in args_list.	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); =>	""
     bool fth_string_greater_p(FTH obj1, FTH obj2)
	  Compare two strings with strcmp(3) and return	true for greater than
	  and false 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)
	  Return 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	(false)
     FTH fth_string_insert(FTH string, ficlInteger index, FTH value)
	  Insert string	representation of value	to string at position index;
	  negative index counts	from backward.	Raise an out-of-range excep-
	  tion 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)
	  Return length	of a Fth string	object or -1 if	not a Fth string ob-
	  ject.
		FTH fs = fth_make_string("hello");
		fth_string_length(fs); => 5
		fth_string_length((FTH)5); => -1 (means	false)
     bool fth_string_less_p(FTH	obj1, FTH obj2)
	  Compare two strings with strcmp(3) and return	true for less than and
	  false	for greater then.
		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
     bool fth_string_member_p(FTH string, FTH key)
	  Return true if string	key exist in string, otherwise false.
		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
     bool fth_string_not_equal_p(FTH obj1, FTH obj2)
	  Compare two strings with strcmp(3) and return	true for not equal and
	  false	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)
	  Remove and return last character of string.  If string is empty, re-
	  turn #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 add_str)
	  Append string	representation of add_str to string and	return changed
	  Fth 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)
	  Return C string from Fth string or NULL if not a Fth 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)
	  Return the string, not a copy, replaced from with to.	 If to is the
	  empty	string,	delete 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)
	  Return the same Fth 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 Fth 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 Fth 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)
	  Remove and return first character of string.	If string is empty,
	  return #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	Fth string ob-
	  ject string.
		FTH fs = fth_make_empty_string(); => ""
		fth_string_sncat(fs, ",	 ", 2);	=> "hello, "
     FTH fth_string_split(FTH string, FTH sep_str)
	  Split	string using sep_str as	delimiter and return result as array
	  of strings.  If sep_str is not a string or regexp, delimiter is
	  space.
		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)
	  Return new string from position start	to, but	excluding, position
	  end; negative	index counts from backward.  Raise an out-of-range ex-
	  ception 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, -4, -2); => "or"
		fth_string_substring(fs, -4, fth_string_length(fs)); =>	"orld"
     FTH fth_string_to_array(FTH string)
	  Convert 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 add_str)
	  Prepends string representation of add_str to string and return
	  changed Fth 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)
	  Return the string, not a copy, changed to all	chars upcase.
		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)
	  Return formatted Fth string 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.

   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; ap-
	  pend 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 el-
	  ement	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)
     void push_cstring(ficlVm *vm, char	*s)
     int fth_set_argv(int from,	int to,	char **argv)

ENVIRONMENT
     FTH_DICTIONARY_SIZE
	  Overwrite default dictionary size (1024 * 1024).
     FTH_LOCALS_SIZE
	  Overwrite default number of locals (2048).
     FTH_RETURN_SIZE
	  Overwrite default size of return stack (1024).
     FTH_STACK_SIZE
	  Overwrite default size of parameter stack (8192).

SEE ALSO
     fth(1), printf(3),	strcmp(3).

     The Clang Team, Clang Compiler User's Manual,
     http://clang.llvm.org/docs/UsersManual.html.

HISTORY
     This manual page describes	version	1.4.1.	libfth is based	on Ficl,
     Forth-inspired command language, version 4.0.31 written by	John Sadler.

AUTHORS
     libfth and	this manual page was written by	Michael	Scholz
     <mi-scholz@users.sourceforge.net>.

BUGS
     Please report bugs	to the author.

FreeBSD	13.0		      September	23, 2021		  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | ENVIRONMENT | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libfth&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help